Skip to main content

GitHub Action: atmos-terraform-plan

This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given planfile to S3 and DynamoDB.


This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given planfile to S3 and DynamoDB.

After running this action, apply Terraform with the companion action, github-action-atmos-terraform-apply



This GitHub Action requires AWS access for two different purposes. This action will attempt to first run terraform plan against a given component and then will use another role to save that given Terraform Plan to an S3 Bucket with metadata in a DynamoDB table. We recommend configuring OpenID Connect with AWS to allow GitHub to assume roles in AWS and then deploying both a Terraform Plan role and a Terraform State role. For Cloud Posse documentation on setting up GitHub OIDC, see our github-oidc-provider component.

In order to store Terraform State, we configure an S3 Bucket to store plan files and a DynamoDB table to track plan metadata. Both will need to be deployed before running this action. For more on setting up those components, see the gitops component (documentation pending). This action will then use the github-action-terraform-plan-storage action to update these resources.

Workflow example

  name: github-action-atmos-terraform-plan

workflow_dispatch: {}
- opened
- synchronize
- reopened
- main

# These permissions are required for GitHub to assume roles in AWS
id-token: write
contents: read

runs-on: ubuntu-latest
- name: github-action-atmos-terraform-plan
uses: cloudposse/github-action-atmos-terraform-plan@v1
component: "foobar"
stack: "plat-ue2-sandbox"
component-path: "components/terraform/s3-bucket"
terraform-plan-role: "arn:aws:iam::111111111111:role/acme-core-gbl-identity-gitops"
terraform-state-bucket: "acme-core-ue2-auto-gitops"
terraform-state-role: "arn:aws:iam::999999999999:role/acme-core-ue2-auto-gitops-gha"
terraform-state-table: "acme-core-ue2-auto-gitops"
aws-region: "us-east-2"


atmos-config-pathThe path to the atmos.yaml fileatmos.yamlfalse
atmos-versionAtmos version to use for vendoring. Default 'latest'latestfalse
aws-regionAWS region for assuming
branding-logo-imageBranding logo image url
branding-logo-urlBranding logo url
componentThe name of the component to plan.N/Atrue
component-pathThe path to the base component. Atmos defines this value as component_path.N/Atrue
debugEnable action debug mode. Default: 'false'falsefalse
drift-detection-mode-enabledIndicate whether this action is used in drift detection workflow.falsetrue
enable-infracostWhether to enable infracost summary. Requires secret infracost-api-key to be specified. Default: 'falsefalsefalse
infracost-api-keyInfracost API keyN/Afalse
metadata-retention-daysInfracost API key1false
shaSHA to use${{ github.event.pull_request.head.sha }}true
stackThe stack name for the given component.N/Atrue
terraform-plan-roleThe AWS role to be used to plan Terraform.N/Atrue
terraform-state-bucketThe S3 Bucket where the planfiles are stored.N/Atrue
terraform-state-roleThe AWS role to be used to retrieve the planfile from AWS.N/Atrue
terraform-state-tableThe DynamoDB table where planfile metadata is stored.N/Atrue
terraform-versionThe version of Terraform CLI to install. Instead of full version string you can also specify constraint string starting with "<" (for example <1.13.0) to install the latest version satisfying the constraint. A value of latest will install the latest version of Terraform CLI. Defaults to latest.latestfalse
tokenUsed to pull node distributions for Atmos from Cloud Posse's GitHub repository. Since there's a default, this is typically not supplied by the user. When running this action on, the default value is sufficient. When running on GHES, you can pass a personal access token for if you are experiencing rate limiting.${{ github.server_url == '' && github.token || '' }}false