Atmos Pro runs your deployments in a specific order using your existing Atmos and Terraform code. It’s fully automated from pull request to apply, with support for locking, ordering, and detailed status checks in PRs.

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 builds on top of GitHub Actions, and the best way to understand how it works is through a practical example—integrating Atmos Pro into both a pull request workflow and a merge workflow.

The process begins when a developer creates a new feature branch and pushes changes—such as updating the values of a component or modifying a configuration file.

This action typically kicks off a GitHub Actions workflow that runs against the feature branch to validate the changes and provide early feedback within the pull request.

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

A deployment refers to a specific component (like a Terraform or Helmfile component) within a stack.

A deployment is considered affected if:

This allows workflows to intelligently target only the components that need to be validated or deployed.

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.

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.

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.

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

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.

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.

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.

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.

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

This documentation will guide you through the features of Atmos Pro and how to use them to manage your infrastructure effectively.