GitHub Actions (Deprecated)

Deprecated

These community-maintained GitHub Actions predate Atmos's native CI integration. New projects should run atmos terraform plan/apply/deploy directly in their workflows — Atmos itself produces job summaries, output variables, status checks, and stored planfiles without a wrapper action.

The action-based docs below are kept here for reference for teams still running them, but they are no longer the recommended approach.

Get started with Native CI →

This collection of GitHub Actions was designed to work specifically with Atmos in an opinionated manner, enabling change management entirely within the GitHub UI. They depend on a stack of supporting infrastructure (S3 + DynamoDB for planfile storage, IAM roles for OIDC) that native CI replaces with built-in Atmos features.

Native CI Equivalents

Capability	Legacy action	Native CI replacement
Plan with job summary	cloudposse/github-action-atmos-terraform-plan	atmos terraform plan (writes to $GITHUB_STEP_SUMMARY)
Apply stored planfile	cloudposse/github-action-atmos-terraform-apply	atmos terraform apply / atmos terraform deploy
Affected stacks matrix	cloudposse/github-action-atmos-affected-stacks	atmos describe affected --format=matrix
Drift detection	cloudposse/github-action-atmos-terraform-drift-detection	Scheduled workflow running atmos terraform plan
Drift remediation	cloudposse/github-action-atmos-terraform-drift-remediation	atmos terraform deploy triggered from an issue
Planfile storage	S3 + DynamoDB managed by the action	Built-in planfile storage (S3, GitHub Artifacts, or local)

Deprecated Actions

📄️ Affected Stacks

Identify the affected stacks and components in a pull request

📄️ Terraform Apply

Run a `terraform apply` to provision changes

📄️ Terraform Drift Detection

Identify drift and create GitHub Issues for remediation

📄️ Terraform Drift Remediation

Remediate Terraform drift using IssueOps

📄️ Terraform Plan

Run a `terraform plan` to understand the impact of changes

Requirements

GitHub Actions that utilize "plan file" storage 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
• atmos.yaml config with GitOps settings

S3 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.

For example, vendor in the s3-component, then using an Atmos stack configuration, define a bucket using the s3-bucket component with this catalog configuration:

stacks/catalog/s3-bucket/gitops.yaml

import:
  - catalog/s3-bucket/defaults

components:
  terraform:
    # S3 Bucket for storing Terraform Plans
    gitops/s3-bucket:
      metadata:
        component: s3-bucket
        inherits:
          - s3-bucket/defaults
      vars:
        name: gitops-plan-storage
        allow_encrypted_uploads_only: false

Assign this S3 Bucket ARN to the terraform-plan-bucket input.

DynamoDB Table

Similarly, a simple DynamoDB table can be provisioned using our dynamodb component. Set the Hash Key and create a Global Secondary Index as follows:

stacks/catalog/dynamodb/gitops.yaml

import:
  - catalog/dynamodb/defaults

components:
  terraform:
    # DynamoDB table used to store metadata for Terraform Plans
    gitops/dynamodb:
      metadata:
        component: dynamodb
        inherits:
          - dynamodb/defaults
      vars:
        name: gitops-plan-storage
        # This key (case-sensitive) is required for the cloudposse/github-action-terraform-plan-storage action
        hash_key: id
        range_key: ""
        # Only these 2 attributes are required for creating the GSI,
        # but there will be several other attributes on the table itself
        dynamodb_attributes:
          - name: 'createdAt'
            type: 'S'
          - name: 'pr'
            type: 'N'
        # This GSI is used to Query the latest plan file for a given PR.
        global_secondary_index_map:
          - name: pr-createdAt-index
            hash_key: pr
            range_key: createdAt
            projection_type: ALL
            non_key_attributes: []
            read_capacity: null
            write_capacity: null
        # Auto delete old entries
        ttl_enabled: true
        ttl_attribute: ttl

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 terraform-state-role input.

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 terraform-plan-role input

Atmos Configuration

The actions that works with atmos >= 1.63.0 expects the Atmos configuration file atmos.yaml to be present in the repository. The config should have the following structure:

rootfs/usr/local/etc/atmos/atmos.yaml

integrations:
  github:
    gitops:
      terraform-version: 1.5.2
      infracost-enabled: false
      artifact-storage:
        region: us-east-2
        bucket: cptest-core-ue2-auto-gitops
        table: cptest-core-ue2-auto-gitops-plan-storage
        role: arn:aws:iam::xxxxxxxxxxxx:role/cptest-core-ue2-auto-gitops-gha
      role:
        plan: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
        apply: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
      matrix:
        sort-by: .stack_slug
        group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")

For actions that use atmos < 1.63.0 the settings passed as github action inputs. Please follow documentation for each action to see the required inputs.

Compatibility Matrix

Important!

Our GitHub Actions depend on specific versions of Atmos.

Artifacts Upgrade

With version v2 of cloudposse/github-action-atmos-terraform-drift-detection and version v3 of cloudposse/github-action-atmos-terraform-plan, the artifact storage configuration was updated to use the same structure. Both will need to be updated to these versions or later to pass artifacts across the actions.

Please see the release notes:

1. https://github.com/cloudposse/github-action-atmos-terraform-plan/releases/tag/v3.0.0
2. https://github.com/cloudposse/github-action-atmos-terraform-drift-detection/releases/tag/v2.0.0

Atmos < 1.63.0

If you are using Atmos < 1.63.0, please refer to the following table:

Github action	Atmos < 1.63.0	Atmos >= 1.63.0
github-action-atmos-affected-stacks	v2	v1 or greater
github-action-atmos-terraform-plan	v1	v2 or greater
github-action-atmos-terraform-apply	v1	v2 or greater
github-action-atmos-terraform-drift-remediation	v1	v2 or greater
github-action-atmos-terraform-drift-detection	v0	v1 or greater