Document component state migrations

[julienp]

Introduced in https://github.com/pulumi/pulumi/releases/tag/v3.264.0

[github-actions]

Sentinel — merge gate status (preview)

Warning

⚠️ Preview mode — this check is NOT blocking your merge

The Sentinel is in preview (report-only) mode: its check-run concludes neutral whatever the gates below say, so nothing here gates this PR. The rows are informational and safe to ignore for now. It would have concluded failure.

This will be enforced in the near future. Once it is, every row below has to be green before this PR can merge. The rows are the sign-offs a merge needs — some yours, some a reviewer's or a deploy's. Tell us in #docs if one looks wrong.

2 of 5 gates would block this merge once the Sentinel is enforced.

	Gate	What it needs
🔴	G1 review-ran	No current review for 4d413a383 — push to refresh, comment @claude #update-review, or flip the PR to draft and back to ready.
✅	G2 findings-answered	Nothing to do: every finding answered.
🔴	G3 right-approver	Needs approval from a member of any review team (pulumi/docs-blog-review, pulumi/docs-guild, pulumi/docs-marketing-review, pulumi/docs-tools) or a repository administrator — no qualifying human approval at this head (bot approvals never count). CamSoper approved an earlier commit; re-approve at 4d413a383.
➖	G4 infra-evidence	Doesn't apply to this PR: no changed path affects the deploy.
➖	G5 oversized-ack	Doesn't apply to this PR: not oversized.

Break glass: a member of a routing team (.github/review-routing.yml teams:) can apply review:waived, which is logged.

_{Evaluated at head 4d413a383.}

[pulumi-bot]

Your site preview for commit 4d413a3 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-21865-4d413a38.s3-website.us-west-2.amazonaws.com

Changed pages:

• /docs/iac/concepts/resources/options/statemigrations/
• /docs/iac/guides/building-extending/components/build-a-component/
• /docs/iac/guides/building-extending/components/state-migrations/

[github-actions]

Reviewer's guide v2 — not for the author

Tip

This is the reviewer's guide. Work through the ⚠️ checklist below, then approve — approving asserts only that the ⚠️ items looked right to you. Machine-verified this run: links, shortcodes, page metadata, and every claim marked verified (receipts on the evidence page). Code samples are read, not compiled.

PR author: your to-do list is the other review comment, "Author action guide" — nothing on this card is yours.

Approval needed from: @pulumi/docs-guild — any member's approval satisfies the merge gate.

Note

What this PR changes:

• New guide: component state migrations (state-migrations.md).
• New resource option reference page: stateMigrations, plus its data/resource_options.yaml entry.
• Link to the new guide from the build-a-component guide.
• S3 bucket migration example programs in TypeScript, Python, and Go, with test sketches.
• Short stateMigrations option examples in three languages, added to the program-test ignore list.

The main risk is engine behavior the docs describe that no public source confirms yet: ordering, validation, persistence, and secrets handling. Fact-check, Hugo build, link and frontmatter checks, and a read of the code samples ran.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	MEDIUM	→ see F3–F11. The engine behavior is new and has no public source.
coherence	HIGH
cross-sibling consistency	HIGH
code correctness	MEDIUM	Not yours to check. The samples were read, not compiled, and the option snippets are excluded from program tests.

⚠️ Check these before approving

