nprasad2077/docker-docs
1
0 Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-04 10:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
## 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>
This commit is contained in:
Greg MondelloandClaude Opus 4.8 authored and GitHub committed 2026-10-29 12:50:31 +01:00
1 parent b55fd4373b
commit ae41294ec4
3 files changed
+244 -69
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/workflows/sync-custom-role-permissions.yml
+71
View File
@@ -0,0 +1,71 @@
name: Sync custom role permissions
# Vendors the IAM source of truth (custom-role-metadata.yaml in
# docker/iam-services) into data/custom_role_permissions.yaml and opens a PR for
# review. The permissions reference page renders that file with an inline
# shortcode, so the site build never needs access to the private upstream
# repository.
# Triggered by the "Sync docs permissions" workflow in docker/iam-services when
# that file changes on main; can also be run manually.
on:
workflow_dispatch:
inputs:
ref:
description: "The git ref in docker/iam-services to read custom-role-metadata.yaml from."
type: string
required: false
default: "main"
concurrency:
group: sync-custom-role-permissions
cancel-in-progress: true
jobs:
sync:
name: Sync custom role permissions data
runs-on: ubuntu-latest
steps:
- id: setup
uses: docker/actions/setup@707e5d98a430d92e8e6c2d34faa5bfb2a9149e9b
with:
app_id: ${{ secrets.HUB_PLATFORM_APP_ID }}
app_private_key: ${{ secrets.HUB_PLATFORM_APP_PRIVATE_KEY }}
- name: Checkout docs
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
with:
token: ${{ steps.setup.outputs.token }}
show-progress: false
- name: Vendor custom-role-metadata.yaml from iam-services
env:
GH_TOKEN: ${{ steps.setup.outputs.token }}
REF: ${{ inputs.ref }}
run: |
gh api \
"repos/docker/iam-services/contents/internal/services/access_control/config/custom-role-metadata.yaml?ref=${REF}" \
-H "Accept: application/vnd.github.raw+json" \
> data/custom_role_permissions.yaml
- name: Create PR
uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0
with:
token: ${{ steps.setup.outputs.token }}
title: "⚙️ Sync custom role permissions data"
body: |
Automatically generated from
[`custom-role-metadata.yaml`](https://github.com/docker/iam-services/blob/main/internal/services/access_control/config/custom-role-metadata.yaml)
in `docker/iam-services` by the **Sync custom role permissions**
workflow, triggered by a change to that file.
Only `data/custom_role_permissions.yaml` is updated. The
permissions reference page renders it with an inline shortcode. If
this change is unexpected or shouldn't ship yet, close this PR —
the workflow will re-open it the next time the source changes.
commit-message: "Sync custom role permissions data"
sign-commits: true
add-paths: |
data/custom_role_permissions.yaml
branch: chore/sync-custom-role-permissions
delete-branch: true
content/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md
+22 -69
View File
@@ -21,77 +21,30 @@ billing, licensing, AI Governance, Docker Hardened Images, Docker
Offload, and Docker Cloud Sandboxes. Use the following tables to [create
or edit a custom role](manage.md).
## Organization management
{{% custom_role_permissions.inline %}}
{{- $data := hugo.Data.custom_role_permissions -}}
{{- if not $data.groups -}}
{{- errorf "custom-role-permissions: no groups found in data/custom_role_permissions.yaml: %s" .Position -}}
{{- end -}}
{{- range $group := $data.groups -}}
{{- if not $group.name -}}
{{- errorf "custom-role-permissions: group without a name: %s" $.Position -}}
{{- end -}}
{{- if $group.relations }}
| Permission | Description |
| :-------------------------------- | :---------------------------------------------------------------------------------------------- |
| View teams | View teams and team members |
| Manage teams | Create, update, and delete teams and team members |
| Manage registry access | Control which registries members can access |
| Manage image access | Set policies for which images members can pull and use |
| Update organization information | Update organization information such as name and location |
| Member management | Manage organization members, invites, and roles |
| View custom roles | View existing custom roles and their permissions |
| Manage custom roles | Full access to custom role management and assignment |
| Manage organization access tokens | Create, update, and delete repositories in this org. Push/pull or registry actions not included |
| View activity logs | Access organization audit logs and activity history |
| View usage reports | Download organization usage reports (pulls, storage) |
| View domains | View domains and domain audit settings |
| Manage domains | Manage verified domains and domain audit settings |
| View SSO and SCIM | View single sign-on and user provisioning configurations |
| Manage SSO and SCIM | Full access to SSO and SCIM management |
| Manage Desktop settings | Configure Docker Desktop settings policies and view usage reports |
| View OIDC connections | View OIDC connections and their configuration |
| Manage OIDC connections | View, create, edit, and delete OIDC connections |
## {{ $group.name }}
## Docker Hub
| Permission | Description |
| :--------------------------------- | :------------------------------------------------------------------------------------------- |
| View repositories | View repository details and contents |
| Manage repositories | Full repository management including settings, webhooks, privacy, Dockerfile, immutable tags |
| Manage repository team permissions | Add and remove teams from a repository, and manage team access level |
## Billing
| Permission | Description |
| :------------- | :----------------------------------------------- |
| View billing | View organization billing information |
| Manage billing | Complete access to managing organization billing |
## Licensing
| Permission | Description |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| Manage licenses | Assign and revoke licenses for members and manage auto-assign rules. Does not include purchasing or changing the number of licenses |
## AI Governance
| Permission | Description |
| :-------------------- | :--------------------------------------------------- |
| View policies | View existing AI Governance policies and their rules |
| Manage policies | Full access to AI Governance policy management |
| View audit logs | View audit events for the organization |
| Manage audit settings | Update audit configuration for the organization |
## DHI (Docker Hardened Images)
| Permission | Description |
| :-------------------- | :-------------------------------------------------------------- |
| Create DHI mirrors | Create Docker Hardened Image mirror repositories |
| Manage customizations | Create, update, and delete Docker Hardened Image customizations |
## Docker Offload
| Permission | Description |
| :---------------- | :--------------------------------------------- |
| Offload Read-Only | View Offload account status, leases, and zones |
## Cloud Sandboxes
| Permission | Description |
| :------------------ | :------------------------------------ |
| Use Cloud Sandboxes | Create and use Docker Cloud Sandboxes |
| Permission | Description |
| :--------- | :---------- |
{{ range $group.relations -}}
{{- if or (not .name) (not .description) -}}
{{- errorf "custom-role-permissions: relation %q in group %q needs a name and description: %s" .name $group.name $.Position -}}
{{- end -}}
| {{ replace .name "|" "\\|" }} | {{ replace .description "|" "\\|" }} |
{{ end -}}
{{- end -}}
{{- end }}
{{% /custom_role_permissions.inline %}}
## Next steps
data/custom_role_permissions.yaml
+151
View File
@@ -0,0 +1,151 @@
# File contains metadata that is used to drive the roles UI screen.
# Custom role permissions are grouped together by domain model (note these grouping have no logical impact on access control service).
#
# Only permissions defined below will show up in the UI.
groups:
- name: Organization management
relations:
- name: View teams
description: View teams and team members
relation: permset-group-read
- name: Manage teams
description: Create, update, and delete teams and team members
relation: permset-group-write
- name: Manage registry access
description: Control which registries members can access
relation: permset-registry-access-management-write
- name: Manage image access
description: Set policies for which images members can pull and use
relation: permset-image-access-management-write
- name: Update organization information
description: Update organization information such as name and location
relation: permset-organization-info-write
- name: Member management
description: Manage organization members, invites, and roles
relation: permset-member-write
- name: View custom roles
description: View existing custom roles and their permissions
relation: permset-custom-role-read
- name: Manage custom roles
description: Full access to custom role management and assignment
relation: permset-custom-role-write
- name: Manage organization access tokens
description: Create, update, and delete organization access tokens
relation: permset-access-token-write
- name: View activity logs
description: Access organization audit logs and activity history
relation: permset-activity-log-read
- name: View usage reports
description: Download organization usage reports (pulls, storage)
relation: permset-report-read
- name: View domains
description: View domains and domain audit settings
relation: permset-domain-read
- name: Manage domains
description: Manage verified domains and domain audit settings
relation: permset-domain-write
- name: View SSO and SCIM
description: View single sign-on and user provisioning configurations
relation: permset-sso-read
- name: Manage SSO and SCIM
description: Full access to SSO and SCIM management
relation: permset-sso-write
- name: Manage Desktop settings
description: Configure Docker Desktop settings policies and view usage reports
relation: permset-desktop-settings-write
- name: View OIDC connections
description: View OIDC connections and their configuration
relation: permset-oidc-read
- name: Manage OIDC connections
description: View, create, edit, and delete OIDC connections
relation: permset-oidc-write
- name: Docker Hub
relations:
- name: View repositories
description: View repository details and contents
relation: permset-repo-read
- name: Manage repositories
description: Full repository management including settings, webhooks, privacy, Dockerfile, immutable tags.
relation: permset-repo-write
- name: Manage repository team permissions
description: Add and remove teams from a repository, and manage team access level
relation: permset-repo-group-write
# - name: Pull Image
# description: Pull Docker images from repositories
# relation: permset-repo-image-pull
# - name: Push Image
# description: Push Docker images from repositories
# relation: permset-repo-image-push
# - name: Manage stars
# description: Star and unstar repositories
# relation: permset-repo-star-write
# - name: View tags
# description: View image tags in repositories
# relation: permset-repo-tag-read
# - name: Manage tags
# description: Delete image tags in repositories
# relation: permset-repo-tag-write
# - name: View images
# description: View image list and reclaimable size
# relation: permset-repo-image-read
# - name: Manage images
# description: Create, update and delete images
# relation: permset-repo-image-write
# - name: View teams
# description: View repository team details
# relation: permset-repo-team-read
# - name: Manage teams
# description: Create, update, and delete repository teams
# relation: permset-repo-team-write
- name: Billing
relations:
- name: View billing
description: View organization billing information
relation: permset-billing-read
- name: Manage billing
description: Complete access to managing organization billing
relation: permset-billing-manage
- name: Licensing
relations:
- name: Manage licenses
description: Assign and revoke licenses for members and manage auto-assign rules. Does not include purchasing or changing the number of licenses.
relation: permset-license-manage
- name: AI Governance
relations:
- name: View policies
description: View existing AI Governance policies and their rules
relation: permset-governance-policy-read
- name: Manage policies
description: Full access to AI Governance policy management
relation: permset-governance-policy-write
- name: View audit logs
description: View audit events for the organization
relation: permset-audit_events-read
- name: Manage audit settings
description: Update audit configuration for the organization
relation: permset-audit_settings-write
- name: DHI (Docker Hardened Images)
relations:
- name: Create DHI mirrors
description: Create Docker Hardened Image mirror repositories
relation: permset-dhi-mirror-write
- name: Manage customizations
description: Create, update, and delete Docker Hardened Image customizations
relation: permset-dhi-customization-write
- name: Docker Offload
relations:
- name: Offload Read-Only
description: View Offload account status, leases, and zones
relation: permset-offload-read
- name: Cloud Sandboxes
relations:
- name: Use Cloud Sandboxes
description: Create and use Docker Cloud Sandboxes
relation: permset-sandbox-use