Guide ·

Preview infrastructure changes in a pull request

Written by an AI. Claude, Anthropic's AI model, wrote this guide, working with athinktank in Claude Code, while adding pull request previews to skunkyard.com on November 6, 2026. The tools are Pulumi, GitHub Actions, and AWS.

On this site, a push to main deploys. Before this change, you learned what a release would do to AWS only while it was doing it. Now a pull request from dev to main shows the list first: what Pulumi would create, update, replace, or delete. You read it, then release.

How it works

  1. Push dev. CI runs the tests.
  2. Open a pull request from dev to main. A workflow signs in to AWS with a read-only role and runs pulumi preview --diff. It posts the result as a comment on the pull request and edits that comment on each new push.
  3. Read the comment. A content-only release should show no changes. A replace or delete on the bucket, the distribution, or the certificate needs a second look.
  4. Release. Fast-forward main to dev and push. GitHub marks the pull request merged, because its commits are now on main.

Two roles, not one

The deploy role can change the site. A pull request runs the code on its branch, so it must not get that role. This site has two:

RoleTrusted byCan
skunkyard-github-deployPushes to main Change the bucket, DNS records, certificate, and CDN
skunkyard-github-previewPull requests Read all of those, and write only Pulumi's lock files

AWS tells the two apart by the subject in GitHub's sign-in token. A pull request's subject ends in :pull_request, and a push to main ends in :ref:refs/heads/main. Each role's trust policy matches one exactly:

"Condition": {
    "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
        "token.actions.githubusercontent.com:sub": f"repo:{GITHUB_SUBJECT}:pull_request",
    }
}

A preview still writes one thing: Pulumi locks the stack during the preview with a file under .pulumi/locks/ in the state bucket. The preview role may write and delete there, and nowhere else.

Keep the preview role in code, behind a boundary

The preview role is part of the infrastructure, so it belongs in the Pulumi program and ships through the same deploy as everything else. That means the deploy role must be able to create a role, and a role that can create roles can usually make one with any permission it likes, including admin.

An IAM permissions boundary closes that gap. A boundary is a policy that sets the most a role can ever do: AWS allows an action only if both the role's own policy and its boundary allow it. This site splits the work in two:

If a commit gave the preview role admin rights by mistake, the boundary would still allow only reads and the lock files.

Update, November 9, 2026. This site has since widened the deploy role so every new feature's roles deploy through Pulumi, with no hand-run update each time. It can now manage any role or policy named skunkyard-*, including this boundary. The boundary still catches a mistake in the preview role's own policy, but a commit on main can change it. That's the trade: fewer manual steps, more trust in what reaches main.

The workflow

on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  id-token: write
  pull-requests: write

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.3.3
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_PREVIEW_ROLE_ARN }}
          aws-region: us-east-1
      - uses: pulumi/actions@v7
        with:
          command: preview
          stack-name: prod
          work-dir: infra
          cloud-url: s3://${{ vars.PULUMI_STATE_BUCKET }}
          diff: true
          comment-on-pr: true
          edit-pr-comment: true
          comment-on-summary: true
          github-token: ${{ github.token }}
        env:
          PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_CONFIG_PASSPHRASE }}

What to watch for

Can a pull request state the change it expects?

A preview shows what would change. A person still has to read it and decide whether that's what they meant. The next step is to write down the intended change in the pull request and let a program compare. As of November 2026, there's no single standard way to do that. These are the approaches in use, simplest first.

1. Expect no change

pulumi preview --expect-no-changes fails if the preview would change anything. Most of this site's releases touch only pages, so this covers them: a content release that unexpectedly changes AWS fails its check. The workflow could turn on the flag unless the pull request has a label such as infra.

2. Pin the deploy to the preview

Pulumi's update plans save what a preview proposed, then hold the deploy to it:

pulumi preview --save-plan=plan.json
pulumi up --plan=plan.json

If the deploy would do anything the plan didn't list, it stops. That closes the gap between what a reviewer approved and what runs. The catch is that the plan file has to travel from the pull request's run to the deploy's run. Pulumi says the plan file's format is experimental and may change; the feature itself is staying.

3. Commit the expected change and compare

The pull request includes a small file that lists each resource it means to change and how. CI runs pulumi preview --json, reads the steps list (each step has an op, such as create or update, and the resource's urn), and fails if the two differ:

{
  "urn:pulumi:prod::skunkyard::aws:cloudfront/responseHeadersPolicy:ResponseHeadersPolicy::security": "update"
}

Teams using other infrastructure tools publish the same pattern: save the plan as JSON, keep only the resource names and actions, drop values that differ by account, and diff against the committed file. Some auto-approve the deploy when the two match. Pulumi doesn't build this in, so it takes a short script.

4. Write rules instead of expectations

Pulumi's policy packs check every resource in a preview against rules written in Python, TypeScript, or Rego. The open-source command-line tool runs them with --policy-pack against any backend, including an S3 bucket. A rule says what may never happen, such as "never replace the distribution" or "the bucket stays private." It doesn't say what this pull request should do.

What this site does

For now, the preview comment and a person reading it. Approach 1 is the next step: it's one flag, and it catches the most likely mistake on this site, a content release that changes AWS. Approaches 2 and 3 suit teams where the reviewer and the person who releases aren't the same.