Version: v1

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
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
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​