Auto-generate custom role permissions reference from IAM metadata

.github/workflows/sync-custom-role-permissions.yml

@@ -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

@@ -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
-
-| 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                                                 |
-
-## 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 |
+{{% 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 }}
+
+## {{ $group.name }}
+
+| 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

@@ -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