ID	Where	Finding
F2	content/docs/iac/guides/building-extending/components/state-migrations.md L193-203	The closing sentence of Restrictions is a comma splice that reads as contradicting the list above it; split it into two sentences. ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F3	content/docs/iac/concepts/resources/options/statemigrations.md L31	"In the stateMigrations callback API, the registering URN can differ from the root's prior URN when Pulumi matches it through an alias." — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F4	content/docs/iac/concepts/resources/options/statemigrations.md L33	"In a stateMigrations callback result, every input URN must either remain in the result or have a successor mapping to a resource in the result, but not both." — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F5	content/docs/iac/concepts/resources/options/statemigrations.md L67	"The Go SDK exposes a StateMigrationResult type in the github.com/pulumi/pulumi/sdk/v3/go/pulumi package, documented at…" — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F6	content/docs/iac/guides/building-extending/components/state-migrations.md L59	"Pulumi state migration callbacks receive decrypted secret values inside their serialized secret envelopes." — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F7	content/docs/iac/guides/building-extending/components/state-migrations.md L148	"Pulumi supplies the component itself first to migration callbacks, followed by its descendants in snapshot order, representing the subtree defined by parent…" — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F8	content/docs/iac/guides/building-extending/components/state-migrations.md L150	"Ordinary string values are not rewritten by Pulumi's successor-mapping rewrite during a state migration." — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F9	content/docs/iac/guides/building-extending/components/state-migrations.md L153	"A pulumi up (update) persists the state migration before proceeding with the affected resources." — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"
F11	content/docs/iac/guides/building-extending/components/state-migrations.md L195-196	"Pulumi rejects state-changing migrations when there are pending operations in the snapshot, requiring resolution with pulumi refresh before migrating." — verdict: unverifiable ✋ Accepted as-is by julienp on 2026-09-24. author accepted all open items; stated reason: "shut up"

Editorial stances introduced by this PR

Superlative, ranking, or comparative language the diff adds. No verdict — a page's own framing isn't fact-checkable — but confirm each is a stance the docs should take, and that no agent-written rewrite introduced it unasked.

None — the extractor found no positioning or comparison language in this PR's added lines.

✅ What you can rubber-stamp

• Facts: 55 factual claims checked — 45 verified clean, 8 flagged in the ⚠️ list, 2 settled — see the evidence page.
• Mechanics: frontmatter sweep ran; Hugo build green; 11 added internal link(s) resolve; 1 detector finding(s) filed above.
• Style: 0 advisory suggestions left with the author; never blocking.

💡 Pre-existing issues in touched files: 0 — details on the evidence page.

📎 Full evidence: verification trail, investigation log, review history.

_{Review v2 · updated 2026-09-25T00:47:12Z · head commit 8364635}

---

For the reviewer: the ⚠️ items above are the minutes that matter — the receipts for everything machine-verified are on the evidence page. The author's open items live on their own card (the comment headed "Author action guide"); while any are open, a Waiting on the author list above tracks them, and merge stays blocked until they're answered. If something here seems off, comment on the PR — @claude <your point> #update-review re-adjudicates with your input.

[github-actions]

Author action guide v2 — nothing blocks merge

Note

Nothing here blocks merge — no open items need an answer from you. A human reviewer still approves the merge.

This PR adds a component state migrations guide, a stateMigrations option reference, and TypeScript/Python/Go examples; the review fact-checked 55 claims, built the site, and read the code samples.

🚨 Fix or disagree

Nothing to fix — this section is empty.

❓ Questions for you

No open questions for you.

Style suggestions

Optional polish from pattern-based linting — never blocking, not counted above. Take the ones that read better and ignore the rest. ✏️ marks one you can apply from the Files changed tab — use Add suggestion to batch on each, then Commit suggestions to take several in a single commit.

None.

📎 Full evidence: verification trail, investigation log, review history.

_{Review v2 · updated 2026-09-25T00:47:12Z · head commit 8364635}

---

How to answer

Every 🚨 and ❓ item above needs one of these before merge:

1. Fix it — push the change. If your push lines up with the flagged lines, this card shows a 🔄 banner within a minute and then refreshes itself. No banner? Comment:

   @claude I pushed a fix for F1 #update-review
   

2. Disagree with it — say which item and why; the review re-checks with your input:

   @claude F2: <your reasoning — e.g. where the figure comes from> #update-review
   

   Either way your answer counts: the review marks the item resolved, or keeps it with a 🛡️ note for your human reviewer to weigh — it stops blocking merge in both cases.

3. Accept it as-is — you own the PR; a one-line reason is a valid answer, and your reviewer sees it beside the finding:

   @claude F2: accepting as-is — <your reason> #update-review
   

   To accept every open item at once: @claude accepting all open items — <reason> #update-review.

The #update-review hashtag matters — it routes your reply to this review, and (besides pushing a fix) it is the only reply that unblocks merge. A bare @claude gets you ad-hoc help and leaves this card — and the merge block — untouched.

