Setup Atmos Pro

Setting up Atmos Pro is straightforward: install the GitHub App, grant repository permissions, set up the workflows, and deploy the AWS infrastructure. This guide provides an overview of each step, with detailed instructions available in the linked pages.

Setup Process

1 Install the GitHub App

The first step is to install the Atmos Pro GitHub App into your infrastructure repository. This will set up the initial connection between your repository and Atmos Pro.

Sign up for Atmos Pro using GitHub
Create or join a workspace
Install the Atmos Pro GitHub App
Import your repositories

For step-by-step instructions, see the official Atmos Pro installation guide.

2 Grant Repository Permissions

The second step is to grant repository permissions in Atmos Pro to enable ordered deployments and other features.

Permission: Affected Stacks Create
Workflow: *
Branch: *
Environment: *

For detailed instructions on repository permissions, see the official Atmos Pro repository permissions guide.

3 Set Up Workflows

The third step is to configure the workflows in your repository. This includes reviewing the generated workflows, setting up environment variables, and configuring branch protection rules.

Review the 3 GitHub Action workflows
Add the Workspace ID to GitHub repository variables
Merge the workflows into the default branch

The dispatched workflows need to exist in the default branch before they can be triggered!

The following workflows should be added to your repository:

atmos-pro.yaml
atmos-pro-terraform-plan.yaml
atmos-pro-terraform-apply.yaml

This workflow is triggered by GitHub on pull request events (opened, synchronized, reopened) and when the PR is merged (closed). It uses the atmos describe affected command to identify affected components and upload them to Atmos Pro.

.github/workflows/atmos-pro.yaml
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:
      - "runs-on=${{ github.run_id }}"
      - "runner=small"
      - "tag=affected-stacks"
      - "private=false"

    # 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:
      - uses: runs-on/action@v1
      - 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 }}
          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 }}

This workflow is dispatched by Atmos Pro to create Terraform plans for affected components. It is a reusable workflow that takes stack and component as inputs.

.github/workflows/atmos-pro-terraform-plan.yaml
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:
      - "runs-on=${{ github.run_id }}"
      - "runner=terraform"
      - "tag=${{ inputs.component }}-${{ inputs.stack }}"
      - "private=false"

    steps:
      - uses: runs-on/action@v1
      - 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 }}

This workflow is dispatched by Atmos Pro to apply Terraform changes for affected components. It is a reusable workflow that takes stack and component as inputs.

.github/workflows/atmos-pro-terraform-apply.yaml
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:
      - "runs-on=${{ github.run_id }}"
      - "runner=terraform"
      - "tag=${{ inputs.component }}-${{ inputs.stack }}"
      - "private=false"

    steps:
      - uses: runs-on/action@v1
      - 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 }}

For additional workflow setup instructions, see the official Atmos Pro workflow configuration guide.

4 Deploy AWS Infrastructure

The final step is to deploy the required AWS infrastructure. This will create all necessary resources for running Atmos Terraform Plan and Apply from GitHub Actions.

Configure Terraform State Backend
For role assumption, deploy the GitHub OIDC provider and roles
To store Terraform planfiles, deploy the S3 bucket and DynamoDB table.

For step-by-step AWS deployment instructions, choose one of the following options:

Tips

Make sure you have admin access to both GitHub and AWS before starting the setup
Follow the detailed instructions in each linked guide for specific steps
Test the setup with a small change before deploying major infrastructure changes

Verification

After completing all four steps, you can verify the setup by:

1 Test GitHub Integration

Create a new pull request with a small stack change
The Atmos Pro GitHub App will automatically comment on the PR
The comment will show the status of affected components
As workflows are dispatched for each component, the comment will automatically update

2 Verify AWS Resources

Check that the S3 bucket for storing Terraform plans exists
Verify the DynamoDB table for tracking deployments is created
Confirm the IAM roles have the correct permissions

Setup Process​

1 Install the GitHub App​

2 Grant Repository Permissions​

3 Set Up Workflows​

4 Deploy AWS Infrastructure​