Skip to main content

GitHub Actions

GitHub Actions are a powerful way to automate your workflows with Atmos. Use these actions to plan, apply, and manage your Terraform infrastructure with Atmos.

This collection of GitHub Actions is designed to work specifically with Atmos in an opinionated manner, enabling you to implement a modern change management system entirely within the native GitHub UI. These Actions use the standard atmos.yaml configuration and some backing services designed to properly manage Terraform plan files, including their invalidation.

These GitHub Actions stribe to be cloud-agnostic; however, most of our instructions focus on AWS, where we predominantly use them. None of these actions require hardcoded credentials, and all work using GitHub OIDC and GitHub Apps managed by your organization. These Actions do not require any subscriptions and are based entirely on open source.

GitHub Actions for Atmos

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.

Please refer to the table below.

Github actionAtmos < 1.63.0Atmos >= 1.63.0
github-action-atmos-affected-stacksv2v1
github-action-atmos-terraform-planv1v2
github-action-atmos-terraform-applyv1v2
github-action-atmos-terraform-drift-remediationv1v2
github-action-atmos-terraform-drift-detectionv0v1