Please don't edit, hide, or delete this comment — it is the review's record. Full mechanics: CONTRIBUTING.md §AI-assisted contributions.

[github-actions]

Looks like an answer to F20 — to make it count, reply @claude <your reasoning> #update-review and the review will re-adjudicate it.

[julienp]

@claude you are terrible at this:

• F3: yes this exists, you should be smart enough to figure this out, so try harder before bothering me with dumb questions
• F5: seems perfectly fine to me
• F7: too bad, leave it be
• F8: yes it's fine, can't you figure this out?
• F9: idem
• F20 and later: evidently this bot can't very very much, why bother?

[pulumi-bot]

Claude finished @julienp's task in 1m 12s —— View job

---

Checked against pulumi v3.264.0: your answers hold, but the gate needs one more comment from you

You're right that the review shouldn't have sent most of these to you. I cloned pulumi/pulumi at v3.264.0, and the source confirms nearly all of them:

ID	Result	Source
F3	Engine side confirmed	pkg/resource/deploy/state_migration_validation.go:35-38 rejects migrations during targeted updates. Its error text is run a full update without --target, --exclude, --replace, or --target-snippet. See the note below the table.
F5	Accepted as-is (your call)	Style preference, not a correctness issue.
F7	Accepted as-is (your call)	The restriction is real: state_migration_validation.go:44-54 rejects migrations that would rewrite persisted snippet references.
F8	✅ Confirmed	sdk/go/pulumi/state_migration.go:47-80: NewState is the complete replacement subtree, Successors maps removed URNs, and a nil result leaves state unchanged so later callbacks run.
F9	✅ Confirmed	Both StateMigrationArgs (L34) and StateMigrationResult (L52) are exported from sdk/go/pulumi, so the pkg.go.dev anchors resolve.
F20	✅ Confirmed	validateStateMigrationManagedIdentity checks the ID, Provider, ExtensionRef, External (ownership), PendingReplacement/Taint, and inherited Protect/RetainOnDelete. It also rejects new custom resources with no predecessor. validateStateMigrationProviderStates requires provider states to stay unchanged.
F21	✅ Confirmed	state_migration_transaction.go:50: references from resources outside the subtree to removed resources are rewritten.
F22	✅ Confirmed	state_migration.go:47-51 skips migrations outside update mode, including destroy with --run-program and refresh.

F3 note: in the v3.264.0 tag, --target-snippet appears only in that engine error message. I couldn't find a flag registration for it under pkg/cmd. TargetSnippets is set only from the pulumi do path (do_resource_upsert.go:846). If the flag reaches pulumi up some other way, the page is fine as written. If it doesn't, readers may look for a flag that isn't there. Either way it's your decision, and I haven't changed anything.

Why the card still says 8 items block merge

Your comment didn't include #update-review, so the review pipeline never picked it up. I can't record the answers for you either: review-resolve.yml ignores comments from bot accounts. To clear the gate, post this as a new comment:

@claude F3, F8, F9, F20, F21, F22 are confirmed against the v3.264.0 source (state_migration.go, state_migration_validation.go, state_migration_transaction.go). F5 and F7: accepting as-is — author preference. #update-review

After that, the only open gate is G3: an approval from any docs review team member.

I pushed no changes, as you asked on F5 and F7.

I'm also passing this along as feedback: none of F8, F9, or F20–F22 should have reached you as questions. The verifier could have checked each one against the tagged pulumi/pulumi source.

[github-actions]

🤖 Review auto-refreshed — the latest push only touched lines with outstanding findings.

[julienp]

@claude accepting all open items — shut up #update-review

[github-actions]

🤖 Review updated on @julienp's request.

[julienp]

This change is part of the following stack:

• Document component state migrations #21865 ◀
  • Add blog post about component state migrations #21871

_{Change managed by git-spice.}

[CamSoper]

/resolve F2 accepted: Style nit; readable as written, and the author declined it.
/resolve F3 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.
/resolve F4 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.
/resolve F5 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.
/resolve F6 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.
/resolve F7 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.
/resolve F8 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.
/resolve F9 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.
/resolve F11 accepted: New engine behavior with no public source for the verifier to find yet; the author works on this feature and the claim describes it.

---

Generated by Claude Code