Auto-generate custom role permissions reference from IAM metadata by gmondello · Pull Request #26336 · docker/docs

gmondello · 2026-10-12T17:13:37Z

Summary

Replaces the manual edits we make to this page whenever a custom-role permission is added or renamed with a synced data file + Hugo shortcode. The source of truth is custom-role-metadata.yaml in docker/iam-services.

What's in this PR

data/custom_role_permissions.yaml: the upstream YAML, vendored verbatim from iam-services main.
layouts/_shortcodes/custom-role-permissions.html and .markdown.md: render one section per group, with a Permission/Description table, for both HTML and Markdown output. Cells escape |. The build fails with the group and permission name if a group, name or description is missing. The page calls it as {{% custom-role-permissions %}} so the headings stay in the page table of contents.
permissions-reference.md: the generated region is replaced by the shortcode call. Intro and "Next steps" stay hand-maintained.
.github/workflows/sync-custom-role-permissions.yml: workflow_dispatch (with a ref input) that fetches the YAML at that ref, writes it to data/, and opens a PR via peter-evans/create-pull-request. Site builds never need access to the private upstream repo.
.prettierignore: excludes the shortcode, because it emits Markdown and Prettier's go-template plugin reflows the table.

The Node generator, hand-rolled YAML parser and generation markers are removed.

How the automation fires

A companion workflow in docker/iam-services (PR #1175) triggers this one whenever custom-role-metadata.yaml changes on main. The result is always a PR for review, so nothing publishes automatically.

Opt out of any given change: close the generated PR; it re-opens on the next source change.

Testing

Built the full site with Hugo 0.163.0. HTML and Markdown output both contain the same 32 permissions in 8 tables, the section anchors and table of contents are intact, and removing a description fails the build with a clear error. Prettier passes on the YAML and the workflow. The workflow itself has not run.

⚠️ Provisioning needed before this runs (docs maintainers)

HUB_PLATFORM_APP_ID / HUB_PLATFORM_APP_PRIVATE_KEY secrets present in this repo, with the GitHub App installed here (PR-write) and granted contents-read on docker/iam-services. (Same app already used by iam-services ↔ frontends sync.)
A workflow file added via a fork PR won't auto-run, so a maintainer needs to land/enable it.

🤖 Generated with Claude Code

Adds a generator + workflow that rebuild the custom-role permissions reference from custom-role-metadata.yaml in docker/iam-services (the source of truth), replacing the manual updates done by hand. - scripts/generate-custom-role-permissions.mjs rewrites the tables between generation markers; frontmatter, intro, and "Next steps" are hand-maintained. - .github/workflows/sync-custom-role-permissions.yml regenerates the page and opens a PR when triggered by docker/iam-services. The regenerated page adds the Licensing and Cloud Sandboxes sections and the DHI "Manage customizations" row (from iam-services#1172 and docker#1173), superseding the manual docker#26324. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

netlify · 2026-10-12T17:13:43Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`47d44c2`
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6adbbbd704d83bdc9375279b
😎 Deploy Preview	https://deploy-preview-26336--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

dvdksn · 2026-10-21T13:59:24Z

Could this follow the existing Hugo data/template approach? The CLI reference already renders structured data through hugo.Data, and other shortcodes use transform.Unmarshal.

The sync workflow could vendor the upstream YAML into data/, with a shortcode or layout rendering the permission tables in both HTML and Markdown output. That would keep the surrounding prose hand-maintained without needing a custom YAML parser, table formatter, or generation markers.

For example, the Markdown rendering could look roughly like this, with the YAML stored at data/custom_role_permissions.yaml:

{{/* Pseudocode: validate the expected structure and escape table cells. */}}
{{ range hugo.Data.custom_role_permissions.groups }}
## {{ .name }}

| Permission | Description |
| :--------- | :---------- |
{{ range .relations }}
| {{ .name }} | {{ .description }} |
{{ end }}
{{ end }}

The page could invoke the shortcode between its introduction and next steps, with a corresponding HTML renderer. The workflow would only fetch the YAML and open a PR containing the data update, so builds wouldn't need access to the private upstream repository.

Separately, the upstream metadata needs a description correction: “Manage organization access tokens” describes creating, updating, and deleting repositories, while model.fga connects permset-access-token-write to organization access-token read/write/delete operations. That error already exists in the docs; it should be corrected at the source before syncing the descriptions automatically.

Generated by Codex

gmondello · 2026-10-23T18:54:36Z

Separately, the upstream metadata needs a description correction: “Manage organization access tokens” describes creating, updating, and deleting repositories, while model.fga connects permset-access-token-write to organization access-token read/write/delete operations. That error already exists in the docs; it should be corrected at the source before syncing the descriptions automatically.

This was fixed in https://github.com/docker/iam-services/pull/1181

Replace the Node generator and generation markers with a data file and a custom-role-permissions shortcode, following the existing hugo.Data approach. The sync workflow now only vendors custom-role-metadata.yaml into data/custom_role_permissions.yaml. The shortcode renders the tables for both HTML and Markdown output and fails the build on missing names or descriptions. Exclude the Markdown-emitting shortcode from Prettier. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Take main's version of the page so the upcoming merge of main is conflict-free. The next commit swaps the tables for the shortcode. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…rtcode Replace the hand-maintained tables from main with the shortcode call. Keeps main's updated front matter and intro. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

gmondello · 2026-10-23T20:01:08Z

Could this follow the existing Hugo data/template approach?

Thanks for the review, @dvdksn. I've followed your steer. Mind taking another look? In particular I am not sure about the .prettierignore piece 🤷

Cc: @akristen

github-actions Bot added area/security area/release Relates to CI or deployment ci ci updates labels Oct 12, 2026

gmondello marked this pull request as ready for review October 14, 2026 14:37

gmondello requested review from aevesdocker and akristen as code owners October 14, 2026 14:37

akristen requested review from dvdksn and removed request for aevesdocker October 15, 2026 20:58

github-actions Bot added the hugo Updates related to hugo label Oct 23, 2026

gmondello and others added 3 commits October 23, 2026 14:55

Match permissions reference to main before merging

dec18ff

Take main's version of the page so the upcoming merge of main is conflict-free. The next commit swaps the tables for the shortcode. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Merge branch 'main' into gmondello/sync-custom-role-permissions

6b2a601

Render the permissions reference with the custom-role-permissions sho…

47d44c2

…rtcode Replace the hand-maintained tables from main with the shortcode call. Keeps main's updated front matter and intro. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Navigation Menu

Repository navigation

Auto-generate custom role permissions reference from IAM metadata - #26336

Auto-generate custom role permissions reference from IAM metadata#26336
gmondello wants to merge 5 commits into
docker:mainfrom
gmondello:gmondello/sync-custom-role-permissions

gmondello commented Oct 12, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

dvdksn commented Oct 21, 2026

Uh oh!

gmondello commented Oct 23, 2026

Uh oh!

gmondello commented Oct 23, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

gmondello commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's in this PR

How the automation fires

Testing

⚠️ Provisioning needed before this runs (docs maintainers)

Uh oh!

netlify Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsdocker ready!

Uh oh!

dvdksn commented Oct 21, 2026

Uh oh!

gmondello commented Oct 23, 2026

Uh oh!

gmondello commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gmondello commented Oct 12, 2026 •

edited

Loading

netlify Bot commented Oct 12, 2026 •

edited

Loading

gmondello commented Oct 23, 2026 •

edited

Loading