Version: Latest

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

Before You Begin

Admin access to both GitHub and AWS
Familiarity with the detailed instructions in each linked guide
A small test change ready to validate the setup

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

Grant repository permissions in Atmos Pro to enable ordered deployments, drift detection, and other features.

Navigate to your repository in the Atmos Pro dashboard, click Quick Actions, and select Repository Permissions. Add the following permissions:

Permission	Workflow	Branch	Environment
`Affected Stacks Create`	`*`	`*`	`*`
`Instances Create`	`*`	`*`	`*`
`Instances Update`	`*`	`*`	`*`

Affected Stacks Create — Required for PR workflows to report affected stacks
Instances Create — Required for drift detection to register instances
Instances Update — Required for drift detection to update instance status

For detailed instructions, 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!

info

These workflows are already included with the reference architecture. Review them to ensure they meet your requirements.

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)
    # Skip if the PR has the "no-apply" label
    if: |
      !contains(github.event.pull_request.labels.*.name, 'no-apply') &&
      (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: Assume Planner Role
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-region: "us-east-1"
          role-to-assume: "arn:aws:iam::333333333333:role/acme-core-gbl-auto-planner"
          role-session-name: "atmos-pro-determine-affected-stacks"
          mask-aws-account-id: "no"

      - name: Determine Affected Stacks
        id: affected
        uses: cloudposse/github-action-atmos-affected-stacks@v6
        env:
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
          ATMOS_PROFILE: "github-plan"
        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
      upload_status:
        description: "Upload status to Atmos Pro"
        required: false
        type: boolean
        default: false

# 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
        env:
          ATMOS_PROFILE: "github-plan"
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
        with:
          # Atmos Pro args
          component: ${{ inputs.component }}
          stack: ${{ inputs.stack }}
          sha: ${{ inputs.sha }}
          # Upload the status to Atmos Pro
          atmos-pro-upload-status: ${{ inputs.upload_status }}
          # 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@v7
        env:
          ATMOS_PROFILE: "github-apply"
        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
OIDC Integration with GitHub for workflows to authenticate with your cloud provider
Plan File Storage (S3 + DynamoDB) to persist Terraform plan outputs for review and approvals

Deploy with Atmos and Terraform (Recommended)

If you've been following along with the reference architecture, you should already have the Terraform State Backend provisioned. This guide walks through deploying the GitHub OIDC provider and IAM roles needed for GitHub Actions to authenticate with AWS. Deploy AWS Infrastructure

Alternative: CloudFormation

All requirements can also be deployed with CloudFormation. This option is not included by default with the reference architecture but may be useful for organizations that prefer CloudFormation or need to bootstrap before Terraform is available.

See Deploy with CloudFormation for details.

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 with the apply status.

Next Steps

With Atmos Pro configured and verified, enable drift detection to continuously monitor your infrastructure for unauthorized changes. Configure Drift Detection

Setup Process​

Before You Begin

1 Sign up for Atmos Pro​

2 Grant Repository Permissions​

3 Set Up Workflows​

4 Deploy AWS Infrastructure​

Deploy with Atmos and Terraform (Recommended)

Verification​

1 Test GitHub Integration​

2 Trigger a Plan​

3 Merge the PR​