Deploy Affected Components

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

Use Setup Atmos to pin the Atmos container version, enable native CI reporting, and configure authentication and permissions for your repository.

Workflow

Fan out across only the components that changed in the PR using atmos describe affected --format=matrix. When ci.enabled: true is set in atmos.yaml, the matrix is automatically written to $GITHUB_OUTPUT — no --output-file flag needed.

.github/workflows/deploy-affected.yml

on:
  pull_request:

permissions:
  id-token: write
  contents: read
  statuses: write
  checks: write
  pull-requests: write

jobs:
  affected:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    outputs:
      matrix: ${{ steps.affected.outputs.matrix }}
      count: ${{ steps.affected.outputs.count }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - id: affected
        run: atmos describe affected --format=matrix

  deploy:
    needs: affected
    if: ${{ needs.affected.outputs.count != '0' }}
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    strategy:
      matrix: ${{ fromJson(needs.affected.outputs.matrix) }}
      fail-fast: false
    steps:
      - uses: actions/checkout@v6

      - env:
          COMPONENT: ${{ matrix.component }}
          STACK: ${{ matrix.stack }}
        run: atmos terraform deploy "$COMPONENT" -s "$STACK"

The affected job outputs a matrix of {component, stack} pairs and a count. The deploy job checks count != '0' to skip empty matrices ({"include":[]}). With ci.enabled: true, Atmos writes these outputs to $GITHUB_OUTPUT automatically; otherwise, pass --output-file="$GITHUB_OUTPUT".

Add --labels=ci:auto to select components labeled for this workflow. See Choosing which components run in CI for components needing different permissions or network connectivity.

Workflow​

Workflow