Skip to main content

GitHub Action: atmos-terraform-apply

This Github Action is used to run Terraform apply for a single, Atmos-supported component with a saved planfile in S3 and DynamoDB.


This Github Action is used to run Terraform apply for a single, Atmos-supported component with a saved planfile in S3 and DynamoDB.

Before running this action, first create and store a planfile with the companion action, github-action-atmos-terraform-plan.

For more, see Atmos GitHub Action Integrations



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

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


The action expects the atmos gitops configuration file to be present in the repository in ./.github/config/atmos-gitops.yaml. The config should have the following structure:

  atmos-version: 1.45.3
atmos-config-path: ./rootfs/usr/local/etc/atmos/
terraform-state-bucket: cptest-core-ue2-auto-gitops
terraform-state-table: cptest-core-ue2-auto-gitops
terraform-state-role: arn:aws:iam::xxxxxxxxxxxx:role/cptest-core-ue2-auto-gitops-gha
terraform-plan-role: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
terraform-apply-role: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
terraform-version: 1.5.2
aws-region: us-east-2
enable-infracost: false
sort-by: .stack_slug
group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")

Workflow example

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 "apply" job, the "component" and "stack" are hardcoded (foobar and plat-ue2-sandbox). In practice, these are usually derived from another action.

[!TIP] We recommend combining this action with the affected-stacks GitHub Action inside a matrix to plan all affected stacks in parallel.

  name: github-action-atmos-terraform-apply

- closed
- 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-apply
uses: cloudposse/github-action-atmos-terraform-apply@v2
component: "foobar"
stack: "plat-ue2-sandbox"

Migrating from v1 to v2

  1. v2 drops the component-path variable and instead fetches if directly from the atmos.yaml file automatically. Simply remove the component-path argument from your invocations of the cloudposse/github-action-atmos-terraform-apply action.
  2. v2 moves most of the inputs to the Atmos GitOps config path ./.github/config/atmos-gitops.yaml. Simply create this file, transfer your settings to it, then remove the corresponding arguments from your invocations of the cloudposse/github-action-atmos-terraform-apply action.

If you want the same behavior in v2 as in v1 you should create config ./.github/config/atmos-gitops.yaml with the same variables as in v1 inputs.

- name: github-action-atmos-terraform-apply
uses: cloudposse/github-action-atmos-terraform-apply@v2
atmos-gitops-config-path: ./.github/config/atmos-gitops.yaml
component: "foobar"
stack: "plat-ue2-sandbox"

Which would produce the same behavior as in v1, doing this:

- name: github-action-atmos-terraform-apply
uses: cloudposse/github-action-atmos-terraform-apply@v1
component: "foobar"
stack: "plat-ue2-sandbox"
component-path: "components/terraform/s3-bucket"
terraform-apply-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-gitops-config-pathThe path to the atmos-gitops.yaml file./.github/config/atmos-gitops.yamlfalse
branding-logo-imageBranding logo image url
branding-logo-urlBranding logo url
componentThe name of the component to apply.N/Atrue
debugEnable action debug mode. Default: 'false'falsefalse
infracost-api-keyInfracost API keyN/Afalse
shaCommit SHA to apply. Default: github.sha${{ github.event.pull_request.head.sha }}true
stackThe stack name for the given component.N/Atrue
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


statusApply Status. Either 'succeeded' or 'failed'