Migrate from GitHub Actions GitOps

This guide helps you migrate from the legacy GitHub Actions GitOps workflows to Atmos Pro. Atmos Pro provides a simplified and more powerful alternative with built-in dependency ordering, drift detection, and policy controls.

Overview

The legacy GitHub Actions GitOps approach required:

1. Custom GitHub Action workflows for plan, apply, drift detection, and remediation
2. Manual configuration of S3 buckets and DynamoDB tables for plan storage
3. Complex IAM role setup with aws-teams and aws-team-roles components
4. Custom workflow dispatch logic and matrix strategies

Atmos Pro replaces all of this with:

1. Three simple workflow files that Atmos Pro manages
2. Built-in plan storage and management
3. Simplified IAM setup using the iam-role component
4. Automatic dependency ordering and parallel execution

Migration Steps

Step 1: Set Up Atmos Pro

Follow the Atmos Pro Setup Guide to:

1. Sign up for Atmos Pro and create a workspace
2. Install the Atmos Pro GitHub App
3. Grant repository permissions
4. Add the three Atmos Pro workflow files

Step 2: Deploy New IAM Roles

Atmos Pro uses the iam-role component instead of aws-teams and aws-team-roles for GitHub Actions authentication. Deploy the new roles:

atmos workflow deploy/iam-role -f identity

This creates terraform and planner IAM roles in each account that GitHub Actions can assume via OIDC.

Step 3: Update GitHub OIDC Provider

Ensure the github-oidc-provider component is deployed to all accounts where Terraform will run:

atmos workflow deploy/github-oidc-provider -f github

Step 4: Test Atmos Pro Workflows

Before removing the legacy workflows:

1. Create a test pull request with a small change
2. Verify Atmos Pro comments on the PR with affected stacks
3. Verify plan workflows are dispatched and complete successfully
4. Merge the PR and verify apply workflows run correctly

Step 5: Remove Legacy Workflows

Once Atmos Pro is working correctly, remove the legacy workflow files:

1. .github/workflows/atmos-terraform-plan.yaml
2. .github/workflows/atmos-terraform-apply.yaml
3. .github/workflows/atmos-terraform-drift-detection.yaml
4. .github/workflows/atmos-terraform-drift-remediation.yaml
5. .github/workflows/atmos-terraform-dispatch.yaml
6. .github/workflows/atmos-terraform-plan-matrix.yaml
7. .github/workflows/atmos-terraform-apply-matrix.yaml

Step 6: Clean Up Legacy Infrastructure (Optional)

If you no longer need the legacy GitOps infrastructure, you can remove:

1. gitops/s3-bucket component — Plan file storage bucket
2. gitops/dynamodb component — Plan metadata table
3. gitops component — Legacy GitHub OIDC roles

Caution:

Only remove these components after confirming Atmos Pro is working correctly and you no longer need access to historical plan files.

Key Differences

Feature	Legacy GitOps	Atmos Pro
Workflow configuration	7+ custom workflow files	3 simple workflow files
Plan storage	Self-managed S3 + DynamoDB	Built-in
IAM roles	aws-teams + aws-team-roles	iam-role component
Dependency ordering	Manual or none	Automatic
Drift detection	Scheduled workflow	Built-in with dashboard
Policy controls	Custom implementation	Built-in

Troubleshooting

Workflows Not Triggering

If Atmos Pro workflows aren't being dispatched:

1. Verify the Atmos Pro GitHub App is installed and has access to the repository
2. Check that repository permissions are configured in the Atmos Pro console
3. Ensure the workflow files exist in the default branch

Authentication Errors

If workflows fail with authentication errors:

1. Verify github-oidc-provider is deployed to the target account
2. Check that iam-role components are deployed with correct trust policies
3. Ensure the workflow has id-token: write permission

See Also

1. Atmos Pro Setup — Complete setup guide
2. Atmos Pro Overview — Features and capabilities
3. Legacy GitOps Documentation — Reference for existing deployments