# Run Atlas Headless in CI for Go Developers in 2026 > Go developers can run Atlas headless in CI using `atlas run --format json` to get machine-readable output for automated code changes and testing with `go test`. To run an Atlas session non-interactively in a Go CI pipeline and retrieve machine-readable output, developers in 2026 can invoke `atlas run` with the `--format json` flag, allowing integration with `go test` and `go mod` for automated code generation and verification. ## Key takeaways - `atlas run` provides non-interactive execution for Go CI pipelines. - `--format json` delivers machine-readable output for automated Go processing. - Pre-approve Atlas tools like `edit` and `bash` for headless Go workflows. - Atlas integrates direct with `go mod`, `go test`, and `gofmt` for Go development. - Session management (`--continue`, `--fork`) supports complex, multi-stage Go tasks. - Atlas uses `git` for diffing, staging, and rolling back Go code changes. ## How to run Atlas non-interactively in a Go CI pipeline In 2026, Go developers can execute Atlas non-interactively within their CI pipelines by using the `atlas run` command. This command is designed for headless operation, sending a single prompt and exiting once the session becomes idle, making it ideal for automated Go module tasks. When integrating Atlas into a Go CI pipeline, the primary command is `atlas run`. This command's default behavior is non-interactive: it accepts a single prompt as an argument, streams events to standard output, and then exits when the session goes idle. This design ensures that Atlas can perform tasks such as adding table-driven tests or refactoring a Go interface without requiring human intervention. For instance, a pipeline step might invoke `atlas run "add a new test case to the `database/sql` package in `main.go`"` within a Go module, where Atlas can read existing Go packages, interfaces, and `go.sum` dependencies. Atlas will then draft a plan in a read-only plan agent and ask for approval before switching to a build agent, even in a headless context, which requires pre-approval through permission configuration. ## How to get JSON output from Atlas for Go CI automation For Go CI pipelines requiring structured data, Atlas in 2026 offers the `--format json` flag with `atlas run`. This option streams raw event data to standard output, enabling subsequent pipeline steps to parse machine-readable JSON instead of human-readable prose, which is crucial for automated Go module processing. To enable automated processing of Atlas's output in a Go CI pipeline, developers must pass the `--format json` flag to `atlas run`. This ensures that Atlas streams its events as raw JSON objects to standard output, rather than formatted prose. A subsequent Go program or script in the pipeline can then parse this JSON stream to extract information, verify changes, or trigger further actions, such as running `go test` on the generated diff. It is also critical to explicitly set the model using the `provider/model` form, for example, `atlas run --format json --model github/copilot "refactor the `User` struct in `models/user.go`"`. This ensures the correct model and provider are used for the Go codebase, as the GitHub path specifically requires this format and rejects anything else. ## How to manage Atlas tool permissions for headless Go CI In 2026, running Atlas headless in a Go CI environment necessitates pre-approving tools via the permission configuration. Since there is no interactive user to answer 'ask' prompts, all necessary tools like `bash`, `read`, `edit`, and `todowrite` must be explicitly allowed to ensure the Go workflow proceeds without interruption. A key aspect of running Atlas headless in a Go CI pipeline is managing tool permissions. Atlas's tool calls are permission-gated against `allow`, `ask`, and `deny` rules. In a headless execution, there is no user to respond to an `ask` prompt, so all tools required for the Go job must be pre-approved in the permission configuration. This includes essential tools like `bash` for executing shell commands, `read` for accessing file content, `edit` for modifying Go source files, and `todowrite` for creating or updating TODOs. Atlas also computes a unified diff for every file edit and surfaces it for approval before writing, and snapshots file changes as git patches, allowing edits to be diffed and rolled back. This ensures that even in an automated Go workflow, changes are transparent and auditable, integrating with `git branches`, `status`, and `diffs`. ## How to resume or fork an Atlas session in Go CI For complex Go development tasks in 2026, Atlas allows resuming or forking prior sessions using `--continue`, `--session`, or `--fork`. This capability enables a CI pipeline step to build upon an earlier Atlas run, ensuring continuity for multi-stage Go code generation or refactoring efforts without starting from scratch. When a Go CI job requires building upon previous Atlas work, the `atlas run` command provides options for session management. The `--continue` flag allows resuming the most recent session, while `--session ` enables resuming a specific prior session. Alternatively, `--fork ` creates a new session based on an existing one, preserving its context but allowing for divergent work. This is particularly useful in Go development pipelines where an initial Atlas run might draft a new interface, and a subsequent step needs to implement methods for that interface, or where `go test` reveals issues that require further Atlas intervention. These options ensure that Atlas can efficiently manage state across multiple CI steps, leveraging its ability to read `git branches`, `status`, and `diffs`. ## Steps 1. Prepare your Go module: Ensure your project has a `go.mod` file. Atlas operates within a Go module, reading packages, interfaces, and `go.sum` dependencies. 2. Configure Atlas permissions: Pre-approve necessary tools for headless execution. For example, to allow `edit` and `bash` for Go code modifications and test execution, configure `atlas config set permissions.edit allow` and `atlas config set permissions.bash allow`. 3. Invoke Atlas headless with a Go prompt: Run `atlas run` with your specific Go task, requesting JSON output and specifying the model. Example: `atlas run --format json --model github/copilot "add a new table-driven test for the `Calculate` function in `math.go`"` 4. Process Atlas's JSON output: Capture the standard output from `atlas run` and parse the JSON event stream using a Go program or a `jq` command in your CI script to extract relevant information or verify changes. 5. Verify Go code changes: After Atlas completes its task, run `go test ./...` to execute your Go tests and `gofmt -w .` to ensure code formatting compliance on any modified files. 6. Review and commit changes: Atlas computes a unified diff for every file edit. Review these changes, and if satisfactory, Atlas can stage and create commits on your behalf, integrating with your `git` workflow. ## FAQ ### How do I run Atlas in a Go CI pipeline without interaction? Run `atlas run` with your prompt as an argument. Its default mode is non-interactive, sending a single prompt and exiting when the session goes idle, perfect for Go CI automation. ### Can Atlas output machine-readable data for Go automation? Yes, pass `--format json` to `atlas run`. This streams raw event data to stdout, allowing your Go pipeline to parse structured JSON instead of prose for automated processing. ### How do I handle tool permissions for Atlas in headless Go CI? Pre-approve necessary tools like `bash`, `read`, `edit`, and `todowrite` in Atlas's permission configuration. Headless runs have no user to answer `ask` prompts, so explicit `allow` rules are required. ### What Go tools does Atlas integrate with? Atlas integrates directly with the Go toolchain, including `go mod` for package management, `go test` for running tests, and `gofmt` for code formatting, recognizing Go modules and interfaces. ### Can Atlas resume a previous session in a Go CI job? Yes, use `--continue` to resume the last session, or `--session ` to resume a specific one. `--fork ` creates a new session from an existing one, preserving context. ### How does Atlas ensure safety when modifying Go code in CI? Atlas drafts a plan in a read-only agent, asks for approval (which must be pre-approved in headless mode), computes a unified diff for every file edit, and snapshots changes as git patches for review and rollback. ### How do I specify the model for Atlas in a Go CI environment? Set the model explicitly using the `provider/model` form, for example, `--model github/copilot`. This is required for certain providers like GitHub and ensures the correct model is used for your Go codebase. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-go Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-go` (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.