Plan on Pull Request, Apply on Merge — with OIDC

1. 1

   Trust GitHub from AWS (in the bootstrap config, per account)

   One OIDC provider per account, and two roles. The PLAN role trusts any pull request from your repo and gets read-only access plus state access (it needs to write the lock file). The DEPLOYER role, which you've been assuming yourself since Mission 6.3, now also trusts GitHub, but ONLY for runs in the dev or prod GitHub environment. Apply this with the bootstrap config in each account.

   variable "github_repo" {
     type    = string
     default = "you/shoplite"
   }
   
   variable "environment" {
     type = string # dev or prod — which account this bootstrap runs in
   }
   
   resource "aws_iam_openid_connect_provider" "github" {
     url            = "https://token.actions.githubusercontent.com"
     client_id_list = ["sts.amazonaws.com"]
   }
   
   data "aws_iam_policy_document" "ci_plan_trust" {
     statement {
       actions = ["sts:AssumeRoleWithWebIdentity"]
       principals {
         type        = "Federated"
         identifiers = [aws_iam_openid_connect_provider.github.arn]
       }
       condition {
         test     = "StringEquals"
         variable = "token.actions.githubusercontent.com:aud"
         values   = ["sts.amazonaws.com"]
       }
       condition {
         test     = "StringEquals"
         variable = "token.actions.githubusercontent.com:sub"
         values   = ["repo:${var.github_repo}:pull_request"]
       }
     }
   }
   
   resource "aws_iam_role" "ci_plan" {
     name               = "shoplite-ci-plan"
     assume_role_policy = data.aws_iam_policy_document.ci_plan_trust.json
   }
   
   resource "aws_iam_role_policy_attachment" "ci_plan_readonly" {
     role       = aws_iam_role.ci_plan.name
     policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
   }
   
   data "aws_iam_policy_document" "ci_plan_state" {
     statement {
       sid       = "StateReadAndLock"
       actions   = ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"]
       resources = [aws_s3_bucket.tfstate.arn, "${aws_s3_bucket.tfstate.arn}/*"]
     }
     statement {
       sid       = "NeverReadSecretValues"
       effect    = "Deny"
       actions   = ["secretsmanager:GetSecretValue"]
       resources = ["*"]
     }
   }
   
   resource "aws_iam_role_policy" "ci_plan_state" {
     role   = aws_iam_role.ci_plan.id
     policy = data.aws_iam_policy_document.ci_plan_state.json
   }
   
   # The deployer role (created during account setup) gets an extra trust statement:
   #   sub = "repo:${var.github_repo}:environment:${var.environment}"
   # so only jobs running in the matching GitHub Environment can assume it.

2. 2

   Create GitHub Environments

   In the repo settings, create environments dev and prod. Give prod REQUIRED REVIEWERS (you, or your team) and restrict it to the main branch. Store each environment's account ID as an environment variable, AWS_ACCOUNT_ID, and also as repository variables DEV_ACCOUNT_ID and PROD_ACCOUNT_ID for the PR plan matrix. These aren't secrets; OIDC needs none.
