# Run Atlas Headless in CI for Django Projects in 2026 > Django developers can run Atlas headless in CI using `atlas run --format json` to automate code changes and receive machine-readable output for pipeline integration. Django developers in 2026 can run Atlas headless in CI pipelines by invoking `atlas run` with a specific prompt, ensuring machine-readable output by passing the `--format json` flag. This approach integrates Atlas directly into your existing `pytest-django` test suite and `uv` package management workflows, allowing for automated code generation and review within your continuous integration environment. ## Key takeaways - Run Atlas headless in Django CI using `atlas run` for non-interactive automation. - Obtain machine-readable output with `atlas run --format json` for pipeline parsing. - Pre-approve Atlas tools like `bash`, `read`, `edit`, `todowrite` for headless Django tasks. - Resume or fork Atlas sessions in CI using `--continue` or `--fork` for multi-stage Django workflows. - Atlas indexes Django code by AST declarations, not blind line windows. - Validate Atlas changes in Django with `pytest-django` and format with `ruff format`. ## How to run Atlas headless in Django CI pipelines In 2026, Django developers can run Atlas headless in CI pipelines by using the `atlas run` command, which is specifically designed for non-interactive execution. This command sends a single prompt, streams events to stdout, and exits when the session goes idle, making it ideal for automated environments. Running Atlas headless in a Django CI pipeline in 2026 involves invoking the `atlas run` command within your project's root directory, where the `manage.py` file resides. This command's default mode is non-interactive, meaning it processes a single prompt, streams all session events to standard output, and then gracefully exits once the session becomes idle. This behavior is crucial for CI environments, as it prevents indefinite waits and ensures that pipeline steps can proceed or fail predictably. For instance, a CI job might use `atlas run "Add a new field 'status' to the `Order` model in `myapp/models.py` with a default value and generate the migration."` to automate a common Django development task. Atlas will then read your Django apps, models, and settings, build its code index using AST declarations and local Ollama embeddings, and propose changes. The output stream can be captured by subsequent pipeline steps for analysis or logging. ## How to get machine-readable output from Atlas in Django CI To obtain machine-readable output from Atlas in a Django CI pipeline, developers in 2026 should use the `--format json` flag with the `atlas run` command. This flag ensures that the event stream is formatted as raw JSON, enabling downstream pipeline steps to parse and act upon the data programmatically. When integrating Atlas into a Django CI pipeline, obtaining structured, machine-readable output is essential for automated processing. The `atlas run` command supports the `--format json` flag, which transforms the standard event stream into a raw JSON format. This allows a subsequent CI step to easily parse Atlas's actions, proposed changes, and session status. For example, after Atlas has been asked to 'write a test for the `User` model in `myapp/models.py` using `pytest-django`,' the JSON output could be parsed to extract the unified diff for the new test file. This diff, computed by Atlas for every file edit, can then be used by a custom script to verify changes or integrate with other reporting tools. This capability is vital for automating tasks like reviewing generated migrations or validating new `pytest-django` test cases without human intervention. ## How to configure permissions for headless Atlas in Django CI In 2026, running Atlas headless in a Django CI environment requires pre-approving the necessary tools through the permission configuration, as there is no interactive user to answer 'ask' prompts. Atlas's permission-gated tool calls ensure that actions like `edit` or `todowrite` are only executed with explicit authorization. For a headless Atlas session in a Django CI pipeline, pre-approving tool usage is a critical safety measure. Atlas's architecture includes permission-gated tool calls, which means every tool invocation is checked against `allow`, `ask`, and `deny` rules before execution. Since a headless run has no interactive user to respond to an 'ask' prompt, all required tools must be explicitly `allow`-listed in the Atlas configuration. For a typical Django development task, such as asking Atlas to 'add a model field with a migration,' tools like `bash` (for running `python manage.py makemigrations`), `read` (for reading Django model files), `edit` (for modifying `models.py`), and `todowrite` (for creating migration files) would need to be pre-approved. This ensures that Atlas can perform its work, such as generating a new migration file in `myapp/migrations/`, without stalling the CI pipeline due to an unanswered permission prompt. ## How to resume or fork Atlas sessions in Django CI Django developers in 2026 can resume or fork prior Atlas sessions within CI pipelines using the `--continue`, `--session`, or `--fork` flags. This functionality allows a pipeline step to build upon an earlier run, for example, by continuing a complex refactoring task across multiple CI jobs or replaying a specific session for debugging. The ability to resume or fork Atlas sessions is valuable for managing complex or multi-stage tasks within a Django CI pipeline. The `--continue` flag allows a new `atlas run` command to pick up where a previous session left off, using the same session ID. Alternatively, `--session ` can be used to explicitly specify a session to resume. The `--fork` flag creates a new session based on an existing one, allowing for experimentation or parallel development branches from a known state. This is particularly useful in Django projects where a long-running task, such as refactoring a large set of views or models, might be broken into several CI stages. For instance, one CI job might use Atlas to 'refactor `myapp/views.py` to use class-based views,' and a subsequent job could `--continue` that session to 'write `pytest-django` tests for the refactored views,' ensuring continuity and efficiency in the development workflow. ## Steps 1. Initialize Atlas in your Django project: Ensure Atlas is set up in your Django project by running it once interactively or by confirming the presence of an Atlas configuration. Atlas needs to read your Django apps, models, and settings, typically by being run in the directory containing `manage.py`. 2. Configure Atlas permissions for headless execution: Edit your Atlas configuration to `allow` the necessary tools for your CI job, such as `bash`, `read`, `edit`, and `todowrite`. This prevents Atlas from pausing for permission prompts in a non-interactive environment. 3. Craft a specific prompt for Atlas: Define a clear, actionable prompt for Atlas, such as "Add a new field `is_active` to the `Product` model in `myapp/models.py` with a default of `True` and generate the corresponding migration." 4. Invoke `atlas run` with the prompt and JSON output: Execute `atlas run "Your specific prompt here." --format json --model github/gpt-4-turbo` within your CI pipeline. Explicitly setting the model in `provider/model` form is required for headless runs. 5. Parse the JSON output in a subsequent CI step: Capture the standard output from `atlas run` and use a scripting language (e.g., Python) to parse the JSON event stream. Extract relevant information like unified diffs for files modified by Atlas, such as `myapp/models.py` or new migration files in `myapp/migrations/`. 6. Run Django tests with `pytest-django`: After Atlas has made changes, execute your Django test suite using `uv run pytest` or `pytest --ds=your_project.settings` to validate the modifications. For example, `uv run pytest myapp/tests/` will run tests for a specific app. 7. Format code with `ruff format`: Ensure code style consistency by running `ruff format .` across your Django project after Atlas has introduced or modified files. ## FAQ ### How do I run Atlas in a Django project's CI pipeline? In 2026, run `atlas run` within your Django project's root directory, where `manage.py` is located. This command's default non-interactive mode sends a single prompt, streams events, and exits when idle, making it suitable for CI. ### Can Atlas generate Django migrations in CI? Yes, Atlas can generate Django migrations. You would prompt Atlas to "add a model field with a migration" and ensure the `bash`, `read`, `edit`, and `todowrite` tools are pre-approved in your Atlas configuration for headless execution. ### How do I get structured output from Atlas for CI automation in Django? Use the `--format json` flag with `atlas run`. This outputs a raw JSON event stream that can be parsed by subsequent CI steps to extract unified diffs or other structured data from Atlas's actions on your Django codebase. ### What Django tools does Atlas integrate with in CI? Atlas integrates with core Django project structures, reading apps, models, and settings. In CI, it works alongside your `pytest-django` test runner for validation, `uv` for package management, and `ruff format` for code style. ### How does Atlas handle permissions for file changes in a headless Django CI run? Atlas uses permission-gated tool calls. For headless runs, you must pre-approve tools like `edit` and `todowrite` in your Atlas configuration with `allow` rules, as there's no interactive user to grant permissions. ### Can I resume a failed Atlas session in a Django CI pipeline? Yes, you can resume a prior Atlas session using `atlas run --continue` or `atlas run --session `. This allows a CI pipeline step to pick up from an earlier run, building on previous work or replaying a specific session. ### How does Atlas ensure code quality for Django changes in CI? Atlas computes a unified diff for every file edit, which can be surfaced for approval. After Atlas makes changes, your CI pipeline should run `uv run pytest` with `pytest-django` to validate functionality and `ruff format .` to maintain code style. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-django Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-django` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.