# Run Atlas Headless in CI for Ruby Projects in 2026 > Ruby developers can run Atlas headless in CI pipelines using `atlas run --format json` to automate tasks and receive machine-readable output for integration with `RSpec` and `Bundler`. Atlas runs headless in CI for Ruby projects by 2026, enabling non-interactive code generation and analysis. Ruby developers can integrate `atlas run` into their pipelines to automate tasks like generating `RSpec` tests or refactoring modules, receiving machine-readable JSON output for direct integration with `Bundler` and `RuboCop` workflows. This approach ensures that Atlas operates efficiently within existing Ruby toolchains, providing concrete, actionable results without requiring human intervention. ## Key takeaways - Atlas automates Ruby code tasks like `RSpec` test generation and `RuboCop` fixes directly within CI pipelines. - Machine-readable JSON output from `atlas run --format json` enables direct integration with Ruby CI/CD workflows. - Pre-approved tool permissions are essential for safe, non-interactive Atlas execution in Ruby projects. - Atlas deeply understands Ruby project structures, including `Gemfile` dependencies and `Rakefile` tasks. - Unified diffs and git patches provide robust review and rollback capabilities for all Atlas-generated Ruby code changes. ## Running Atlas Headless in Ruby CI Pipelines By 2026, Ruby developers can run Atlas headless in CI pipelines to automate code tasks, ensuring non-interactive execution. The `atlas run` command is specifically designed for this, sending a single prompt and exiting when the session goes idle, providing a streamlined workflow for `Bundler` projects. To execute Atlas non-interactively within a Ruby CI pipeline, use the `atlas run` command. This command's default behavior is non-interactive, making it ideal for automated environments. For machine-readable output that can be parsed by subsequent CI steps, always include the `--format json` flag. This streams raw event data to standard output, allowing your pipeline to programmatically react to Atlas's actions, such as generated `RSpec` tests or `RuboCop` fixes. For example, a CI job might invoke `atlas run --format json --prompt "Generate RSpec tests for lib/my_module.rb"` within a Ruby project containing a `Gemfile`. This ensures that Atlas operates within the expected Ruby context, leveraging its understanding of modules, gems, and `Rakefile` tasks to perform the requested operation. ## Configuring Atlas Permissions for Ruby Workflows To ensure a smooth, non-interactive Atlas session in a Ruby CI environment, all necessary tools must be pre-approved through the permission configuration. Headless runs, especially in 2026, have no human operator to answer 'ask' prompts, making explicit 'allow' rules for tools like `edit` and `bash` critical for `Bundler` projects. When running Atlas headless in a Ruby CI pipeline, interactive permission prompts are not possible. Therefore, it is crucial to pre-approve all tools Atlas might need to use via its permission configuration. For typical Ruby development tasks, Atlas will require access to tools such as `bash` for executing shell commands (e.g., running `bundle install` or `rspec`), `read` for inspecting Ruby source files (e.g., `lib/my_module.rb`), `edit` for modifying code, and `todowrite` for creating new files or updating existing ones (e.g., writing new `spec/my_module_spec.rb` files). These permissions are typically defined in a configuration file, ensuring that Atlas can perform its job without interruption. Without explicit 'allow' rules, any tool call that defaults to 'ask' will halt the headless session, leading to a failed CI build for your Ruby project. ## Integrating Atlas with Ruby Tooling (RSpec, Bundler, RuboCop) Atlas integrates deeply with the Ruby toolchain, understanding `Gemfile` dependencies and `RSpec` test suites, making it a powerful assistant for Ruby developers in 2026. It can read your modules, gems, and `Rakefile` tasks, then write `RSpec` examples or suggest `RuboCop` fixes, all within your existing `Bundler` managed project. Atlas is designed to work direct within a Ruby project's ecosystem. When run in a directory containing a `Gemfile`, Atlas automatically understands the project's dependencies managed by `Bundler`. It can read and analyze Ruby modules (e.g., files in `lib/`), existing `RSpec` test suites (e.g., files in `spec/`), and `Rakefile` tasks. This deep understanding allows Atlas to perform highly relevant actions, such as generating new `RSpec` examples for a given Ruby class or method, or suggesting refactorings that align with `RuboCop`'s style guidelines. For instance, after Atlas generates new `spec/models/user_spec.rb` content, a subsequent CI step could run `bundle exec rspec spec/models/user_spec.rb` to validate the new tests, or `bundle exec rubocop -A` to automatically apply formatting. The machine-readable JSON output from `atlas run --format json` facilitates this integration, allowing CI scripts to parse Atlas's suggestions and apply them or trigger further Ruby toolchain commands. ## Reviewing and Rolling Back Atlas Changes in Ruby Projects Every code modification made by Atlas in a Ruby project generates a unified diff, providing a clear audit trail for developers in 2026. This diff is surfaced for approval, and Atlas also snapshots file changes as git patches, allowing for easy review and rollback of any edits, such as those to `lib/my_class.rb` or `Gemfile`. Safety and review are paramount when automating code changes, even in a headless CI environment. Atlas addresses this by computing a unified diff for every file edit it proposes or executes. This diff can be captured from the `--format json` output and presented to a human reviewer or an automated gate in the CI pipeline. Furthermore, Atlas snapshots all file changes as git patches. This means that even if a headless run applies changes directly, a Ruby developer can easily inspect the modifications using standard git commands (e.g., `git diff`) and roll them back if necessary (e.g., `git apply -R `). This capability is vital for maintaining code quality and ensuring that automated changes, whether to `app/models/user.rb` or a new `RSpec` test file, meet the project's standards before being merged into the main branch. ## Resuming and Forking Atlas Sessions for Ruby Development For complex Ruby development tasks, Atlas allows resuming or forking prior sessions, a valuable feature for iterative work in 2026. This means a CI pipeline can pick up where a previous Atlas run left off using `--continue` or `--session`, or explore alternative solutions from a specific point with `--fork`, saving significant processing time. In scenarios where a Ruby CI job might fail or require further iteration, Atlas provides mechanisms to resume or fork existing sessions. The `--continue` flag allows Atlas to pick up an interrupted session, while `--session ` enables resuming a specific prior session. This is particularly useful for long-running tasks or when a pipeline needs to re-run a step that involves Atlas. For example, if Atlas was tasked with refactoring a large Ruby module in `lib/complex_service.rb` and the CI job timed out, `--continue` would allow it to pick up from the last known state. The `--fork` option provides flexibility to explore alternative solutions based on a previous session's context, without altering the original session. This ensures that Ruby developers can leverage Atlas's stateful capabilities even within a stateless CI environment, optimizing resource usage and accelerating development cycles. ## Steps 1. Ensure your Ruby project includes a `Gemfile` and relevant Ruby source files (e.g., in `lib/` or `app/`) for Atlas to analyze. 2. Configure Atlas permissions to explicitly `allow` necessary tools like `bash`, `read`, `edit`, and `todowrite` in your Atlas configuration file for headless operation. 3. Invoke `atlas run` within your Ruby project directory, specifying the prompt, `--format json`, and the model (e.g., `atlas run --prompt "Generate RSpec tests for lib/user.rb" --format json --model 'github/copilot-gpt4-turbo'`). 4. Capture the JSON output stream from `stdout` in your CI pipeline for programmatic parsing and analysis of Atlas's actions and suggestions. 5. In a subsequent CI step, use Ruby's `JSON` library to parse Atlas's output and trigger relevant Ruby toolchain commands, suchs as `bundle exec rspec` to run generated tests or `bundle exec rubocop -A` to apply formatting. 6. Review the unified diffs generated by Atlas, which are available in the JSON output and as git patches, to approve or roll back changes to your Ruby codebase. 7. Optionally, use `atlas run --continue` or `atlas run --session ` to resume a prior Atlas session if a CI job needs to pick up from an earlier state in your Ruby project. ## FAQ ### How do I run Atlas non-interactively in a Ruby CI pipeline? Run `atlas run` with your desired prompt and include the `--format json` flag. This executes Atlas non-interactively, streaming machine-readable events to stdout, which your Ruby CI pipeline can then parse. ### What output format does Atlas provide for CI automation in Ruby? Atlas provides a raw event stream in JSON format when you use the `--format json` flag with `atlas run`. This output is designed for programmatic parsing by CI tools, allowing you to integrate Atlas's actions with your Ruby toolchain. ### How does Atlas handle permissions when running headless in a Ruby project? For headless runs in Ruby projects, all tools Atlas might use (like `bash`, `read`, `edit`) must be pre-approved in its configuration. This prevents interactive 'ask' prompts that would halt the CI pipeline. ### Can Atlas generate `RSpec` tests in a Ruby CI environment? Yes, Atlas can generate `RSpec` tests in a Ruby CI environment. You would provide a prompt like `"Generate RSpec tests for lib/my_class.rb"` to `atlas run`, and it will output the new test files or modifications, which can then be validated by running `bundle exec rspec`. ### How do I ensure Atlas changes are safe in my Ruby codebase? Atlas generates a unified diff for every change and snapshots file modifications as git patches. Your CI pipeline can capture these diffs from the JSON output for review, and changes can be rolled back using standard git commands, ensuring safety in your Ruby project. ### Does Atlas integrate with `Bundler` and `RuboCop` in CI? Yes, Atlas integrates with `Bundler` and `RuboCop`. It understands `Gemfile` dependencies and can generate code that adheres to `RuboCop`'s style guidelines. Your CI pipeline can run `bundle install` and `bundle exec rubocop` after Atlas's changes to ensure consistency. ### Can I resume a failed Atlas session in a Ruby CI pipeline? Yes, you can resume a failed or interrupted Atlas session in a Ruby CI pipeline using `atlas run --continue` or `atlas run --session `. This allows Atlas to pick up from its last known state, saving time and resources. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-ruby Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-ruby` (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.