Github Actions Workflow Configuration

Learn how to configure GitHub Actions workflows for Atmos Pro ordered deployments.

This section assumes you are familiar with GitHub Actions workflows and have already been using them in your organization. If you are new to GitHub Actions, please refer to the GitHub Actions documentation for more information.

Workflow Configuration

To use Atmos Pro with GitHub Actions, you'll first need to install the GitHub App and then configure three main workflows:

Affected Stacks Workflow
Plan Workflow
Apply Workflow

Requirements

For Atmos Pro to dispatch your GitHub Actions workflows, your workflows must include the following configuration elements:

Workflow `on` Trigger

Your workflow must include the workflow_dispatch event to allow Atmos Pro to trigger it:

on:
  workflow_dispatch:

Required Inputs

Your workflow must include these required inputs in the workflow_dispatch configuration:

on:
  workflow_dispatch:
    inputs:
      atmos_pro_run_id:
        description: "Atmos Pro Run ID"
        required: true
        type: string
      sha:
        description: "SHA to run workflow on"
        required: true
        type: string
      component:
        description: "Component to run workflow on"
        required: true
        type: string
      stack:
        description: "Stack to run workflow on"
        required: true
        type: string

These inputs serve specific purposes:

atmos_pro_run_id: A unique identifier for each Atmos Pro workflow run. This is required because GitHub's API triggers workflow runs asynchronously and doesn't return a workflow_run_id immediately.
sha: The commit SHA to run the workflow against. This is necessary because workflow_dispatch doesn't provide GitHub context for determining which commit to use.
component: The component to run the workflow on
stack: The stack to run the workflow on

Workflow Run Name

For proper status tracking in Atmos Pro's status comment, your workflow must use a specific run-name format:

For plan workflows:

run-name: plan ${{ inputs.component }}/${{ inputs.stack }}/${{ inputs.atmos_pro_run_id}}

For apply workflows:

run-name: apply ${{ inputs.component }}/${{ inputs.stack }}/${{ inputs.atmos_pro_run_id}}

Required Permissions

Each workflow must include these permissions for OIDC authentication:

permissions:
  id-token: write # Required for OIDC
  contents: read # Required for checking out code

Workflow Examples

Affected Stacks Workflow

This workflow determines which stacks are affected by changes in your pull request or push to the main branch.

name: 👽 Atmos Pro Determine Affected Stacks
run-name: 👽 Atmos Pro Determine Affected Stacks
 
# Atmos Pro reacts to events defined in the Atmos stack settings
# and will trigger the appropriate workflows for the given event.
#
# For example, pull requests opened, synchronize, and reopened will trigger plan workflows.
# Whereas pull requests merged will trigger apply workflows
on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - closed
    branches:
      - main
 
# Avoid conflicting workflow triggers.
# For example, wait to trigger apply until plan has been triggered
concurrency:
  group: "${{ github.ref }}"
  cancel-in-progress: false
 
permissions:
  id-token: write # This is required for requesting the JWT (OIDC) token
  contents: read # This is required for actions/checkout
 
jobs:
  affected:
    name: Trigger Affected Stacks
 
    runs-on:
      - "ubuntu-latest"
 
    # Trigger Atmos Pro for Pull Request plan events and specifically closed PRs that have been merged (not just closed)
    if: github.event.action != 'closed' || (github.event.action == 'closed' && github.event.pull_request.merged == true)
 
    steps:
      - name: Checkout
        # For merged PRs, we will need to checkout the base branch to get the correct base branch SHA.
        # This isn't necessary for other events.
        if: github.event.action == 'closed'
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for all branches and tags
 
      # For merged PRs, we want to use 1 previous commit from the base branch SHA
      # This is because by the time this workflow runs, the PR branch has already been merged.
      # It's critical to use the base branch SHA to get the correct changes, not the previous commit from the PR branch.
      - name: Determine previous commit on base branch
        id: get_parent
        if: github.event.action == 'closed'
        shell: bash
        run: |
          # For squash merges, github.event.pull_request.base.sha represents the state of the base branch
          # when the PR was created (or last updated). This may be stale compared to the actual commit
          # on the main branch at the time of the merge. Using 'HEAD~1' after the merge ensures we get
          # the commit that was the tip of main immediately before the squash merge commit was added.
          echo "Merge commit: $(git rev-parse HEAD)"
          PARENT=$(git rev-parse HEAD~1)
          echo "Parent (base) commit: $PARENT"
          echo "merge_commit=$MERGE_COMMIT" >> "$GITHUB_OUTPUT"
          echo "parent_commit=$PARENT" >> "$GITHUB_OUTPUT"
 
      - name: Determine Affected Stacks
        id: affected
        uses: cloudposse/github-action-atmos-affected-stacks@v6
        env:
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
        with:
          atmos-version: ${{ vars.ATMOS_VERSION }} # >= 1.180.0
          atmos-config-path: ${{ vars.ATMOS_CONFIG_PATH }}
          atmos-pro-upload: true
          # Compare the head of the PR to the base of the PR if the PR is not merged.
          # If the PR is merged, compare the head of the PR to 1 previous commit on the base branch.
          head-ref: ${{ github.event.pull_request.head.sha }}
          base-ref: ${{ github.event.action == 'closed' && steps.get_parent.outputs.parent_commit || github.event.pull_request.base.sha }}

