Skip to main content

Native CI

Atmos integrates CI/CD directly into the CLI. Run Terraform commands in GitHub Actions to publish job summaries, status checks, output variables, and pull-request plan comments. Use stored planfiles to verify changes before applying, and Git-aware commands to plan and deploy only the components affected by a change.

Experimental
Native CI replaces legacy Terraform actions

Atmos now handles Terraform CI directly, replacing the legacy Terraform GitHub Actions. Use native Atmos commands for new workflows.

Existing workflows that use the legacy actions continue to work. See GitHub Actions Workflows for examples and setup requirements.

Quick Start​

atmos.yaml
ci:
  enabled: true
  summary:
    enabled: true
  output:
    enabled: true
    variables:
      - has_changes
      - has_additions
      - has_destructions
      - plan_summary
  checks:
    enabled: true
  comments:
    enabled: true
    behavior: upsert

Use this configuration with the GitHub Actions workflows below.

CI Configuration

Configure CI providers, job summaries, output variables, status checks, pull-request plan comments, planfile storage, and templates in your atmos.yaml.

GitHub Actions Workflows​

Atmos provides CI features directly in the CLI; GitHub Actions runs the workflows. Browse the GitHub Actions overview for setup and runnable examples.

Plan on Pull Request​

Review infrastructure changes before merging a pull request. Run an Atmos plan in GitHub Actions and publish the results as job summaries, checks, and pull request comments.

Read the Plan on Pull Request guide.

Apply on Merge​

Deploy infrastructure after a change merges. Atmos can compare the new plan against the plan reviewed in the pull request before applying it.

Read the Apply on Merge guide.

Deploy Affected​

Run CI jobs only for component instances affected by a change. Atmos produces the GitHub Actions matrix from your stacks and Git changes.

Read the Deploy Affected Components guide.

Deploy All​

Run a workflow across every component instance in your stacks. Generate the job matrix from Atmos instead of maintaining a separate inventory in your workflow.

Read the Deploy All Components guide.

Gating Production with Environments​

Require approval before deploying production infrastructure. GitHub environments provide approval gates and environment-specific credentials while Atmos selects and deploys the stack.

Read the Deployment Approvals guide.

Workflow Setup and Reference​

Permissions​

See the GitHub Actions guide for GitHub permissions.

Authentication​

See the GitHub Actions guide for cloud authentication.

Caching the Toolchain​

See the GitHub Actions guide for toolchain caching.

SBOM Artifacts​

See the GitHub Actions guide for SBOM artifacts.

Validate Workflows​

See the GitHub Actions guide for workflow validation.

Features​

Terraform commands support the full native CI feature set below. Kubernetes commands currently produce job summaries only; they do not emit output variables, status checks, PR comments, or stored artifacts.

Job Summaries​

Rich Markdown summaries with resource counts, inline badges, collapsible diffs, and captured command output written to $GITHUB_STEP_SUMMARY. Terraform includes plan/apply summaries plus the broader native CI features below. Helm and Helmfile currently write summaries only. Templates are fully customizable with Go template syntax.

Kubernetes summaries are intentionally compact: plan/diff show created, changed, and no-change objects; apply/deploy show applied or delivered objects; delete shows deleted and not-found objects; validate shows valid and invalid objects plus errors.

Outputs​

Terraform plan and apply results exported as CI output variables for use in downstream jobs. On GitHub Actions, these are written to $GITHUB_OUTPUT. Kubernetes commands do not emit output variables in v1.

Checks​

Live commit status checks showing real-time operation progress — "Plan in progress" while running and "3 to add, 1 to change, 0 to destroy" when complete.

PR Comments​

When ci.comments.enabled: true, Terraform plans running in a pull-request context can post their rendered plan summary as a PR comment. The comment uses the same template as the job summary and, with the default upsert behavior, updates one comment per command, component, and stack on later runs. This requires GitHub Actions pull-requests: write; comments are not posted for non-PR runs, when no summary is available, or by apply, deploy, Kubernetes, Helm, or Helmfile commands.

Planfile Storage​

Store and retrieve planfiles across CI pipeline stages using S3, GitHub Artifacts, or local filesystem. The deploy command downloads stored planfiles, generates a fresh plan, and performs a semantic comparison to detect drift before applying.

Build Cache​

Warm-start the toolchain across CI jobs by restoring and saving the Atmos cache root via the CI provider's cache store — the same store actions/cache uses. Runs automatically with ci.cache.auto: both, or explicitly with the atmos ci cache subcommands.

GitOps​

Atmos is git-aware, which is what makes true GitOps possible: the repository is the source of truth, and the pipeline reconciles only what changed.

Plan what's affected
atmos describe affected diffs two Git commits and reports exactly which components and stacks changed — including changes that ripple through dependencies, imports, and remote state. See Deploy Affected for the matrix workflow.
Apply only what changed
Fan out across just the affected components, so a PR plans — and a merge applies — only the work that actually changed, instead of re-running the entire estate on every commit.
Reusable across repositories
Publish service catalogs and module libraries once and vendor them into every workload repository, so many repos share one versioned source of truth instead of copy-pasting configuration.
Automate workload repositories
Commit generated artifacts back to a source-of-truth repository as part of the pipeline. Define managed repositories once under git.repositories, then have Atmos commit and push automatically — with signed commits, a bot author identity, and bounded non-fast-forward retries — from kind: git hooks, the atmos git commands, or CI workflows. This is the foundation for GitOps with Argo CD, Flux, or downstream CI consuming the committed output.

Commands​

CI features are activated with the --ci flag on supported commands or automatically when running in a CI environment (e.g. GitHub Actions):

atmos terraform plan [--ci]
Run plan with job summary, output variables, status checks, and planfile upload.
atmos terraform apply [--ci]
Run apply with job summary, output variables, and status checks.
atmos terraform deploy [--ci]
Deploy with stored planfile verification, drift detection, and full CI reporting.
atmos helm template|diff|apply|deploy|delete [--ci]
Run native Helm components with job summaries for rendered/applied object metadata.
atmos helmfile template|diff|apply|sync|deploy|destroy [--ci]
Run Helmfile components with job summaries that include captured masked command output.
atmos terraform planfile
Manage stored planfiles: upload, download, list, delete, and show.
atmos describe affected --format=matrix
Generate GitHub Actions matrix strategy from affected components.
atmos kubernetes render|plan|diff|apply|deploy|delete|validate [--ci]
Run Kubernetes operations with a native job summary only. No output variables, status checks, comments, or artifacts are emitted.
atmos vendor update --pull-request
Open (or update) a pull request with available vendored-component updates directly from CI — replaces the deprecated Component Updater action.

Providers​

Atmos auto-detects the CI environment and selects the appropriate provider:

GitHub Actions
Integrates with GitHub job summaries, commit status checks, and output variables. Requires GITHUB_TOKEN for checks and PR features.
Generic CI
Prints summaries, checks, and outputs to stdout. Useful for local development and testing, or any CI provider without native integration.

Related​