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.
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 <session_id>` 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.
Step by step
- 01Initialize 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`.
- 02Configure 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.
- 03Craft 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."
- 04Invoke `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.
- 05Parse 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/`.
- 06Run 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.
- 07Format code with `ruff format`: Ensure code style consistency by running `ruff format .` across your Django project after Atlas has introduced or modified files.
Frequently asked questions
- 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 <session_id>`. 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.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Run Atlas Headless in CI with Atlas (2026 Workflow)
How to run Atlas headless in CI in 2026: atlas run sends one prompt and exits when the session goes idle, with --format json, --command, and --continue for pipeline steps.
Atlas for Django in 2026
Atlas, the terminal-native AI coding agent, empowers Django developers in 2026. Boost productivity across models, views, and migrations with secure, reviewable AI assistance.
Refactor a legacy module in Django with Atlas in 2026
Streamline legacy Django modules in 2026 with Atlas. Safely restructure code, maintain behavior, and prevent breaking changes using `pytest-django`, `uv`, and `ruff format`.
Onboard to an Unfamiliar Codebase in Django with Atlas (2026)
How to onboard to an unfamiliar Django codebase in 2026 with Atlas: codebase_search, glob, the read-only explore subagent, uv, pytest-django, and ruff format.
Self-review your working diff before committing in Django with Atlas in 2026
Catch your own mistakes in Django code before committing. Atlas helps Django developers self-review uncommitted diffs, run pytest-django tests, and apply ruff format in 2026.
Locate Where a Behavior Is Implemented in Django with Atlas (2026)
Find the Django view, model, or signal behind a behavior in 2026: Atlas attacks it with codebase_search, grep, and the lsp tool, then confirms with pytest-django.
Extract a Shared Helper from Duplicated Code in Django with Atlas in 2026
In 2026, Django developers use Atlas to find and refactor duplicated logic into shared helpers. Leverage semantic search, automated patching, and `pytest-django` for safe, efficient code consolidation.
Research a Third-Party API Before Integrating It in Django with Atlas in 2026
Streamline Django API integrations in 2026. Atlas helps developers research external APIs, fetch documentation, and write robust Django code, ensuring compliance with project conventions and safety protocols.