# 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

:::note Native CI replaces legacy Terraform actions
Atmos now handles Terraform CI directly, replacing the
[legacy Terraform GitHub Actions](/deprecated/github-actions).
Use native Atmos commands for new workflows.

Existing workflows that use the legacy actions continue to work.
See [GitHub Actions Workflows](#github-actions-workflows) for examples and setup requirements.
:::

## Quick Start

**File:** `atmos.yaml`

```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](#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`.

Configuration Reference[Read more](/cli/configuration/ci)

## GitHub Actions Workflows

Atmos provides CI features directly in the CLI; GitHub Actions runs the workflows. Browse the [GitHub Actions overview](/integrations/github-actions) 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](/integrations/github-actions/plan-on-pull-request).

### 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](/integrations/github-actions/apply-on-merge).

### 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](/integrations/github-actions/deploy-affected).

### 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](/integrations/github-actions/deploy-all).

### 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](/integrations/github-actions/deployment-approvals).

## Workflow Setup and Reference

### Permissions

See the GitHub Actions guide for [GitHub permissions](/integrations/github-actions/authentication#permissions).

### Authentication

See the GitHub Actions guide for [cloud authentication](/integrations/github-actions/authentication#authentication).

### Caching the Toolchain

See the GitHub Actions guide for [toolchain caching](/integrations/github-actions#caching-the-toolchain).

### SBOM Artifacts

See the GitHub Actions guide for [SBOM artifacts](/integrations/github-actions#sbom-artifacts).

### Validate Workflows

See the GitHub Actions guide for [workflow validation](/integrations/github-actions/validate-workflows).

## 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](/ci/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](/cli/configuration/ci/output)

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](/cli/configuration/ci/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](/cli/configuration/ci/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](/ci/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](/cli/configuration/ci/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`](/cli/commands/ci/cache)
subcommands.

### [GitOps](/cli/configuration/git)

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`](/cli/commands/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](#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](/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](/stacks/hooks#kind-git)
  , the 
  [`atmos git`](/cli/commands/git/usage)
   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]`](/cli/commands/terraform/plan)**
  Run plan with job summary, output variables, status checks, and planfile upload.
- **[`atmos terraform apply [--ci]`](/cli/commands/terraform/apply)**
  Run apply with job summary, output variables, and status checks.
- **[`atmos terraform deploy [--ci]`](/cli/commands/terraform/deploy)**
  Deploy with stored planfile verification, drift detection, and full CI reporting.
- **[`atmos helm template|diff|apply|deploy|delete [--ci]`](/cli/commands/helm/usage)**
  Run native Helm components with job summaries for rendered/applied object metadata.
- **[`atmos helmfile template|diff|apply|sync|deploy|destroy [--ci]`](/cli/commands/helmfile/usage)**
  Run Helmfile components with job summaries that include captured masked command output.
- **[`atmos terraform planfile`](/cli/commands/terraform/planfile)**
  Manage stored planfiles: upload, download, list, delete, and show.
- **[`atmos describe affected --format=matrix`](/cli/commands/describe/affected)**
  Generate GitHub Actions matrix strategy from affected components.
- **[`atmos kubernetes render|plan|diff|apply|deploy|delete|validate [--ci]`](/cli/commands/kubernetes/usage)**
  Run Kubernetes operations with a native job summary only. No output variables, status checks, comments, or artifacts are emitted.
- **[`atmos vendor update --pull-request`](/cli/commands/vendor/vendor-update)**
  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

- [CI Configuration](/cli/configuration/ci) - Configure CI integration in `atmos.yaml`
- [CI Commands](/cli/commands/ci) - CI command reference
- [Profiles](/cli/configuration/profiles) - Configure CI-specific profiles
- [`atmos vendor update`](/cli/commands/vendor/vendor-update) - Update vendored components and open pull requests from CI
- [Deprecated GitHub Actions](/deprecated/github-actions) - Full list of legacy actions and their native replacements
- [Auth](/stacks/auth) - Configure OIDC authentication for CI