Preview infrastructure changes in a pull request
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
- Push
dev. CI runs the tests. - Open a pull request from
devtomain. A workflow signs in to AWS with a read-only role and runspulumi preview --diff. It posts the result as a comment on the pull request and edits that comment on each new push. - Read the comment. A content-only release should show no changes.
A
replaceordeleteon the bucket, the distribution, or the certificate needs a second look. - Release. Fast-forward
maintodevand push. GitHub marks the pull request merged, because its commits are now onmain.
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:
| Role | Trusted by | Can |
|---|---|---|
skunkyard-github-deploy | Pushes to main |
Change the bucket, DNS records, certificate, and CDN |
skunkyard-github-preview | Pull 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:
- Created by hand, once. The CloudFormation bootstrap holds a
boundary policy,
skunkyard-preview-boundary, that allows reading and Pulumi's lock files. It also lets the deploy role create and change exactly one role,skunkyard-github-preview, and only while that boundary is attached:Condition: StringEquals: iam:PermissionsBoundary: !Ref PreviewBoundary - Deployed by GitHub Actions. The Pulumi program defines the role, its trust policy, and its permissions. A change to any of them ships like any other release.
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
- The pull request's code gets the passphrase. Anyone who can push a branch can run code with the read-only role and the Pulumi passphrase. GitHub withholds secrets from pull requests opened from forks, so this matters only for people with write access.
- A preview is a forecast. If someone changes AWS by hand, or another release lands first, the deploy can differ from what the comment showed.
- Some values are unknown. A resource the release creates has no ID yet, so anything that uses that ID shows as unknown.
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.