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
run-name: Atmos Pro

# 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 # Required for requesting the JWT (OIDC) token
  contents: read  # 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 for PR 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@v2

      - name: Install Atmos
        uses: cloudposse/github-action-setup-atmos@v3
        with:
          install-wrapper: false
          atmos-version: ${{ vars.ATMOS_VERSION }}

      # Checkout the PR head SHA so the uploaded HeadSHA matches the webhook trigger event.
      - name: Checkout
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0

      - name: Determine Affected Stacks
        shell: bash
        env:
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
          ATMOS_PROFILE: "github-plan"
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          atmos describe affected --upload

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

on:
  workflow_dispatch:
    inputs:
      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 applies across workflows to both plan and apply.
concurrency:
  group: "${{ inputs.stack }}-${{ inputs.component }}"
  cancel-in-progress: false

permissions:
  id-token: write  # Required for requesting the JWT (OIDC) token
  contents: read   # Required for actions/checkout
  statuses: write  # Required for CI commit status checks

jobs:
  atmos-plan:
    name: ${{ inputs.component }}-${{ inputs.stack }}

    runs-on:
      - "runs-on=${{ github.run_id }}"
      - "runner=terraform"
      - "tag=${{ inputs.component }}-${{ inputs.stack }}"
      - "private=true"

    steps:
      - uses: runs-on/action@v2

      - name: Checkout
        uses: actions/checkout@v6
        with:
          ref: ${{ inputs.sha }}

      - name: Install Atmos
        uses: cloudposse/github-action-setup-atmos@v3
        with:
          install-wrapper: false
          atmos-version: ${{ vars.ATMOS_VERSION }}

      - name: Plan Atmos Component
        shell: bash
        env:
          ATMOS_PROFILE: github-plan
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
          GITHUB_SHA: ${{ inputs.sha }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          atmos terraform plan ${{ inputs.component }} -s ${{ inputs.stack }} --upload-status

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

on:
  workflow_dispatch:
    inputs:
      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 applies across workflows to both plan and apply.
concurrency:
  group: "${{ inputs.stack }}-${{ inputs.component }}"
  cancel-in-progress: false

permissions:
  id-token: write  # Required for requesting the JWT (OIDC) token
  contents: read   # Required for actions/checkout
  statuses: write  # Required for CI commit status checks

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=true"

    steps:
      - uses: runs-on/action@v2

      - name: Checkout
        uses: actions/checkout@v6
        with:
          ref: ${{ inputs.sha }}

      - name: Install Atmos
        uses: cloudposse/github-action-setup-atmos@v3
        with:
          install-wrapper: false
          atmos-version: ${{ vars.ATMOS_VERSION }}

      - name: Apply Atmos Component
        shell: bash
        env:
          ATMOS_PROFILE: github-apply
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
          GITHUB_SHA: ${{ inputs.sha }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          atmos terraform deploy ${{ inputs.component }} -s ${{ inputs.stack }} --upload-status

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​