3. 3

   The workflow

   Read it in three parts. plan runs for pull requests as a matrix over both environments with the read-only role, and posts each plan as a PR comment. apply-dev runs on push to main, re-plans, and applies that saved plan. apply-prod needs apply-dev and runs in the prod environment, so it waits for approval. concurrency serialises runs per environment and never cancels a running apply.

   name: terraform
   
   on:
     pull_request:
       paths: ["infra/**", "modules/**"]
     push:
       branches: [main]
       paths: ["infra/**", "modules/**"]
   
   permissions:
     id-token: write      # OIDC token for AWS
     contents: read
     pull-requests: write # plan comments
   
   env:
     TF_IN_AUTOMATION: "true"
     TF_INPUT: "false"
     AWS_REGION: ap-south-1
   
   jobs:
     plan:
       if: github.event_name == 'pull_request'
       runs-on: ubuntu-latest
       strategy:
         fail-fast: false
         matrix:
           env: [dev, prod]
       concurrency: plan-${{ matrix.env }}-${{ github.head_ref }}
       steps:
         - uses: actions/checkout@v4
         - uses: hashicorp/setup-terraform@v3
           with:
             terraform_version: 1.13.3
             terraform_wrapper: false
         - uses: aws-actions/configure-aws-credentials@v4
           with:
             role-to-assume: arn:aws:iam::${{ vars[format('{0}_ACCOUNT_ID', matrix.env)] }}:role/shoplite-ci-plan
             aws-region: ${{ env.AWS_REGION }}
         - name: fmt
           run: terraform fmt -check -recursive
         - name: plan
           working-directory: infra
           run: |
             ./tf ${{ matrix.env }} validate
             ./tf ${{ matrix.env }} plan -lock-timeout=5m -no-color -out=tfplan
             terraform show -no-color tfplan > plan.txt
         - name: comment
           uses: actions/github-script@v7
           with:
             script: |
               const plan = require('fs').readFileSync('infra/plan.txt', 'utf8');
               const summary = plan.split('\n').find(l => l.startsWith('Plan:') || l.startsWith('No changes')) ?? '';
               const body = `### \`${{ matrix.env }}\` — ${summary}\n<details><summary>Full plan</summary>\n\n\`\`\`\n${plan.slice(-60000)}\n\`\`\`\n</details>`;
               await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body });
   
     apply-dev:
       if: github.event_name == 'push'
       runs-on: ubuntu-latest
       environment: dev
       concurrency:
         group: apply-dev
         cancel-in-progress: false
       steps: &apply-steps
         - uses: actions/checkout@v4
         - uses: hashicorp/setup-terraform@v3
           with:
             terraform_version: 1.13.3
             terraform_wrapper: false
         - uses: aws-actions/configure-aws-credentials@v4
           with:
             role-to-assume: arn:aws:iam::${{ vars.AWS_ACCOUNT_ID }}:role/shoplite-deployer
             aws-region: ${{ env.AWS_REGION }}
         - name: plan and apply
           working-directory: infra
           run: |
             ./tf ${{ github.job == 'apply-prod' && 'prod' || 'dev' }} plan -lock-timeout=5m -out=tfplan
             terraform apply -lock-timeout=5m tfplan
   
     apply-prod:
       if: github.event_name == 'push'
       needs: apply-dev
       runs-on: ubuntu-latest
       environment: prod     # required reviewers → the job waits for approval
       concurrency:
         group: apply-prod
         cancel-in-progress: false
       steps: *apply-steps

4. 4

   Open a pull request and watch

   Change something small: bump api_memory to 1024 in envs/dev.tfvars. The PR gets two comments. Dev shows one task definition replacement and a service update; prod shows No changes. Reviewers approve based on those comments, not on reading HCL diffs alone.

   terminalcopy cmd

   $ git switch -c api-memory && sed -i 's/^api_memory.*//' infra/envs/dev.tfvars && echo 'api_memory = 1024' >> infra/envs/dev.tfvars

   git commit -am 'dev: api memory 1024' && git push -u origin api-memory && gh pr create --fill

   ── expected output ──

   https://github.com/you/shoplite/pull/42

    

   # PR comments posted by the workflow:

   ### `dev` — Plan: 1 to add, 1 to change, 1 to destroy.

   ### `prod` — No changes. Your infrastructure matches the configuration.

5. 5

   Merge: dev applies, prod waits for you

   After merging, apply-dev runs immediately. apply-prod shows 'Waiting for review' until a required reviewer approves in the Actions UI. Here prod has nothing to do, but the gate is always there. From now on, stop applying from your laptop.

   terminalcopy cmd

   $ gh pr merge 42 --squash && gh run watch

   ── expected output ──

   ✓ apply-dev Apply complete! Resources: 1 added, 1 changed, 1 destroyed.

   * apply-prod Waiting for review: prod needs approval to start deploying changes.

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.