# GitHub Actions (Deprecated)

:::warning Deprecated
These community-maintained GitHub Actions predate Atmos's [native CI integration](/ci). 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 →](/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](/ci/planfile-storage) (S3, GitHub Artifacts, or local) |

## Deprecated Actions

## 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](/vendor/) the [`s3-component`](https://docs.cloudposse.com/components/library/aws/s3-bucket/), then using an [Atmos stack configuration](/learn/stacks/), define a bucket using the [`s3-bucket` component](https://github.com/cloudposse/terraform-aws-components/tree/main/modules/s3-bucket) with this catalog configuration:

**File:** `stacks/catalog/s3-bucket/gitops.yaml`

```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](https://docs.cloudposse.com/components/library/aws/dynamodb/). Set the **Hash Key** and create a **Global Secondary Index** as follows:

**File:** `stacks/catalog/dynamodb/gitops.yaml`

```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`](https://github.com/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](https://docs.cloudposse.com/components/library/aws/gitops/). 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](https://docs.cloudposse.com/components/library/aws/aws-teams/), and then allow this team to assume `terraform` in the delegated accounts with our [`aws-team-roles` component](https://docs.cloudposse.com/components/library/aws/aws-team-roles/). 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:

**File:** `rootfs/usr/local/etc/atmos/atmos.yaml`

```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 Important!

Our GitHub Actions depend on specific versions of Atmos.

:::

### Artifacts Upgrade

With version `v2` of
[cloudposse/github-action-atmos-terraform-drift-detection](https://github.com/cloudposse/github-action-atmos-terraform-drift-detection)
and version `v3` of
[cloudposse/github-action-atmos-terraform-plan](https://github.com/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`](https://github.com/cloudposse/github-action-atmos-affected-stacks)                         | [`v2`](https://github.com/cloudposse/github-action-atmos-affected-stacks/tree/v2)             | [`v1`](https://github.com/cloudposse/github-action-atmos-affected-stacks/tree/v1) or greater             |
| [`github-action-atmos-terraform-plan`](https://github.com/cloudposse/github-action-atmos-terraform-plan)                           | [`v1`](https://github.com/cloudposse/github-action-atmos-terraform-plan/tree/v1)              | [`v2`](https://github.com/cloudposse/github-action-atmos-terraform-plan/tree/v2) or greater              |
| [`github-action-atmos-terraform-apply`](https://github.com/cloudposse/github-action-atmos-terraform-apply)                         | [`v1`](https://github.com/cloudposse/github-action-atmos-terraform-apply/tree/v1)             | [`v2`](https://github.com/cloudposse/github-action-atmos-terraform-apply/tree/v2) or greater             |
| [`github-action-atmos-terraform-drift-remediation`](https://github.com/cloudposse/github-action-atmos-terraform-drift-remediation) | [`v1`](https://github.com/cloudposse/github-action-atmos-terraform-drift-remediation/tree/v1) | [`v2`](https://github.com/cloudposse/github-action-atmos-terraform-drift-remediation/tree/v2) or greater |
| [`github-action-atmos-terraform-drift-detection`](https://github.com/cloudposse/github-action-atmos-terraform-drift-detection)     | [`v0`](https://github.com/cloudposse/github-action-atmos-terraform-drift-detection/tree/v0)   | [`v1`](https://github.com/cloudposse/github-action-atmos-terraform-drift-detection/tree/v1) or greater   |