@htekdev/actions-debugger 1.0.14 → 1.0.16

package/errors/permissions-auth/github-app-installation-token-new-format.yml

@@ -0,0 +1,124 @@
+id: permissions-auth-014
+title: "GitHub App Installation Tokens New Stateless Format Breaks Length/Regex Validation"
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - installation-token
+  - token-format
+  - stateless-token
+  - breaking-change
+  - auth
+patterns:
+  - regex: "invalid.*token.*format|token.*validation.*failed"
+    flags: "i"
+  - regex: "token.*length.*expected|token.*too long"
+    flags: "i"
+  - regex: "Bad credentials|401.*installation.token"
+    flags: "i"
+  - regex: "installation.*token.*truncated|column.*too long.*token"
+    flags: "i"
+error_messages:
+  - "Bad credentials — installation token rejected by downstream validation"
+  - "column 'token' is too long for type character varying(40)"
+  - "token validation failed: expected length 40, got 520"
+  - "ERROR: value too long for type character(40)"
+root_cause: |
+  Starting April 27, 2026, GitHub rolled out a **new stateless format** for GitHub App
+  installation tokens. The new tokens are approximately **520 characters** long and use
+  a new prefix, compared to the previous format which was a fixed **40-character**
+  opaque token.
+
+  **What changed:**
+  - Old format: 40-character token (e.g., `ghs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
+  - New format: ~520-character JWT-like stateless token with a new prefix scheme
+
+  **What breaks:**
+  1. **Database columns sized at `CHAR(40)` or `VARCHAR(40)`** — any app that stores
+     the token in a database field sized for the old format will fail with a column
+     truncation or "value too long" database error.
+  2. **Regex/length validation** — code that validates token format or length (e.g.,
+     `len(token) == 40`, or regex `^ghs_[a-f0-9]{36}$`) will reject the new tokens.
+  3. **HTTP header size limits** — some reverse proxies or WAFs with conservative
+     request header size limits may reject requests with the longer Authorization header.
+  4. **Logging or masking systems** — tools that detect or mask secrets by pattern may
+     not recognize the new format, causing tokens to appear in logs unmasked.
+
+  Source: GitHub Changelog 2026-04-24 — "Notice about upcoming new format for GitHub
+  App installation tokens"
+fix: |
+  **Treat installation tokens as opaque strings of variable length.** Do not assume
+  a specific length, prefix pattern, or character set.
+
+  1. **Database**: Expand token storage columns to `VARCHAR(1024)` or use TEXT type
+     to future-proof against further format changes.
+  2. **Validation**: Remove length checks and pattern-based validation on token values.
+     Validate by making an authenticated API call (e.g., `GET /app/installations`) —
+     if it returns 200, the token is valid.
+  3. **HTTP proxy/WAF**: Increase `LargeClientHeader` or equivalent header size limits
+     if your infrastructure sits in front of the GitHub API requests.
+  4. **Secret masking**: Update any custom masking patterns to match the new prefix
+     or use `add-mask` in workflows rather than pattern-based masking.
+fix_code:
+  - language: yaml
+    label: "Do not validate token length — use API to verify instead"
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+          steps:
+            - name: Generate GitHub App installation token
+              id: app-token
+              uses: actions/create-github-app-token@v2
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+            # ❌ Never validate token by length — new format is ~520 chars
+            # - run: |
+            #     TOKEN="${{ steps.app-token.outputs.token }}"
+            #     [ ${#TOKEN} -eq 40 ] || exit 1  # WILL FAIL with new format
+
+            # ✅ Verify by making an authenticated API call
+            - name: Verify token works
+              env:
+                GH_TOKEN: ${{ steps.app-token.outputs.token }}
+              run: gh api /app --jq '.name'
+  - language: yaml
+    label: "Mask the full new-format token in logs with add-mask"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate token
+              id: app-token
+              uses: actions/create-github-app-token@v2
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+            # Explicitly mask the token value so it does not appear in logs
+            # (pattern-based masking may not catch the new ~520-char format)
+            - name: Mask token
+              run: echo "::add-mask::${{ steps.app-token.outputs.token }}"
+
+            - name: Use token
+              env:
+                GH_TOKEN: ${{ steps.app-token.outputs.token }}
+              run: gh api /repos/${{ github.repository }}/releases
+prevention:
+  - "Store GitHub App installation tokens in TEXT or VARCHAR(1024)+ columns — never size to the old 40-character format."
+  - "Remove any code that validates token length or matches against a fixed token-format regex."
+  - "Use `echo '::add-mask::TOKEN'` explicitly in workflows rather than relying on pattern-based log masking for App tokens."
+  - "Subscribe to GitHub Changelog token-format notices — https://github.blog/changelog/ — and test format changes in staging before they reach production."
+  - "Use `actions/create-github-app-token` (the official action) to generate tokens rather than rolling your own JWT exchange, so the action absorbs format changes automatically."
+docs:
+  - url: "https://github.blog/changelog/2026-04-24-notice-about-upcoming-new-format-for-github-app-installation-tokens"
+    label: "GitHub Changelog: Notice about upcoming new format for GitHub App installation tokens"
+  - url: "https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation"
+    label: "GitHub Docs: Authenticating as a GitHub App installation"
+  - url: "https://github.com/actions/create-github-app-token"
+    label: "actions/create-github-app-token — official token generation action"

package/errors/permissions-auth/github-packages-read-requires-packages-permission.yml

@@ -0,0 +1,128 @@
+id: permissions-auth-011
+title: "GITHUB_TOKEN Cannot Pull Private GitHub Packages Without packages: read Permission"
+category: permissions-auth
+severity: error
+tags:
+  - github-packages
+  - ghcr
+  - container-registry
+  - packages-read
+  - github-token
+  - 401
+  - npm-packages
+  - docker
+patterns:
+  - regex: "401 Unauthorized.*(?:ghcr\\.io|npm\\.pkg\\.github\\.com|maven\\.pkg\\.github\\.com)"
+    flags: "i"
+  - regex: "(?:ghcr\\.io|npm\\.pkg\\.github\\.com).*401 Unauthorized"
+    flags: "i"
+  - regex: "Error response from daemon.*(?:unauthorized|denied).*ghcr\\.io"
+    flags: "i"
+  - regex: "npm ERR!\\s+401\\s+Unauthorized.*npm\\.pkg\\.github\\.com"
+    flags: "i"
+  - regex: "unauthorized: authentication required"
+    flags: "i"
+error_messages:
+  - "Error response from daemon: pull access denied for ghcr.io/org/image, repository does not exist or may require 'docker login': denied: denied"
+  - "npm ERR! 401 Unauthorized - GET https://npm.pkg.github.com/@org%2fpkg/-/pkg-1.0.0.tgz"
+  - "unauthorized: authentication required"
+  - "Error: The process '/usr/bin/docker' failed with exit code 1"
+root_cause: |
+  When a GitHub Actions workflow pulls from the GitHub Container Registry (ghcr.io) or from
+  GitHub Packages registries (npm.pkg.github.com, maven.pkg.github.com), the GITHUB_TOKEN
+  must have the `packages: read` permission explicitly granted.
+
+  The GITHUB_TOKEN's default permissions do NOT include `packages: read` unless:
+  1. The repository's default token permissions (Settings → Actions → General) are set to
+     "Read and write" at the org or repository level.
+  2. The workflow or job explicitly declares `permissions: packages: read`.
+
+  Commonly confused behaviors:
+  - A public package on ghcr.io from the same org is readable without auth — but a private
+    package or a package from a private repository requires authentication.
+  - GITHUB_TOKEN is scoped to the CURRENT repository. Pulling packages published from a
+    DIFFERENT repository in the same org may require a PAT even with packages: read set,
+    because the token only has read access to packages owned by the current repo.
+  - When `permissions:` is set at the workflow level (even just `contents: read`), all
+    unmentioned permissions are downgraded to 'none' — this silently removes packages: read
+    if it was previously implied by repository defaults.
+
+  This error is particularly common when:
+  - A workflow was working until someone added a top-level permissions: block for another
+    purpose (e.g., to set id-token: write for OIDC), silently removing packages: read
+  - The organization was migrated from packages-on-repo to ghcr.io
+  - Running workflows on forks (secrets unavailable, GITHUB_TOKEN scoped differently)
+fix: |
+  Add `packages: read` to the workflow-level or job-level permissions block.
+
+  For cross-repository package pulls where GITHUB_TOKEN is insufficient, create a
+  Classic PAT with `read:packages` scope (or a fine-grained PAT with "Packages: read"
+  for the source repo) and store it as a repository secret.
+fix_code:
+  - language: yaml
+    label: "Grant packages: read to pull from ghcr.io"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            packages: read  # ← required for ghcr.io and GitHub Packages
+          steps:
+            - name: Log in to GitHub Container Registry
+              uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Pull image
+              run: docker pull ghcr.io/${{ github.repository_owner }}/my-image:latest
+  - language: yaml
+    label: "Authenticate npm to GitHub Packages with GITHUB_TOKEN"
+    code: |
+      jobs:
+        install:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            packages: read
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Authenticate npm to GitHub Packages
+              run: |
+                echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> ~/.npmrc
+                echo "@myorg:registry=https://npm.pkg.github.com" >> ~/.npmrc
+
+            - run: npm ci
+  - language: yaml
+    label: "Cross-repo package pull using PAT (when GITHUB_TOKEN is insufficient)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Log in to ghcr.io with PAT (cross-repo packages)
+              uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                # PAT with read:packages scope stored as repository secret
+                password: ${{ secrets.PACKAGES_READ_PAT }}
+
+            - run: docker pull ghcr.io/other-org/shared-image:latest
+prevention:
+  - "Always declare explicit `permissions:` blocks — adding ANY permission key removes all defaults, so list everything your job needs."
+  - "Include `packages: read` whenever a job pulls from ghcr.io, npm.pkg.github.com, or maven.pkg.github.com."
+  - "Note that GITHUB_TOKEN is scoped to the current repository; cross-repository package pulls may require a PAT with `read:packages` scope."
+  - "When adding `id-token: write` for OIDC, simultaneously audit all other permissions your jobs need to avoid accidentally removing packages: read."
+docs:
+  - url: "https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions"
+    label: "GitHub docs — Publishing and installing packages with GitHub Actions"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token"
+    label: "GitHub docs — GITHUB_TOKEN permissions reference"
+  - url: "https://stackoverflow.com/questions/64124831/github-actions-401-unauthorized-when-installing-a-github-package-with-npm-or-yarn"
+    label: "Stack Overflow — 401 unauthorized installing GitHub Package with GITHUB_TOKEN"
+  - url: "https://github.com/orgs/community/discussions/162859"
+    label: "Community discussion #162859 — 401 bad request installing GitHub Packages"

package/errors/permissions-auth/oidc-id-token-write-permission-missing.yml

@@ -0,0 +1,169 @@
+id: permissions-auth-016
+title: "OIDC Authentication Fails — id-token: write Missing from Restricted permissions Block"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - id-token
+  - permissions
+  - jwt
+  - aws
+  - azure
+  - gcp
+  - workload-identity
+  - token-request
+patterns:
+  - regex: "id-token.*write|id_token.*write"
+    flags: "i"
+  - regex: "Error:.*OIDC.*provider|No OIDC provider found|OIDC.*not available"
+    flags: "i"
+  - regex: "RequestError.*GetIdToken|Unable to get OIDC token|getIDToken.*failed"
+    flags: "i"
+  - regex: "OIDCError|oidc-client.*failed|could not fetch oidc token"
+    flags: "i"
+error_messages:
+  - "Error: No OIDC provider found. OIDC tokens are not available for this workflow."
+  - "RequestError: Unable to get OIDC token from actions ID token endpoint"
+  - "Error: getIDToken() failed: Could not get ID token. Input required and not supplied: audience"
+  - "OIDCError: Could not fetch OIDC token"
+  - "Error: No permission to get id-token"
+  - "failed to get credentials: failed to get OIDC token: failed to get ID token: Unable to get ID token"
+root_cause: |
+  GitHub Actions OIDC (OpenID Connect) allows workflows to authenticate with cloud
+  providers (AWS, Azure, GCP) using short-lived JWT tokens instead of long-lived secrets.
+  To request an OIDC token, the workflow job MUST have `id-token: write` permission.
+
+  When a workflow or job defines a `permissions:` block, it switches from the **default
+  permissive** mode to **explicit restrictive** mode. In restrictive mode, any permission
+  NOT listed defaults to `none` — including `id-token`.
+
+  Common mistakes that silently remove `id-token: write`:
+
+  1. **Restricting permissions at workflow level without re-granting at job level:**
+     ```yaml
+     permissions:         # Workflow-level restriction
+       contents: read     # id-token implicitly becomes 'none'
+     ```
+
+  2. **Adding `permissions: {}` to lock down a workflow:**
+     ```yaml
+     permissions: {}      # All permissions set to none, including id-token
+     ```
+
+  3. **Following security advice to restrict GITHUB_TOKEN without accounting for OIDC:**
+     Security guides recommend restricting permissions, but if the job uses OIDC,
+     `id-token: write` must be explicitly added back.
+
+  4. **Inheriting a restricted workflow-level permission in a reusable workflow caller:**
+     Callers that set restrictive top-level `permissions:` do not automatically grant
+     `id-token: write` to reusable workflow jobs that need OIDC.
+
+  This is a particularly confusing error because:
+  - The error message "No OIDC provider found" sounds like a configuration issue
+    with the cloud provider, not a GitHub Actions permissions issue
+  - The workflow runs successfully in unrestricted mode (when no `permissions:` block
+    exists and defaults apply), so the error only appears after tightening security
+  Source: GitHub Docs — security hardening OIDC requirements
+  Source: GitHub Community — "No OIDC provider found" recurring discussion
+fix: |
+  Add `id-token: write` to the `permissions:` block for any job that uses OIDC
+  authentication (actions/configure-aws-credentials, azure/login, etc.).
+
+  If `permissions:` is defined at the workflow level, you can either:
+  - Add `id-token: write` to the workflow-level block (grants it to all jobs), or
+  - Override permissions at the job level with `id-token: write` just for the job
+    that needs it (more secure — principle of least privilege)
+
+  Also ensure `contents: read` is present if the job uses `actions/checkout`.
+fix_code:
+  - language: yaml
+    label: "Fix: add id-token: write to the job permissions block"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write     # ✅ Required for OIDC token request
+            contents: read      # Required for actions/checkout
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Configure AWS credentials via OIDC
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
+                aws-region: us-east-1
+
+            - name: Deploy
+              run: aws s3 sync dist/ s3://my-bucket
+
+  - language: yaml
+    label: "Workflow with restricted top-level permissions and OIDC job"
+    code: |
+      name: Deploy
+
+      on:
+        push:
+          branches: [main]
+
+      # Restrict default permissions for the whole workflow
+      permissions:
+        contents: read
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # Inherits workflow-level permissions: contents=read, id-token=none
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build
+                path: dist/
+
+        deploy:
+          runs-on: ubuntu-latest
+          needs: build
+          # ✅ Override permissions at job level to add id-token: write
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build
+
+            - name: Configure Azure login via OIDC
+              uses: azure/login@v2
+              with:
+                client-id: ${{ vars.AZURE_CLIENT_ID }}
+                tenant-id: ${{ vars.AZURE_TENANT_ID }}
+                subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+
+  - language: yaml
+    label: "Reusable workflow: caller must pass id-token write permission"
+    code: |
+      # Caller workflow (in the calling repo)
+      jobs:
+        call-deploy:
+          uses: org/shared-workflows/.github/workflows/deploy.yml@main
+          permissions:
+            id-token: write    # ✅ Caller must grant this for the reusable workflow
+            contents: read
+          with:
+            environment: production
+
+prevention:
+  - "Whenever you add a `permissions:` block, explicitly include `id-token: write` for any job using OIDC."
+  - "Audit OIDC-dependent jobs after adding or tightening `permissions:` blocks."
+  - "Use job-level permissions instead of workflow-level when only some jobs need OIDC — principle of least privilege."
+  - "Document `id-token: write` with an inline comment explaining it is required for OIDC authentication."
+  - "For reusable workflows using OIDC: callers must explicitly pass `id-token: write` in their job permissions."
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#adding-permissions-settings"
+    label: "GitHub Docs: OIDC — Adding permissions settings (id-token: write)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token#modifying-the-permissions-for-the-github_token"
+    label: "GitHub Docs: Controlling permissions for GITHUB_TOKEN"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token#defining-access-for-the-github_token-scopes"
+    label: "GitHub Docs: Defining access for GITHUB_TOKEN scopes"

package/errors/permissions-auth/permissions-empty-block-removes-contents-read.yml

@@ -0,0 +1,97 @@
+id: permissions-auth-017
+title: "Empty permissions: {} Block Removes contents: read, Breaking Checkout on Private Repos"
+category: permissions-auth
+severity: error
+tags:
+  - permissions
+  - github-token
+  - contents-read
+  - checkout
+  - private-repo
+  - security-hardening
+patterns:
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+  - regex: "403.*Resource not accessible"
+    flags: "i"
+  - regex: "HttpError.*Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "Error: Resource not accessible by integration"
+  - "HttpError: Resource not accessible by integration"
+  - "remote: Repository not found.\nError: The process '/usr/bin/git' failed with exit code 128"
+  - "Error: fatal: repository 'https://github.com/owner/repo/' not found"
+root_cause: |
+  GitHub Actions workflows have a default token permission set controlled by the repository's
+  settings. When you add a `permissions:` block to a workflow or job, you are making permissions
+  EXPLICIT — any scope not listed is set to `none`, even if it was previously granted by default.
+
+  An empty `permissions: {}` block (or `permissions:` with no sub-keys) silently removes ALL
+  permissions including `contents: read`. This causes `actions/checkout` to fail on private
+  repositories because the GITHUB_TOKEN no longer has permission to clone the repository.
+
+  This is counterintuitive because developers often add `permissions: {}` as a security hardening
+  step without realizing it removes the read access needed for basic workflow operations like
+  checking out code.
+
+  The failure appears immediately at the checkout step. On public repositories, checkout may
+  succeed (public repos allow unauthenticated read) but any write operations, API calls, or
+  steps requiring token scopes will silently receive no permissions.
+fix: |
+  Always specify the minimum required permissions explicitly. At minimum, include
+  `contents: read` to allow `actions/checkout` to clone the repository. Add other scopes
+  only as needed for the workflow's specific operations.
+fix_code:
+  - language: yaml
+    label: "Minimal permissions: checkout only"
+    code: |
+      permissions:
+        contents: read   # required for actions/checkout on private repos
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Typical CI workflow permissions"
+    code: |
+      permissions:
+        contents: read      # checkout
+        pull-requests: write  # comment on PRs
+        checks: write       # report check status
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            # ...
+  - language: yaml
+    label: "Read-only lockdown (safest baseline)"
+    code: |
+      # At workflow level: lock down everything to read-only
+      permissions:
+        contents: read
+        packages: read
+
+      jobs:
+        deploy:
+          # Override at job level for the job that needs write access
+          permissions:
+            contents: read
+            deployments: write
+            id-token: write   # OIDC
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Never use `permissions: {}` — always list scopes explicitly with their required levels"
+  - "Include `contents: read` as the minimum permission in every workflow that uses actions/checkout"
+  - "Use job-level permissions overrides to grant elevated scopes only where needed, not at the workflow level"
+  - "GitHub's security hardening guide recommends workflow-level read-only + job-level write overrides as the safest pattern"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token"
+    label: "GitHub Docs — Controlling permissions for GITHUB_TOKEN"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-permissions-for-github_token"
+    label: "GitHub Docs — Security hardening: using permissions for GITHUB_TOKEN"

package/errors/permissions-auth/reusable-workflow-permissions-not-inherited.yml

@@ -0,0 +1,114 @@
+id: permissions-auth-012
+title: "Reusable Workflow Permissions Not Inherited from Caller — Must Be Granted Explicitly"
+category: permissions-auth
+severity: error
+tags:
+  - reusable-workflow
+  - permissions
+  - github-token
+  - caller
+  - contents
+patterns:
+  - regex: "is requesting '([^']+)', but is only allowed '([^']+)'"
+    flags: "i"
+  - regex: "The workflow.*is requesting.*but is only allowed"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/caller.yml: Error calling workflow 'org/repo/.github/workflows/reusable.yml@main'. The workflow 'org/repo/.github/workflows/reusable.yml@main' is requesting 'contents: read', but is only allowed 'contents: none'."
+  - "Resource not accessible by integration"
+root_cause: |
+  When a workflow calls a reusable workflow using `jobs.<job>.uses`, the called workflow
+  runs with a GITHUB_TOKEN whose permissions are the INTERSECTION of:
+  1. The permissions declared in the caller workflow (or job)
+  2. The permissions the called reusable workflow needs
+
+  Reusable workflows do NOT automatically inherit the caller's permissions. If the caller
+  workflow declares a restrictive permissions block (or relies on repository-default
+  read-all), but the reusable workflow declares or needs broader permissions, the call
+  fails at validation time with:
+
+    "The workflow 'X' is requesting 'contents: read', but is only allowed 'contents: none'."
+
+  This also manifests at runtime as "Resource not accessible by integration" (HTTP 403)
+  when the reusable workflow's steps attempt API calls or git operations that require
+  permissions not granted by the caller.
+
+  Common scenarios:
+  - Caller explicitly sets `permissions: {}` (no permissions) for security hardening
+  - Caller sets only `id-token: write` for OIDC but reusable workflow needs `contents: read`
+  - Repository setting "Read and write permissions" is overridden to "Read repository
+    contents and packages permissions" at org level, reducing the default token scope
+  - Caller passes `secrets: inherit` but forgets to also pass `permissions:`
+
+  Source: GitHub Community Discussion #52665
+fix: |
+  Explicitly grant the required permission scopes in the **caller** workflow, at either
+  the workflow level or the specific job level that uses the reusable workflow.
+
+  To discover which permissions a reusable workflow needs, check its `on.workflow_call`
+  declaration or read its steps to see which GitHub API/resource operations it performs.
+
+  Follow least privilege: grant only what the reusable workflow actually needs, not
+  blanket read-all.
+fix_code:
+  - language: yaml
+    label: "Broken — caller grants no permissions, reusable workflow needs contents"
+    code: |
+      # ❌ BROKEN: caller sets permissions: {} — reusable workflow inherits none
+      name: Release
+      on: push
+
+      permissions: {}  # Locks down all permissions — nothing passes through
+
+      jobs:
+        release:
+          uses: my-org/shared-workflows/.github/workflows/release.yml@main
+          # Error: release.yml requests 'contents: write' but caller allows 'contents: none'
+  - language: yaml
+    label: "Fixed — grant required scopes explicitly at the job level"
+    code: |
+      # ✅ FIXED: grant only what the reusable workflow needs
+      name: Release
+      on: push
+
+      permissions: {}  # Lock down at workflow level for security
+
+      jobs:
+        release:
+          permissions:
+            contents: write       # Required by the reusable workflow for creating releases
+            id-token: write       # Required for OIDC if the reusable workflow uses it
+          uses: my-org/shared-workflows/.github/workflows/release.yml@main
+  - language: yaml
+    label: "Fixed — grant permissions at workflow level when multiple jobs use reusable workflows"
+    code: |
+      # ✅ FIXED: grant at workflow level when multiple jobs need the same scopes
+      name: CI
+      on: [push, pull_request]
+
+      permissions:
+        contents: read          # Needed for checkout in reusable workflows
+        packages: write         # Needed for reusable workflow that publishes packages
+        pull-requests: write    # Needed for reusable workflow that adds PR comments
+
+      jobs:
+        build:
+          uses: my-org/shared-workflows/.github/workflows/build.yml@main
+        publish:
+          needs: build
+          uses: my-org/shared-workflows/.github/workflows/publish.yml@main
+prevention:
+  - "Always read the reusable workflow's steps to know which permissions it needs before calling it."
+  - "Test reusable workflow calls from a caller with explicit `permissions: {}` first — failures reveal required scopes."
+  - "Document required permissions in the reusable workflow's `on.workflow_call` block as comments."
+  - "When adding `permissions:` to a caller, remember that declaring ANY permission sets all others to `none` — enumerate every scope you need."
+  - "Use job-level `permissions:` rather than workflow-level to apply least-privilege per job."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows"
+    label: "Reusing workflows — permissions and access"
+  - url: "https://github.com/orgs/community/discussions/52665"
+    label: "GitHub Community #52665 — reusable workflow permissions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token"
+    label: "Controlling permissions for GITHUB_TOKEN"