mirror of
https://github.com/docker/docs.git
synced 2026-11-04 10:01:00 +00:00
Greg MondelloandClaude Opus 4.8
ae41294ec4
## 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](https://github.com/docker/iam-services/pull/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)
1. `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.)
2. A workflow file added via a fork PR won't auto-run, so a maintainer
needs to land/enable it.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>