Configure Integrations

​

Overview

• AWS: Account IDs and role ARNs for Terraform
• GitHub (octo-sts): Tokens for managing GitHub organization resources
• Terramate Cloud (optional): Plan visualization and drift detection

​

Verify Terraform Configuration

globals {
  namespace = "<NAMESPACE>"

  # These were set during bootstrap
  github_oidc_assume_role_arn = "arn:aws:iam::<INFRA_ACCOUNT_ID>:role/<NAMESPACE>-gbl-infra-bootstrap-github-oidc"
  sso_admin_assume_role_arn   = "arn:aws:iam::<INFRA_ACCOUNT_ID>:role/aws-reserved/sso.amazonaws.com/<AWS_REGION>/AWSReservedSSO_AdministratorAccess_XXXXX"
  backend_bucket              = "<NAMESPACE>-gbl-infra-bootstrap-state"
  backend_region              = "<AWS_REGION>"
}

​

Configure GitHub Repository Variables

​

Update GitHub Workflows

# In .github/workflows/terramate-preview.yml, terramate-deploy.yml, and terramate-detect-drift.yml
- name: "Configure AWS Credentials"
  uses: aws-actions/configure-aws-credentials@v4
  with:
    aws-region: ${{ vars.TERRAFORM_AWS_REGION }}
    role-to-assume: ${{ vars.TERRAFORM_AWS_ROLE_ARN }}

​

Configure octo-sts for GitHub Tokens

issuer: https://token.actions.githubusercontent.com
subject_pattern: "^repo:<YOUR_ORG>/<your-repo>:.*"
claim_pattern:
  workflow_ref: '^<YOUR_ORG>/<your-repo>/\.github/workflows/terramate.*@refs/.*$'

permissions:
  administration: write
  metadata: read
  members: write
  contents: read

issuer: https://token.actions.githubusercontent.com
subject: "repo:<YOUR_ORG>/<your-repo>:ref:refs/heads/main"

permissions:
  contents: write
  pull_requests: write

​

Configure Terramate Cloud (Optional)

1. Create an account at cloud.terramate.io (EU) OR us.cloud.terramate.io (US)
2. Install the GitHub App from your Terramate Cloud dashboard under Integrations to enable PR comments and status checks
3. Update the cloud_organization in .github/workflows/terramate-preview.yml and other Terramate workflows:

- name: Install Terramate
  uses: terramate-io/terramate-action@0500f8a40b57a793a41edd2aea0a49e31c7204e8 # v3.2.0
  with:
    version: "0.15.1"
    cloud_organization: your-terramate-org

​

Search for Remaining References

# Find references to the original organization
grep -r "DevOps-Directive" .github/
grep -r "094905625236" .  # Original AWS account ID

​

Verify Your Setup

cd terraform
terramate fmt --check
terramate generate

​

Commit Your Changes

git add .
git commit -m "chore: configure AWS account IDs and role ARNs"
git push

​

Verify CI/CD

1. Check the workflow run in the Actions tab
2. The Configure AWS Credentials step should succeed
3. Terraform plan output should appear (if using Terramate Cloud, check the PR comments)

​

Troubleshooting

​

”Access Denied” when assuming cross-account role

1. GitHub → Infrastructure account: Check the OIDC role trust policy
   # Run from Infrastructure account (replace <NAMESPACE> with your namespace)
   aws iam get-role --role-name "<NAMESPACE>-gbl-infra-bootstrap-github-oidc" \
     --query 'Role.AssumeRolePolicyDocument'
   
2. Infrastructure account → Target account: Check the target role trust policy
   # Run from target account (e.g. staging)
   aws iam get-role --role-name "<NAMESPACE>-gbl-staging-bootstrap-admin" \
     --query 'Role.AssumeRolePolicyDocument'
   

​

GitHub Actions can’t authenticate

1. Verify the OIDC provider exists in the Infrastructure account:
   aws iam list-open-id-connect-providers
   
2. Check the GitHub OIDC role trust policy allows your repository:
   # Replace <NAMESPACE> with your namespace
   aws iam get-role --role-name "<NAMESPACE>-gbl-infra-bootstrap-github-oidc" \
     --query 'Role.AssumeRolePolicyDocument'
   
3. Ensure the repository name in the trust policy matches exactly (case-sensitive, including organization name).

​

Next Steps