The Cloud Posse GitHub Action for "Atmos Terraform Plan" simplifies provisioning Terraform from within GitHub using workflows. Understand precisely what to expect from running a
terraform plan from directly within the GitHub UI for any Pull Request.
Given any component and stack in an Atmos supported infrastructure environment,
github-action-atmos-terraform-plan will run
atmos terraform plan, generate a Terraform planfile, store this planfile in an S3 Bucket with metadata in DynamodDB, and finally format the Terraform Plan result as part of a GitHub Workflow Job Summary.
This GitHub Action incorporates superior GitOps support for Terraform by utilizing the capabilities of Atmos, enabling efficient management of large enterprise-scale environments.
- Implements Native GitOps with Atmos and Terraform
- No hardcoded credentials. Use GitHub OIDC to assume roles.
- Compatible with GitHub Cloud & Self-hosted Runners for maximum flexibility.
- Beautiful Job Summaries don't clutter up pull requests with noisy GitHub comments
- 100% Open Source with Permissive APACHE2 License means you have no expensive subscriptions or long-term commitments.
The following screenshot showcases a successful "plan" Job Summary report. The report effectively utilizes badges to clearly indicate success or failure. Furthermore, it specifically highlights any potentially destructive operations, mitigating the risk of unintentional destructive actions. A
diff-style format is employed to illustrate the creation, recreation, destruction, or modification of resources. Unnecessary details are neatly hidden behind a collapsible
<details/> block, ensuring a streamlined view. Additionally, developers are provided with a direct link to access the job run, eliminating the need for manual searching to gather information about any potential issues.
By expanding the "Terraform Plan Summary" block (clicking on the
<details/> block), the full details of the plan are visible.
In this example, the action is triggered when certain events occur, such as a manual workflow dispatch or the opening, synchronization, or reopening of a pull request, specifically on the main branch. It specifies specific permissions related to assuming roles in AWS. Within the "plan" job, the "component" and "stack" are hardcoded. In practice, these are usually derived from another action.
# These permissions are required for GitHub to assume roles in AWS
- name: Plan Atmos Component
Please note that in practice, we recommend combining this action with the
affected-stacks GitHub Action inside a matrix to plan all affected stacks in parallel.
This GitHub Action depends on a few resources:
- S3 bucket for storing planfiles
- DynamoDB table for retrieving metadata about planfiles
- 2x IAM roles for "planning" and accessing the "state" bucket
This action can use any S3 Bucket to keep track of your planfiles. Just ensure the bucket is properly locked down since planfiles may contain secrets.
# S3 Bucket for storing Terraform Plans
Assign this S3 Bucket ARN to the
Similarly, a simple DynamoDB table can be provisioned using our
dynamodb component. Set the Hash Key and create a Global Secondary Index as follows:
# DynamoDB table used to store metadata for Terraform Plans
# This key (case-sensitive) is required for the cloudposse/github-action-terraform-plan-storage action
# Only these 2 attributes are required for creating the GSI,
# but there will be several other attributes on the table itself
- name: 'createdAt'
- name: 'pr'
# This GSI is used to Query the latest plan file for a given PR.
- name: pr-createdAt-index
# Auto delete old entries
Pass the ARN of this table as the input to the
terraform-plan-table of the
cloudposse/github-action-atmos-terraform-plan GitHub Action.
IAM Access Roles
First create an access role for storing and retrieving planfiles from the S3 Bucket and DynamoDB table. We deploy this role using the
gitops component. Assign this role ARN to the
Next, create a role for GitHub workflows to use to plan and apply Terraform. We typically create an "AWS Team" with our
aws-teams component, and then allow this team to assume
terraform in the delegated accounts with our
aws-team-roles component. Assign this role ARN to the