@htekdev/actions-debugger 1.0.14 → 1.0.15

package/errors/permissions-auth/fine-grained-pat-deployment-write-required.yml

@@ -0,0 +1,146 @@
+id: permissions-auth-015
+title: "Fine-Grained PAT Requires 'deployments: write' to Approve or Reject Deployments (Was 'read')"
+category: permissions-auth
+severity: error
+tags:
+  - fine-grained-pat
+  - deployments
+  - permissions
+  - pat
+  - environments
+  - approval
+  - breaking-change
+patterns:
+  - regex: "Resource not accessible by integration.*deployment|403.*deployment.*approve"
+    flags: "i"
+  - regex: "Must have admin rights to Repository.*approve.*deployment|permission.*deployments.*write"
+    flags: "i"
+  - regex: "HttpError: Resource not accessible by integration.*reviewers"
+    flags: "i"
+  - regex: "403.*Unable to approve deployment|Forbidden.*approve.*pending.*deployment"
+    flags: "i"
+error_messages:
+  - "Resource not accessible by integration"
+  - "HttpError: Resource not accessible by integration"
+  - "Error: RequestError [HttpError]: Resource not accessible by integration"
+  - "Must have admin rights to Repository. - https://docs.github.com/rest/deployments/deployments"
+  - "403: Forbidden - You need deployments:write permission to approve or reject a deployment."
+root_cause: |
+  On April 1, 2025, GitHub changed how deployment approval permissions work for
+  fine-grained personal access tokens (PATs). Prior to this change, a fine-grained PAT
+  with `deployments: read` permission could approve, approve-with-comment, or reject pending
+  deployments in protected environments. After April 1, 2025, the `deployments: write`
+  permission is **required** to review deployments.
+
+  This change was announced in the GitHub Changelog on March 20, 2025. Impacted customers
+  were notified by email in early March 2025. Fine-grained PATs that were created before
+  the change and only granted `deployments: read` stopped being able to approve or reject
+  deployments on April 1, 2025 without any change to the token itself — existing tokens
+  suddenly lost the ability they previously had.
+
+  **Affected scenarios:**
+  - GitHub Actions workflows that call `POST /repos/{owner}/{repo}/actions/runs/{run_id}/approvals`
+    or `POST /repos/{owner}/{repo}/actions/runs/{run_id}/pending_deployments` with a
+    fine-grained PAT that only has `deployments: read`
+  - Custom deployment orchestration scripts using fine-grained PATs
+  - GitHub Apps or OAuth apps authenticated via fine-grained PAT that approved deployments
+
+  **Note:** Classic PATs and GitHub Apps with `deployments: write` scope are unaffected.
+  GitHub Apps using their own installation token (not a fine-grained PAT) are also
+  unaffected as long as they have the `deployments: write` permission in their app settings.
+fix: |
+  Update the fine-grained PAT to grant `deployments: write` permission instead of
+  `deployments: read`:
+
+  1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
+  2. Click the PAT used in your workflow
+  3. Click "Regenerate token"
+  4. Under "Permissions → Repository permissions → Deployments", change from "Read" to "Read and write"
+  5. Update the secret in your repository/organization with the new token value
+
+  If you use a GitHub App instead of a PAT for deployments, ensure the App's repository
+  permission for "Deployments" is set to "Read and write" in the App settings.
+fix_code:
+  - language: yaml
+    label: "Workflow using octokit to approve deployments — ensure PAT has deployments:write"
+    code: |
+      jobs:
+        approve-deployment:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Approve pending deployment
+              uses: actions/github-script@v7
+              with:
+                # This PAT MUST have deployments:write permission (not just read)
+                github-token: ${{ secrets.DEPLOYMENT_APPROVAL_PAT }}
+                script: |
+                  const pendingDeployments = await github.rest.actions.getPendingDeploymentsForRun({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    run_id: context.runId
+                  });
+
+                  const environmentIds = pendingDeployments.data
+                    .filter(d => d.environment.name === 'production')
+                    .map(d => d.environment.id);
+
+                  await github.rest.actions.reviewPendingDeploymentsForRun({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    run_id: context.runId,
+                    environment_ids: environmentIds,
+                    state: 'approved',
+                    comment: 'Auto-approved by CI orchestration'
+                  });
+  - language: yaml
+    label: "Verify token permissions before attempting deployment approval"
+    code: |
+      jobs:
+        check-permissions:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Verify deployment token scope
+              uses: actions/github-script@v7
+              with:
+                github-token: ${{ secrets.DEPLOYMENT_APPROVAL_PAT }}
+                script: |
+                  // Try a read operation first to confirm token is valid
+                  const token = process.env.GITHUB_TOKEN;
+
+                  // Check deployments permission by listing — uses read; write needed for approve
+                  const deployments = await github.rest.repos.listDeployments({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo
+                  });
+                  console.log(`Token valid — found ${deployments.data.length} deployments.`);
+                  console.log('NOTE: To APPROVE deployments, this PAT needs deployments:write, not just read.');
+  - language: yaml
+    label: "Use GITHUB_TOKEN with environment protection rules instead of fine-grained PAT"
+    code: |
+      # Better pattern: let GitHub's environment protection handle approvals
+      # rather than auto-approving via API with a PAT
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment:
+            name: production
+            # Configure required reviewers in Environment settings
+            # No custom PAT needed — GITHUB_TOKEN works for normal deployment flows
+          steps:
+            - name: Deploy
+              run: echo "Deploying to production..."
+              # The 'environment' key above enforces approval through GitHub UI
+              # without needing deployments:write in a PAT
+prevention:
+  - "When creating fine-grained PATs for CI/CD deployment workflows, always grant `deployments: write` upfront — even if you only need read today, write is required for any approval-related operation."
+  - "Audit all fine-grained PATs used in GitHub Actions for their `deployments` permission level after the April 2025 change."
+  - "Prefer using GitHub's built-in environment protection rules (required reviewers, wait timers) over custom approval scripts with PATs — fewer moving parts."
+  - "Subscribe to the GitHub Changelog to receive advance notice of breaking permission changes."
+docs:
+  - url: "https://github.blog/changelog/2025-03-20-notification-of-upcoming-breaking-changes-in-github-actions/"
+    label: "GitHub Changelog: Modification to deployment permissions (March 20, 2025)"
+  - url: "https://docs.github.com/en/rest/actions/workflow-runs#review-pending-deployments-for-a-workflow-run"
+    label: "GitHub REST API: Review pending deployments for a workflow run"
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token"
+    label: "GitHub Docs: Creating a fine-grained personal access token"

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"