How it Works

In this section, we'll discuss how Atmos Pro works with GitHub Actions to deploy your Atmos stacks in a specific order. We will discuss how it all works in this section and will walk you through the steps needed to configure Atmos Pro in the next section.

Atmos Pro can be configured to run workflows in many different ways, but in order to explain how it works, we'll use the following example:

On pull requests, Atmos Pro triggers atmos terraform plan:

1. Developer Makes a Change
2. Code Is Pushed to Feature Branch
3. GitHub Actions Trigger Atmos Affected Stacks
4. Atmos Uploads Affected Stacks
5. Atmos Pro Dispatches Plan Workflows
6. Atmos Pro Updates Status Comment

On merged pull requests, Atmos Pro triggers atmos terraform apply:

1. Pull Request Is Merged
2. GitHub Actions Trigger Atmos Affected Stacks
3. Atmos Uploads Affected Stacks
4. Atmos Pro Dispatches Apply Workflows
5. Atmos Pro Updates Status Comment

If this isn't the workflow you're looking for, we'll demonstrate how to configure Atmos Pro for different scenarios in the next section, but for now, let's focus on the workflow we just described.

Code is Pushed to a Feature Branch

The process starts when developer makes some changes to the Atmos stacks or terraform modules in their infrastructure repository, opens a feature branch, and pushes the code changes to the feature branch.

GitHub Actions Trigger Atmos Affected Stacks

When code is pushed to a branch, Cloud Posse's Atmos Affected Stacks GitHub Action runs the atmos describe affected command to determine which stacks are affected by the code change.

Stacks are considered affected if their configuration changes, if there are any changes to the terraform code they are using, if any global configuration is changed, or if the stack is dependent on another stack that is affected.

Atmos Uploads Affected Stacks

Once the affected stacks have been determined with atmos, the GitHub Action uploads the list of affected stacks to the Atmos Pro API. The app then processes the list of affected stacks and determines the order in which stacks need to be deployed.

Authentication

Atmos CLI uses OpenID Connect (OIDC) for secure authentication with the Atmos Pro API. This is the recommended and most secure way to authenticate. OIDC authentication is natively supported in the Atmos CLI tool, making it easier to securely authenticate without managing tokens.

For detailed instructions on setting up authentication, see our Authentication Guide.

Workspace ID

To use Atmos Pro with GitHub Actions, you'll need to configure your workspace ID. This ID is used to identify your workspace in the Atmos Pro API.

For detailed instructions on finding and configuring your workspace ID, see our Workspace ID Guide.

Repository Permissions

To use Atmos Pro with GitHub Actions, you'll need to grant Atmos Pro repository permission. This is required for OIDC authentication.

For detailed instructions on granting repository permissions, see our Repository Permissions Guide.

Atmos Pro Dispatches GitHub Workflows

Atmos Pro automatically dispatches workflows for each affected stack in the correct order. It starts with root stacks (stacks with no dependencies) and then processes child stacks only after their parent stacks have completed successfully. This ensures that your infrastructure changes are always deployed in the correct order.

When a pull request is merged, Atmos Pro re-runs the affected stacks detection and dispatches the configured apply workflow instead of the plan workflow.

For detailed information about workflow configuration and dispatch process, see our Workflow Configuration Guide.

GitHub Workflow Dispatch

Atmos Pro handles workflow dispatch in a hierarchical manner. Each top-level, or Root Stack (a stack that is not dependent on another affected stack) is dispatched to a separate workflow run. We'll use the atmos-terraform-plan workflow, but which workflow runs and its inputs are fully user configurable.

Atmos Pro is notified by GitHub Webhooks when a stack has been dispatched, is running, or has completed. Once a stack completes, then the first level of dependent stacks, or Child Stacks, are dispatched to separate workflow runs. This process continues until all levels of dependent stacks have been dispatched.

Status Reporting

Throughout the deployment process, Atmos Pro creates and updates a comment on the Pull Request showing the list of affected stacks, dependency graph, and current status of each dispatched stack.

Atmos Configuration

To use Atmos Pro, you'll need to configure your Atmos stacks to define which workflows should be dispatched for each component based on the event type. The configuration tells Atmos Pro when to run plan or apply workflows for each component when changes are detected.

For detailed instructions on configuring workflow dispatch rules for your Atmos stacks, see our Atmos Configuration Guide.

Workflow Configuration

To use Atmos Pro with GitHub Actions, you'll need to configure three main workflows:

1. Affected Stacks Workflow - Determines which stacks are affected by changes
2. Plan Workflow - Runs atmos terraform plan for specific stacks on dispatch
3. Apply Workflow - Runs atmos terraform apply for specific stacks on dispatch

For detailed workflow configuration instructions, including YAML examples and required permissions, see our Workflow Configuration Guide.

Pull Request is Merged

Atmos Pro reacts to the pull request closed event and determines if the pull request is merged (not just closed). If so, then Atmos Pro dispatches the configured workflows.

1. GitHub Actions runs on the closed event in GitHub, runs atmos describe affected, and uploads the result to Atmos Pro.
2. Atmos Pro receives the event and determines it to be a custom merged event for the pull request.
3. Atmos Pro then dispatches the merged workflows.
4. The dispatched workflows then run and update status accordingly in the comments on the PR.

This ensures your infrastructure changes are properly deployed and tracked after merging.