@htekdev/actions-debugger 1.0.22 → 1.0.24

package/errors/known-unsolved/no-job-allow-failure.yml

@@ -0,0 +1,73 @@
+id: known-unsolved-026
+title: "No Native allow-failure Mechanism for Jobs"
+category: known-unsolved
+severity: limitation
+tags:
+  - continue-on-error
+  - allow-failure
+  - job-status
+  - pr-checks
+  - known-limitation
+patterns:
+  - regex: "allow.?failure"
+    flags: "i"
+  - regex: "continue-on-error.*(still|marked).*(fail|error)"
+    flags: "i"
+error_messages:
+  - "allow-failure is not a valid key for jobs"
+  - "Job failed but continue-on-error is set — result is still 'failure'"
+root_cause: |
+  GitHub Actions has no native `allow-failure` key for jobs (unlike GitLab CI's `allow_failure`).
+  Adding `allow-failure: true` to a job produces a YAML validation error or is silently ignored
+  because it is not a recognized field.
+
+  The closest equivalent is `continue-on-error: true`, but this has different semantics:
+  - The job still shows as failed in the workflow run summary (yellow warning icon, not green check).
+  - If the job is listed as a required status check in branch protection, the PR is still blocked.
+  - The overall workflow conclusion becomes "success" but the individual job result remains "failure".
+  - Downstream jobs using `needs.<job>.result == 'success'` will not execute.
+
+  This is a long-standing platform gap with 1,571 GitHub reactions (actions/runner#2347) and a
+  community discussion with broad support (orgs/community/discussions/15452).
+fix: |
+  There is no perfect equivalent to allow-failure. The recommended workaround is `continue-on-error: true`
+  on the optional job, combined with a separate "gate" job that aggregates results and is made the
+  required status check in branch protection instead.
+
+  1. Add `continue-on-error: true` to the optional job.
+  2. Add a gate job with `needs: [optional-job]` and `if: always()`.
+  3. The gate job always succeeds — make it the required branch-protection check.
+  4. Downstream jobs check `needs.optional-job.result` explicitly if needed.
+fix_code:
+  - language: yaml
+    label: "Workaround: gate job pattern for allow-failure equivalent"
+    code: |
+      jobs:
+        optional-flaky:
+          runs-on: ubuntu-latest
+          continue-on-error: true   # job can fail without blocking workflow
+          steps:
+            - run: ./run-flaky-tests.sh
+
+        required-gate:
+          runs-on: ubuntu-latest
+          needs: [optional-flaky]
+          if: always()              # always runs regardless of optional-flaky result
+          steps:
+            - name: Report optional job outcome
+              run: |
+                echo "Optional job result: ${{ needs.optional-flaky.result }}"
+                # This step always exits 0 — make required-gate the branch protection check
+                exit 0
+prevention:
+  - "Do not add allow-failure: true to jobs — it is not a recognized Actions field and causes a workflow validation error."
+  - "Use continue-on-error: true as the closest equivalent but understand its PR check implications."
+  - "For required status checks, use the gate/aggregator job pattern — never the optional job itself."
+  - "Track orgs/community/discussions/15452 for official platform support of allow-failure."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow"
+    label: "GitHub Actions — Using jobs in a workflow (continue-on-error)"
+  - url: "https://github.com/actions/runner/issues/2347"
+    label: "actions/runner #2347 — allow-failure support request (1571 reactions)"
+  - url: "https://github.com/orgs/community/discussions/15452"
+    label: "Community discussion #15452 — allow-failure for jobs"

package/errors/known-unsolved/reusable-secrets-inherit-not-deep-forwarded.yml

@@ -0,0 +1,113 @@
+id: known-unsolved-021
+title: "secrets: inherit Does Not Cascade to Second-Level Nested Reusable Workflows"
+category: known-unsolved
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - secrets
+  - secrets-inherit
+  - nesting
+  - silent-failure
+
+patterns:
+  - regex: "secret .+ is required, but not provided"
+    flags: "i"
+  - regex: "secrets\\.\\w+ is not a valid secret key"
+    flags: "i"
+
+error_messages:
+  - "Secret GIT_PAT is required, but not provided"
+  - "Required secret 'MY_SECRET' was not provided by the caller"
+
+root_cause: |
+  `secrets: inherit` in a caller workflow passes ALL repository and organization
+  secrets to the directly-called (first-level) reusable workflow. However, if that
+  reusable workflow then calls ANOTHER reusable workflow (second level), those
+  inherited secrets are NOT automatically forwarded to the second level.
+
+  Each `workflow_call` boundary is a discrete secrets scope. `secrets: inherit`
+  only covers one hop. If you have:
+
+    root.yml  →  (secrets: inherit)  →  level1.yml  →  level2.yml
+
+  then `level2.yml` receives an empty secrets context unless `level1.yml`
+  explicitly passes them via its own `secrets:` block.
+
+  This is a platform design decision, not a bug. GitHub has confirmed that
+  `secrets: inherit` does not cascade through multiple `workflow_call` layers.
+  There is no current mechanism for automatic multi-level secret propagation.
+
+  Community reports: actions/runner#2709 (open, labeled bug, 8 👍, 2023–2025),
+  community/discussions/23107.
+
+fix: |
+  Explicitly declare and pass secrets at EVERY reusable workflow boundary.
+
+  For level1.yml to forward secrets to level2.yml, level1.yml must:
+    1. Declare secrets in its on.workflow_call.secrets block.
+    2. Pass those secrets explicitly in the jobs.*.secrets block when calling level2.yml.
+
+  Alternatively, use `secrets: inherit` at EACH level — but the calling workflow
+  (level1.yml) itself must also explicitly declare the secrets it expects so
+  they are available in its scope to pass down.
+
+fix_code:
+  - language: yaml
+    label: "root.yml — caller uses secrets: inherit for first hop"
+    code: |
+      jobs:
+        call-level1:
+          uses: ./.github/workflows/level1.yml
+          secrets: inherit   # passes ALL secrets to level1.yml only
+
+  - language: yaml
+    label: "level1.yml — must declare AND re-forward secrets to level2.yml"
+    code: |
+      on:
+        workflow_call:
+          secrets:
+            MY_SECRET:
+              required: true
+            DEPLOY_TOKEN:
+              required: false
+
+      jobs:
+        call-level2:
+          uses: ./.github/workflows/level2.yml
+          secrets:
+            MY_SECRET: ${{ secrets.MY_SECRET }}       # explicit re-forward
+            DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} # explicit re-forward
+
+  - language: yaml
+    label: "level2.yml — must declare secrets it expects"
+    code: |
+      on:
+        workflow_call:
+          secrets:
+            MY_SECRET:
+              required: true
+            DEPLOY_TOKEN:
+              required: false
+
+      jobs:
+        use-secrets:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use secret
+              run: echo "token length = ${#MY_SECRET}"
+              env:
+                MY_SECRET: ${{ secrets.MY_SECRET }}
+
+prevention:
+  - "Audit every workflow_call boundary in nested reusable workflows — each hop must explicitly forward secrets."
+  - "Document required secrets at every level in workflow comments to avoid silent empty-string failures."
+  - "Use composite actions instead of nested reusable workflows when secrets do not need to cross job boundaries — composite actions share the parent job's secrets context automatically."
+  - "Test nested workflows by echoing a non-sensitive derived value (e.g., secret length) at each level to confirm propagation."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/reusing-workflows#passing-secrets-to-nested-workflows"
+    label: "GitHub Docs — Passing secrets to nested workflows"
+  - url: "https://github.com/actions/runner/issues/2709"
+    label: "actions/runner#2709 — Passing secrets to reusable workflow does not work (open, 2023)"
+  - url: "https://github.com/orgs/community/discussions/23107"
+    label: "community/discussions#23107 — Inheriting secrets in reusable workflows"

package/errors/known-unsolved/schedule-cron-hours-long-queue-drift.yml

@@ -0,0 +1,101 @@
+id: known-unsolved-025
+title: "Scheduled Workflow Queue Drift Exceeds Hours and Worsens Over Time"
+category: known-unsolved
+severity: limitation
+tags:
+  - cron
+  - schedule
+  - drift
+  - queue-delay
+  - best-effort
+  - platform-load
+patterns:
+  - regex: "schedule"
+    flags: "i"
+error_messages:
+  - "Scheduled workflows can be delayed during periods of high loads of GitHub Actions workflow runs."
+root_cause: |
+  GitHub Actions scheduled workflows use a best-effort queue. GitHub does not guarantee
+  that a schedule: trigger fires at the exact cron time. During periods of high platform
+  load, workflows are queued and the dispatch delay can reach multiple hours.
+
+  Since 2025, average delays have been growing on the GitHub-hosted infrastructure:
+  workflows that previously started within 10-20 minutes now commonly wait 1-4+ hours.
+  The drift is not constant — it varies by time of day and platform load and compounds
+  over months for daily/nightly jobs.
+
+  Key contributing factors:
+  - Growth in GitHub's user base means more repositories with scheduled workflows compete
+    for the same dispatch queue infrastructure.
+  - The midnight UTC window is severely congested; nearby times face similar load.
+  - GitHub dispatches schedule events in batches; individual repos have no dispatch priority.
+  - Repositories with no activity for 60+ days have their schedules disabled entirely.
+  - GitHub's documentation explicitly states schedules are best-effort with no SLA.
+
+  This is a known platform-capacity limitation, not a bug. No fix or workaround guarantees
+  on-time execution from within GitHub's scheduler.
+  Reported in actions/runner#4468 (open Jun 2026); discussed in community/196910.
+fix: |
+  There is no way to guarantee on-time execution of a scheduled GitHub Actions workflow.
+  Mitigation strategies depend on how time-sensitive the job is.
+
+  Mitigation 1: Schedule away from congestion windows.
+  Avoid exact hours and midnight UTC. Use irregular minutes and off-peak hours
+  (e.g., 23 14 * * * instead of 0 0 * * *).
+
+  Mitigation 2: Use an external cron service with workflow_dispatch.
+  Remove the on: schedule trigger and replace it with workflow_dispatch. An external
+  scheduler (cloud function, server cron, GitHub App) calls the GitHub REST API dispatches
+  endpoint on time. The workflow starts immediately because workflow_dispatch jobs are not
+  subject to the schedule queue.
+
+  Mitigation 3: Accept the delay and build tolerance.
+  For non-time-critical automations (nightly builds, maintenance tasks), build tolerance
+  into downstream systems rather than fighting the delay.
+
+  Mitigation 4: Self-hosted runners with external scheduling.
+  For strict timing requirements, combine self-hosted runners with an external trigger so
+  the job bypasses GitHub hosted-runner queuing entirely.
+fix_code:
+  - language: yaml
+    label: "Use irregular schedule time to avoid peak congestion"
+    code: |
+      on:
+        schedule:
+          # Avoid :00, :15, :30, :45 and midnight UTC — use irregular off-peak times
+          - cron: '23 14 * * *'   # 2:23 PM UTC
+        workflow_dispatch: {}     # Manual fallback for missed or delayed runs
+  - language: yaml
+    label: "External cron dispatch via GitHub API (reliable timing)"
+    code: |
+      # External scheduler (Lambda, cron job, GitHub App) calls:
+      # curl -X POST \
+      #   -H "Authorization: Bearer $GH_TOKEN" \
+      #   https://api.github.com/repos/OWNER/REPO/actions/workflows/nightly.yml/dispatches \
+      #   -d '{"ref":"main"}'
+      #
+      # Your workflow — no on: schedule needed:
+      on:
+        workflow_dispatch: {}
+
+      jobs:
+        nightly:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/nightly-build.sh
+prevention:
+  - "Never build SLAs or downstream dependencies that assume a scheduled workflow starts within minutes of its cron time."
+  - "Always add workflow_dispatch: alongside schedule: so delayed or missed runs can be manually triggered from the Actions UI."
+  - "Use non-round-number cron minutes (17, 23, 41, etc.) to avoid the most congested slots."
+  - "For time-critical jobs, use an external scheduler that calls the GitHub API rather than relying on GitHub scheduler queue."
+  - "Track repository activity — GitHub disables scheduled workflows on repos inactive for 60+ days."
+docs:
+  - url: "https://github.com/actions/runner/issues/4468"
+    label: "actions/runner#4468 — Continuously increasing schedule drift (Jun 2026)"
+  - url: "https://github.com/orgs/community/discussions/196910"
+    label: "Community discussion: schedule drift increasing over time"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "schedule event — best-effort documentation"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Scheduled workflow disabled after 60 days inactivity"

package/errors/permissions-auth/checkout-persist-credentials-token-write.yml

@@ -0,0 +1,90 @@
+id: permissions-auth-028
+title: "checkout persist-credentials:true Default Stores GITHUB_TOKEN in .git/config"
+category: permissions-auth
+severity: warning
+tags:
+  - checkout
+  - persist-credentials
+  - github-token
+  - security
+  - credential-helper
+patterns:
+  - regex: "persist.credentials.*(true|default)|persist-credentials.*not.*false"
+    flags: "i"
+  - regex: "\\.git.config.*token|credential.*helper.*store.*github"
+    flags: "i"
+error_messages:
+  - "GITHUB_TOKEN persisted in .git/config by actions/checkout"
+  - "Unexpected repository write from a non-commit step"
+root_cause: |
+  `actions/checkout` defaults to `persist-credentials: true`. When enabled, the action configures
+  a credential helper that stores the GITHUB_TOKEN in the repository local `.git/config`.
+  Every repository operation in subsequent steps automatically uses this token for authentication,
+  without any explicit credential setup in those steps.
+
+  Consequences:
+  - Any step that invokes the source control client (directly or via tools that do so internally)
+    inherits repository write access if the job holds `contents: write` permission.
+  - Third-party tools that call the source control client internally (Docker buildx, dependency
+    managers reading version tags, build tools) receive unintended repository access.
+  - In fork PR workflows (`pull_request_target`), checking out a fork ref with persisted
+    credentials gives forked code implicit access to secrets via subsequent repository operations.
+  - Unintended repository writes can occur from any step that invokes write-mode operations.
+
+  The default remains `true` for backward compatibility, but silently increases attack surface
+  for every job that does not need post-checkout write access.
+
+  167 reactions on actions/checkout#485 (open since 2021).
+fix: |
+  Set `persist-credentials: false` on all checkout steps that do not require authenticated
+  repository operations in later steps. Jobs that do need to write back to the repo should
+  use a scoped credential pattern or a dedicated auto-commit action that manages credentials
+  explicitly in its own isolated context.
+fix_code:
+  - language: yaml
+    label: "Recommended: disable persist-credentials for read-only jobs (build, lint, test)"
+    code: |
+      steps:
+        # Token NOT stored in .git/config — safe for read-only jobs
+        - uses: actions/checkout@v4
+          with:
+            persist-credentials: false
+
+        - name: Build and test
+          run: npm ci && npm test
+
+  - language: yaml
+    label: "Scoped: only persist credentials for jobs that explicitly write back to repo"
+    code: |
+      jobs:
+        read-only-analysis:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                persist-credentials: false   # no ambient write access
+
+        write-back:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+          steps:
+            # persist-credentials: true (default) only where write is explicitly intended
+            - uses: actions/checkout@v4
+
+            - name: Generate and commit output
+              uses: stefanzweifel/auto-commit-action@v5
+              with:
+                commit_message: "chore: auto-generated output"
+prevention:
+  - "Default to persist-credentials: false — only omit (use default true) when authenticated repository operations are explicitly needed in later steps."
+  - "Audit jobs that rely on the implicit default and also hold contents:write permission."
+  - "In pull_request_target workflows, always set persist-credentials: false when checking out fork refs."
+  - "Review third-party tools in the job that invoke the source control client internally."
+docs:
+  - url: "https://github.com/actions/checkout/issues/485"
+    label: "actions/checkout #485 — Remove persist-credentials or change default (167 reactions)"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions"
+    label: "GitHub Security Hardening for GitHub Actions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs"
+    label: "GitHub Actions — GITHUB_TOKEN permissions"

package/errors/permissions-auth/create-github-app-token-cross-job-token-revoked.yml

@@ -0,0 +1,95 @@
+id: permissions-auth-027
+title: "create-github-app-token token auto-revoked in post step — cannot pass to downstream jobs"
+category: permissions-auth
+severity: silent-failure
+tags:
+  - create-github-app-token
+  - github-app
+  - token-revocation
+  - cross-job
+  - job-outputs
+  - masked-secrets
+patterns:
+  - regex: "HttpError.*401.*Bad credentials"
+    flags: "i"
+  - regex: "Token has been revoked"
+    flags: "i"
+  - regex: "RequestError.*401"
+    flags: "i"
+error_messages:
+  - "HttpError: Bad credentials"
+  - "Error: 401 Bad credentials"
+  - "RequestError: 401 Unauthorized"
+root_cause: |
+  actions/create-github-app-token automatically revokes the generated installation token
+  in the action's post step (after the job completes). This means a token generated in
+  job A and passed as a job output to job B will already be revoked by the time job B
+  runs. Additionally, GitHub Actions automatically masks any value that looks like a
+  token (matching the ghp_, ghs_, ghu_, github_pat_, etc. prefixes). Masked values
+  cannot be passed through job outputs — the runner replaces them with "***" in outputs,
+  so the downstream job receives a masked/empty string rather than the actual token value.
+  Setting skip-token-revoke: true is necessary but not sufficient: the masking mechanism
+  still prevents the token from appearing as a job output.
+fix: |
+  Recreate the token in each job that needs it by calling actions/create-github-app-token
+  as a step within each dependent job. This is the recommended pattern from the action
+  maintainers. Do not attempt to pass the token through job outputs.
+fix_code:
+  - language: yaml
+    label: "Wrong: token passed through job output (always fails)"
+    code: |
+      jobs:
+        get-token:
+          runs-on: ubuntu-latest
+          outputs:
+            token: ${{ steps.app-token.outputs.token }}  # BROKEN: masked, will be ***
+          steps:
+            - id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+        use-token:
+          needs: get-token
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "token is ${{ needs.get-token.outputs.token }}"
+              # Always prints "***" — token unusable
+  - language: yaml
+    label: "Correct: recreate token in each job that needs it"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - id: app-token       # recreate — do not reuse from build job
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+            - run: ./deploy.sh
+              env:
+                GH_TOKEN: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "Never pass GitHub App tokens through job outputs — the token is masked and will be empty"
+  - "Recreate the token in every job that needs it using a dedicated create-github-app-token step"
+  - "Store APP_ID as a repository variable (vars.APP_ID) and private key as a secret"
+  - "Consider using a GitHub App with fine-grained permissions to minimize the blast radius of token exposure"
+docs:
+  - url: "https://github.com/actions/create-github-app-token/issues/66"
+    label: "actions/create-github-app-token#66: output token cannot be used across jobs"
+  - url: "https://github.com/actions/create-github-app-token#usage"
+    label: "actions/create-github-app-token: Usage documentation"
+  - url: "https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-to-access-secrets"
+    label: "GitHub Docs: Security hardening — intermediate environment for secrets"

package/errors/permissions-auth/github-token-contents-write-missing-git-push.yml

@@ -0,0 +1,117 @@
+id: permissions-auth-025
+title: "GITHUB_TOKEN Missing contents:write — git push Returns 403 Write Access Not Granted"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - contents-write
+  - git-push
+  - 403
+  - permissions-block
+  - auto-commit
+  - write-access
+patterns:
+  - regex: "remote: Write access to repository not granted"
+    flags: "i"
+  - regex: "error: failed to push some refs"
+    flags: "i"
+  - regex: "refusing to allow.*GitHub Actions.*to create or update workflow"
+    flags: "i"
+  - regex: "HttpError: Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "remote: Write access to repository not granted."
+  - "error: failed to push some refs to 'https://github.com/owner/repo.git'"
+  - "fatal: unable to access 'https://github.com/owner/repo.git/': The requested URL returned error: 403"
+  - "Resource not accessible by integration"
+root_cause: |
+  The GITHUB_TOKEN is scoped by the `permissions:` block on the workflow or job. When any
+  `permissions:` block is present, all unspecified permissions are set to `none` (not to their
+  defaults). If `contents: write` is not explicitly granted, any `git push`, `git commit`, or
+  REST API call that writes to the repository will be rejected with HTTP 403 "Write access to
+  repository not granted."
+
+  Three common situations:
+
+  1. **Minimal permissions block** — the workflow declares `permissions: read-all` or lists
+     specific permissions (e.g., `pull-requests: write`) but omits `contents: write`. Any
+     subsequent git push fails with 403.
+
+  2. **Inherited restrictive org policy** — the organization sets the default token permission
+     to "read repository contents" (Settings → Actions → General → Workflow permissions). Without
+     an explicit `contents: write` in the workflow, the token cannot push.
+
+  3. **Fine-grained token in workflow context** — a PAT or GitHub App token is used for checkout
+     but the GITHUB_TOKEN (still the effective token for `git push`) lacks write access.
+
+  This is distinct from `permissions-auth-017` (empty `permissions: {}` block removing
+  `contents: read` and breaking checkout). This pattern specifically affects git write operations
+  and REST API calls that create or update repository content.
+fix: |
+  Add `contents: write` to the permissions block on the job or workflow where the push occurs.
+  Grant the narrowest scope needed — prefer job-level `permissions:` over workflow-level to
+  limit the blast radius.
+
+  If the org policy sets the default to "read-only", every workflow that writes to the repo
+  must explicitly declare `contents: write`.
+fix_code:
+  - language: yaml
+    label: "Add contents:write at the job level (preferred — narrowest scope)"
+    code: |
+      jobs:
+        auto-commit:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write   # ← required for git push / creating commits via API
+          steps:
+            - uses: actions/checkout@v4
+            - name: Bump version and push
+              run: |
+                git config user.name  "github-actions[bot]"
+                git config user.email "github-actions[bot]@users.noreply.github.com"
+                npm version patch --no-git-tag-version
+                git add package.json
+                git commit -m "chore: bump version [skip ci]"
+                git push
+  - language: yaml
+    label: "Org default is read-only — always set explicit contents:write for push workflows"
+    code: |
+      # When Settings → Actions → General → Workflow permissions = "Read repository contents and packages"
+      # EVERY workflow that pushes must declare contents: write:
+
+      permissions:
+        contents: write       # required for git push, release creation, branch creation
+        pull-requests: write  # only if the workflow also comments on PRs
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Create release
+              run: gh release create "${{ github.ref_name }}" --generate-notes
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Debug: print effective token permissions before failing"
+    code: |
+      - name: Check token permissions
+        run: |
+          gh api /repos/${{ github.repository }} --jq '.permissions'
+          gh auth status
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Always add `contents: write` to any job that does `git push`, `git tag`, creates releases, or writes files via the GitHub API."
+  - "Set the organization default to 'Read and write' only when necessary; otherwise document that all push workflows must declare `contents: write`."
+  - "Use job-level `permissions:` blocks instead of workflow-level to minimize token scope."
+  - "Add a permissions comment near the `permissions:` block listing what each grant is needed for, so future maintainers don't accidentally remove it."
+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://stackoverflow.com/questions/79437803/git-commit-in-github-actions-workflow-failing-write-access-to-repository-not"
+    label: "SO#79437803 — git commit failing: Write access to repository not granted, 403"
+  - url: "https://stackoverflow.com/questions/79471500/github-actions-authentication-failed-for-pushing-to-repository"
+    label: "SO#79471500 — Authentication failed for pushing to repository"
+  - url: "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository"
+    label: "GitHub Docs: Setting GITHUB_TOKEN default permissions"