Administration IA phase 1: re-shelve the SaaS side into get-started / concepts / guides / reference - #21056
Administration IA phase 1: re-shelve the SaaS side into get-started / concepts / guides / reference#21056jkodroff wants to merge 4 commits into
Conversation
Move the 46 SaaS-side Administration pages onto the standard docs shelves —
get-started / concepts / guides / reference — so the section is organized by
document type rather than topic, matching iac/, esc/, deployments/, and idp/.
Pure git mv + alias. No prose edits: every moved page keeps its full existing
alias chain and gains its old URL on top.
- get-started/ <- onboarding-guide/ (5 pages), retitled "Get Started"
- concepts/ <- the org and access model (12 pages) + new landing page
- guides/ <- SAML, SCIM, OIDC, audit-log export, CMK, least privilege,
billing managers (25 pages) + new landing pages
- reference/ <- the four RBAC scope tables + new landing pages
The three retired container landing pages and the two redirect stubs are
deleted with their aliases folded onto the real pages, so all three
directories vacate cleanly. Leaving a stub behind would have kept its
directory alive, and Hugo skips an alias whose target path already has a
page — silently dropping the container redirect.
Also updates every inbound link outside content/blog/ (which aliases cover),
including data/glossary.toml, data/pulumi_pricing.yaml, layouts/index.llms.txt,
the S3 redirect targets, and the relref in layouts/shortcodes/identities.html
that would otherwise fail the build.
Part of #21051. Fixes #21052.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012VLSi7rdf7rrDaHm9rNd8c
Billing Manager is a role in the access model, not a procedure — the page defines what the role is and what it can see, so it belongs beside organizations, accounts, and agent accounts rather than under guides/. That empties the guides/ "Organization management" group. Also adds a pointer from the reference landing page to the Pulumi Cloud REST API, which is where the programmatic half of administration lives. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012VLSi7rdf7rrDaHm9rNd8c
github-actions
Bot
added
review:triaging
![unblocked[bot]](https://avatars.githubusercontent.com/in/166219?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found.
About Unblocked
Unblocked has been set up to automatically review your team's pull requests to identify genuine bugs and issues.
📖 Documentation — Learn more in our docs.
💬 Ask questions — Mention @unblocked to request a review or summary, or ask follow-up questions.
👍 Give feedback — React to comments with 👍 or 👎 to help us improve.
⚙️ Customize — Adjust settings in your preferences.
| - [Stacks](stacks) | ||
| - [Environments](environments) | ||
| - [Cloud accounts](insights-accounts) | ||
| - [Organization settings](org-settings) |
There was a problem hiding this comment.
These relative links resolve from the rendered URL /docs/administration/concepts/rbac/scopes/ to paths like /docs/administration/concepts/rbac/scopes/stacks, but the scope detail pages were moved to /docs/administration/reference/rbac-scopes/. This will result in 404 errors for users.
The reference/rbac-scopes/_index.md landing page uses the correct absolute paths — these should match:
| - [Stacks](stacks) | |
| - [Environments](environments) | |
| - [Cloud accounts](insights-accounts) | |
| - [Organization settings](org-settings) | |
| - [Stacks](/docs/administration/reference/rbac-scopes/stacks/) | |
| - [Environments](/docs/administration/reference/rbac-scopes/environments/) | |
| - [Cloud accounts](/docs/administration/reference/rbac-scopes/insights-accounts/) | |
| - [Organization settings](/docs/administration/reference/rbac-scopes/org-settings/) |
Lighthouse Performance ReportCommit: 9ab16ba | Metric definitions
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Optional style suggestions from the pre-merge review — apply or dismiss; none of them block.
Generated by Claude Code
Pre-merge Review — Last updated 2026-08-21T21:57:12ZTip Summary: This is a pure information-architecture change: the Pulumi Cloud administration docs are re-shelved from Review confidence:
Investigation log
🔍 Verification trail490 claims extracted · 358 verified · 14 unverifiable · 51 contradicted · 4 framing-drift · 10 detector findings
Important Please don't hide, resolve, or delete this comment! It breaks things! 📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches. |
continued from previous comment
Important Please don't hide, resolve, or delete this comment! It breaks things! 📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches. |
continued from previous comment
Important Please don't hide, resolve, or delete this comment! It breaks things! 📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches. |
continued from previous comment
Important Please don't hide, resolve, or delete this comment! It breaks things! 📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches. |
continued from previous comment
🚨 Outstanding in this PRThese must be resolved or refuted before merging. No outstanding findings in this PR.
|
💡 Pre-existing issues in touched files (optional)
✅ Resolved since last reviewFixed in
Accepted as-is by @jkodroff — inherited text this PR only link-rewrote:
📜 Review history
Important Please don't hide, resolve, or delete this comment! It breaks things! 📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches. |
github-actions
Bot
added
review:outstanding-issues
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
github-actions
Bot
added
review:stale
Mandatory:
- concepts/rbac/scopes.md used bare relative links ([Stacks](stacks)) for the
four scope tables. Those resolved from the page's old URL but not its new
one, and the tables moved to reference/rbac-scopes/ regardless. Now full
canonical paths, per AGENTS.md.
- concepts/rbac/scopes.md linked roles#default-roles; that heading is
"Pulumi-defined roles". Pre-existing on master, surfaced by the move.
Fixed the anchor and the stale link text together.
Found while auditing the same class of problem:
- concepts/rbac/roles.md linked access-tokens#organization-access-tokens, but
that heading carries an explicit {#creating-an-organization-access-token}
override. Also pre-existing.
Low-confidence findings that were safe to take:
- Restored "and least privilege" to the guides meta_desc, dropped by mistake
when billing managers moved to concepts.
- Scoped the concepts CMK bullet to "currently for Pulumi ESC with AWS KMS",
matching what the target page actually says.
- concepts/rbac/scopes.md H2s to sentence case, per AGENTS.md. Nothing links
to the old anchors.
All 128 links and anchors into /docs/administration/ verified against the
built site.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012VLSi7rdf7rrDaHm9rNd8c
|
@claude #update-review Both outstanding findings are fixed at Mandatory
Found by auditing the same class
I then validated every internal link and anchor into Low-confidence, taken
Low-confidence, not taken — accepted as-is by the author The remaining items are all inherited text this PR only link-rewrote: the console UI claims in One deliberate omission: |
github-actions
Bot
added
review:in-progress
|
🤖 Review updated on @jkodroff's request. |
github-actions
Bot
added
review:no-blockers
2 participants
Phase 1 of the Administration IA restructure (#21051). Moves the 46 SaaS-side pages onto the four standard shelves so the section is organized by document type rather than topic, matching
iac/,esc/,deployments/, andidp/.Pure
git mv+ alias. Zero prose edits — every moved page keeps its full existing alias chain and gains its old URL on top. The only body changes are link retargets.Fixes #21052.
Structure
Decisions worth a look
Billing managers landed in
concepts/, notguides/. The issue mapped it to guides; the page defines what the Billing Manager role is, so it sits beside organizations, accounts, and agent accounts.The two redirect stubs are deleted, not retargeted. The issue called for keeping
organizations-teams/teams.mdandaccess-identity/stack-permissions.mdin place with a newredirect_to. That would have kept their directories alive, and Hugo renders a section list page at/docs/administration/organizations-teams/— the exact URL we need to alias ontoconcepts/. Hugo skips an alias whose target path already has a page, so the container redirect would have been silently dropped. Folding each stub's aliases onto its real page vacates all three directories cleanly and gives readers one hop instead of two./docs/administration/access-identity/stack-permissions/now lands at the top of the permission-sets page rather than#stack-permission-sets. A Hugo alias can't carry a fragment. Easy to revert to aredirect_tostub if we'd rather keep the anchor.Get-started naming settled. The page's title and menu label disagreed ("Setting Up Pulumi for Your Organization" vs. "Onboarding Guide"). Now
title: Get Started/h1: Get started with Pulumi Cloud. The broader question of whether the section should be named "Administration" is deliberately out of scope —/docs/pulumi-cloud/is currently an alias onadministration/_index.md, so a section rename needs untangling first.Three ESC pages lost their secondary
administration:menu entry.esc/concepts/approvals.md,esc/concepts/customer-managed-keys.md, andesc/administration/audit-logs.mdwere parented toadministration-security-compliance, which this PR deletes. They stay in theescmenu.layouts/shortcodes/identities.htmlhad to move. It carried arelrefto/docs/administration/access-identity/saml/, andrefLinksErrorLevel: ERRORmakes that a hard build failure rather than a 404.Also updated
/docs/administration/section cards,data/glossary.toml,data/pulumi_pricing.yaml,layouts/index.llms.txt, the 7 S3 redirect targets inscripts/redirects/, and ~115 files of inbound links acrosscontent/docs,content/tutorials,content/what-is, andcontent/releases.content/blog/is deliberately untouched — aliases cover it, per AGENTS.md.Added a pointer from the new
reference/landing page to the Pulumi Cloud REST API.Verification
make lint— 0 errorsmake build— cleanscripts/alias-verification/verify-aliases.py— 45/45 renames correct, 0 missing, 0 suspicious. The 6 deleted URLs were confirmed aliased by hand (the extractor writes deletes to a separate file the verifier doesn't read).public/, including deep legacy chains (/docs/intro/pulumi-cloud/scopes/stacks/,/docs/pulumi-cloud/access-management/saml/okta/).Not fixed here
content/docs/deployments/guides/oidc/*.mdreference/docs/administration/access-identity/oidc/provider/*. These turned out not to be rot — they're live aliases owned by those very pages, so nothing was broken and nothing needed changing.🤖 Generated with Claude Code
https://claude.ai/code/session_012VLSi7rdf7rrDaHm9rNd8c