A basic example demonstrating how to use Atmos Pro with GitHub Actions for infrastructure deployment. This repository shows the minimal configuration needed to get started with Atmos Pro workflows.
This is a basic example repository that demonstrates how to use Atmos Pro with GitHub Actions for infrastructure deployment. It provides a minimal setup to help you understand the core concepts of Atmos Pro workflows.
For comprehensive documentation and advanced features, visit atmos-pro.com/docs.
Prerequisites for Using Atmos CLI
In order to trigger workflows from this GitHub repository, the Atmos Pro GitHub App will execute atmos on your behalf in GitHub Actions. You do not need to install anything locally.
However if you wish to execute atmos locally, you will need to install Atmos. For installation instructions, visit the Atmos installation guide.
Prerequisites for Using Atmos Pro (Basic Example)
The following prerequisites are not required to run this demo example but are essential for using Atmos Pro effectively with real infrastructure:
To use GitHub Actions securely with Terraform, you'll need to set up GitHub OIDC with your cloud provider of choice.
⚠️ This example works without GitHub OIDC, but you'll need it in practice for GitHub Actions to authenticate properly with your cloud provider.
For more on setting this up with our reference architecture, please see How to use GitHub OIDC with AWS.
This example has plan storage disabled for simplicity. However, we recommend enabling it once the basics are working.
- Atmos Pro supports plan storage on AWS, GCP, and Azure.
- Plan storage lets you reuse the
.tfplanfile generated during theplanphase in theapplyphase—this is a Terraform best practice.
For more on setting this up with our reference architecture, please see Setup GitOps with GitHub Actions.
The example uses a local state backend, which is fine for demos without real cloud resources.
- In production, you should configure a remote state backend.
- Cloud Posse provides a reusable component for AWS. For GCP, Azure, etc., use your preferred backend configuration.
For more on setting this up with our reference architecture, please see .
Follow these steps to get started with this Atmos Pro example:
-
Fork this repository
- Click the "Fork" button in the top right corner of this repository on GitHub
-
Install the Atmos Pro GitHub App
- Follow the Atmos Pro documentation to sign up for Atmos Pro and install the GitHub App in your forked repository.
-
Set up GitHub Variables
ATMOS_PRO_WORKSPACE_ID- Your Atmos Pro workspace ID. Find your workspace ID.ATMOS_VERSION- The version of Atmos to use (e.g.,1.181.0)ATMOS_CONFIG_PATH- Path to your Atmos configuration file (e.g.,atmos.yaml)
For more information about GitHub variables, see the GitHub documentation.
Now to test it out, create a pull request and let Atmos Pro do the rest!
For example, you can modify an example component in stacks/deploy/nonprod.yaml and create a pull request on GitHub to trigger the Atmos Pro workflows. Try changing the value of foo, sit back, and see what happens!
This example demonstrates the minimal configuration needed to use Atmos Pro with GitHub Actions. The workflow follows these steps:
On Pull Requests
When a pull request is created or updated, Atmos Pro triggers atmos terraform plan:
- Developer makes a change - You modify your infrastructure code
- Code is pushed to feature branch - Changes are committed and pushed
- GitHub Actions trigger Atmos affected stacks - Atmos identifies which stacks are affected by your changes
- Atmos uploads affected stacks - The affected stack configurations are uploaded to Atmos Pro
- Atmos Pro dispatches plan workflows - Atmos Pro automatically runs
atmos terraform planfor affected components - Atmos Pro updates status comment - Results are posted as a comment on your pull request
This gives you visibility into what changes will be made to your infrastructure before merging.
sequenceDiagram
participant Dev as Developer
participant GH as GitHub
participant AA as GitHub Actions
participant Atmos as Atmos CLI
participant AP as Atmos Pro
participant TF as Terraform
participant AWS as AWS
Dev->>GH: Create/update PR
GH->>AA: Trigger workflow
AA->>Atmos: atmos affected stacks
Atmos->>Atmos: Identify affected stacks
Atmos->>AP: Upload affected stacks to Atmos Pro API
AP->>AA: Dispatch plan workflows
AA->>Atmos: atmos terraform plan
Atmos->>TF: terraform plan
TF->>AWS: Check current state
AWS->>TF: Current state
TF->>AA: Plan results
AA->>GH: Workflow status
AP->>GH: Check workflow status
AP->>GH: Update PR comment
On Merged Pull Requests
When a pull request is merged, Atmos Pro triggers atmos terraform apply:
- Pull request is merged - Your changes are merged into the main branch
- GitHub Actions trigger Atmos affected stacks - Atmos identifies which stacks need to be updated
- Atmos uploads affected stacks - The affected stack configurations are uploaded to Atmos Pro
- Atmos Pro dispatches apply workflows - Atmos Pro automatically runs
atmos terraform applyfor affected components - Atmos Pro updates status comment - Deployment results are posted as a comment on the merged PR
This ensures your infrastructure changes are automatically deployed when code is merged.
sequenceDiagram
participant Dev as Developer
participant GH as GitHub
participant AA as GitHub Actions
participant Atmos as Atmos CLI
participant AP as Atmos Pro
participant TF as Terraform
participant AWS as AWS
Dev->>GH: Merge PR
GH->>AA: Trigger workflow
AA->>Atmos: atmos affected stacks
Atmos->>Atmos: Identify affected stacks
Atmos->>AP: Upload affected stacks to Atmos Pro API
AP->>AA: Dispatch apply workflows
AA->>Atmos: atmos terraform apply
Atmos->>TF: terraform apply
TF->>AWS: Apply infrastructure changes
AWS->>TF: Apply results
TF->>AA: Apply results
AA->>GH: Workflow status
AP->>GH: Check workflow status
AP->>GH: Update PR comment
For more detailed configuration options and advanced features, refer to the Atmos Pro documentation.
To build the documentation for this repository, run:
atmos docs generate readmeThis command generates the README.md file from the README.yaml configuration.
.
├── .github/
│ ├── README.md # Generated README for GitHub
│ ├── README.md.gotmpl # Template for README generation
│ └── workflows/ # GitHub Actions workflows
│ ├── atmos-pro.yaml # Main Atmos Pro workflow
│ ├── atmos-terraform-apply.yaml
│ ├── atmos-terraform-plan.yaml
│ └── atmos-validate.yaml
├── README.yaml # Main documentation source
├── atmos.yaml # Atmos configuration
├── components/ # Infrastructure components
│ └── terraform/
│ ├── my-example-component-1/ # Example Terraform component 1
│ │ ├── README.md
│ │ └── main.tf
│ └── my-example-component-2/ # Example Terraform component 2
│ ├── README.md
│ └── main.tf
└── stacks/ # Atmos stack configurations
└── deploy/ # Deployment stacks
├── _defaults.yaml # Default stack settings
├── nonprod.yaml # Non-production environment
└── prod.yaml # Production environment
Preamble to the Apache License, Version 2.0
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
Copyright © 2017-2025 Cloud Posse, LLC