Plan Workflow

This workflow runs the atmos terraform plan command for a specific stack.

name: 👽 Atmos Pro Terraform Plan
run-name: plan ${{ inputs.component }}/${{ inputs.stack }}/${{ inputs.atmos_pro_run_id}}
 
on:
  workflow_dispatch:
    inputs:
      atmos_pro_run_id:
        description: "Atmos Pro Run ID"
        type: string
      sha:
        description: "Commit SHA"
        type: string
      component:
        description: "Component"
        required: true
        type: string
      stack:
        description: "Stack"
        required: true
        type: string
 
# Avoid running the same stack in parallel mode (from different workflows)
# This applied to across workflows to both plan and apply
concurrency:
  group: "${{ inputs.stack }}-${{ inputs.component }}"
  cancel-in-progress: false
 
permissions:
  id-token: write # This is required for requesting the JWT (OIDC) token
  contents: read # This is required for actions/checkout
 
jobs:
  atmos-plan:
    name: ${{ inputs.component }}-${{ inputs.stack }}
 
    runs-on:
      - "ubuntu-latest"
 
    steps:
      - uses: unfor19/install-aws-cli-action@v1
 
      - name: Plan Atmos Component
        uses: cloudposse/github-action-atmos-terraform-plan@v5
        with:
          # Atmos Pro args
          component: ${{ inputs.component }}
          stack: ${{ inputs.stack }}
          sha: ${{ inputs.sha }}
          # Atmos required configuration
          atmos-version: ${{ vars.ATMOS_VERSION }}
          atmos-config-path: ${{ vars.ATMOS_CONFIG_PATH }}

Apply Workflow

This workflow runs the atmos terraform apply command for a specific stack.

name: 👽 Atmos Pro Terraform Apply
run-name: apply ${{ inputs.component }}/${{ inputs.stack }}/${{ inputs.atmos_pro_run_id}}
 
on:
  workflow_dispatch:
    inputs:
      atmos_pro_run_id:
        description: "Atmos Pro Run ID"
        type: string
      sha:
        description: "Commit SHA"
        type: string
      component:
        description: "Component"
        required: true
        type: string
      stack:
        description: "Stack"
        required: true
        type: string
      github_environment:
        description: "GitHub Environment"
        required: true
        type: string
 
# Avoid running the same stack in parallel mode (from different workflows)
# This applied to across workflows to both plan and apply
concurrency:
  group: "${{ inputs.stack }}-${{ inputs.component }}"
  cancel-in-progress: false
 
permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout
 
jobs:
  atmos-apply:
    name: ${{ inputs.component }}-${{ inputs.stack }}
 
    # The GitHub environment is defined in Atmos Pro settings.
    # Typically this is <tenant>-<stage>
    environment: ${{ inputs.github_environment }}
 
    runs-on:
      - "ubuntu-latest"
 
    steps:
      - uses: unfor19/install-aws-cli-action@v1
 
      - name: Apply Atmos Component
        uses: cloudposse/github-action-atmos-terraform-apply@v4
        with:
          # Atmos Pro args
          component: ${{ inputs.component }}
          stack: ${{ inputs.stack }}
          sha: ${{ inputs.sha }}
          # Atmos required configuration
          atmos-version: ${{ vars.ATMOS_VERSION }}
          atmos-config-path: ${{ vars.ATMOS_CONFIG_PATH }}

Summary

Now that you have signed up for Atmos Pro and installed the Atmos Pro GitHub App, configured your Atmos repository, and configured your GitHub Actions workflow, you are ready to start using Atmos Pro to deploy your Atmos stacks!

Configure Atmos Overview