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

The first step is to sign up for Atmos Pro. The sign up process includes creating a workspace in the Atmos Pro web console and installing the Atmos Pro GitHub App into your infrastructure repository. This will set up the connection between your repository and Atmos Pro.

Sign up for Atmos Pro
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

Atmos Pro doesn't run Terraform or Atmos itself. It dispatches GitHub Actions that you control. To run Terraform in those GitHub Actions, you need to set up a few things in your cloud environment:

State Backend (S3 + DynamoDB) to store Terraform state and enable state locking
Plan File Storage (S3 + DynamoDB) to persist Terraform plan outputs for review and approvals
OIDC Integration with GitHub for workflows to authenticate with your cloud provider

If you've been following along with the reference architecture, by now you should already have the Terraform State Backend provisioned. To complete the requirements for Atmos Pro and GitHub Actions, continue with the step-by-step instructions: Atmos and Terraform deployment

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 Trigger a Plan

In the new pull request, change a value for any component. For example, add a tag to a S3 bucket.
The atmos-pro.yaml workflow will discover the newly affected stack and trigger Atmos Pro.
Atmos Pro will run Atmos Terraform Plan for the affected stack.
As the workflow is executed, Atmos Pro will update the comment on the PR with the plan status.

3 Merge the PR

Now try merging the PR
Again, the atmos-pro.yaml workflow will discover the affected stacks and trigger Atmos Pro.
This time Atmos Pro will determine this is a "merged" event and run Atmos Terraform Apply.
Finally, Atmos Pro will update the comment on the PR will the apply status.

Setup Process​

1 Sign up for Atmos Pro​

2 Grant Repository Permissions​

3 Set Up Workflows​

4 Deploy AWS Infrastructure​

Tips

Verification​

1 Test GitHub Integration​

2 Trigger a Plan​

3 Merge the PR​