Atmos Pro turns GitHub Actions into a powerful infrastructure deployment engine—secure, ordered, and drift-aware.
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.
Atmos Pro provides end-to-end infrastructure deployment that is:
Defined purely in your existing Atmos and Terraform code
Fully automated, from pull request to apply-after-merge
Safe and reliable, with deployment locking and ordering
Easy to monitor, with detailed status reporting in pull requests
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.
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
Ready to learn this topic?
We have some example GitHub Actions workflows that will make this feel more concrete.
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:
Its configuration has changed
The underlying component code has changed
Any global configuration it relies on has changed
It depends on another deployment that was affected
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.
Ready to learn this topic?
Projects are organized into a well-structured folder layout, embracing best practices and conventions for a consistently organized project.
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.
Ready to learn this topic?
Projects are organized into a well-structured folder layout, embracing best practices and conventions for a consistently organized project.
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.
Ready to learn this topic?
Projects are organized into a well-structured folder layout, embracing best practices and conventions for a consistently organized project.
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.
This documentation will guide you through the features of Atmos Pro and how to use them to manage your infrastructure effectively.