@htekdev/actions-debugger 1.0.14 → 1.0.16

package/errors/known-unsolved/secrets-not-allowed-in-if-conditions.yml

@@ -0,0 +1,149 @@
+id: known-unsolved-016
+title: "secrets Context Cannot Be Directly Referenced in if: Conditions"
+category: known-unsolved
+severity: limitation
+tags:
+  - secrets
+  - if-condition
+  - conditional
+  - env
+  - limitation
+  - expressions
+  - step-condition
+patterns:
+  - regex: "if:.*\\$\\{\\{.*secrets\\..*\\}\\}"
+    flags: "i"
+  - regex: "secrets\\.[A-Z_a-z]+\\s*!=\\s*''"
+    flags: "i"
+error_messages:
+  - "This job was skipped."
+root_cause: |
+  GitHub Actions explicitly prohibits direct use of the `secrets` context in `if:`
+  conditional expressions at the job or step level. The platform blocks this as a
+  security measure to prevent secret values from being leaked through expression
+  evaluation in workflow logs.
+
+  Attempting `if: ${{ secrets.MY_SECRET != '' }}` or `if: secrets.MY_SECRET` silently
+  fails — the condition evaluates to an empty string (falsy), causing the step or job
+  to be skipped with no error message, warning, or explanation.
+
+  The same restriction applies at the job level:
+    ```yaml
+    jobs:
+      deploy:
+        if: ${{ secrets.DEPLOY_KEY != '' }}  # silently evaluates wrong
+    ```
+
+  This catches developers off guard because:
+  - The workflow is syntactically valid and passes YAML linting — no parse error
+  - The failure mode is silent: the job/step is skipped with "This job was skipped"
+    rather than an explicit error about the secrets restriction
+  - The pattern looks correct by analogy with other contexts (`github.*`, `env.*`,
+    `vars.*`) that DO work in `if:` conditions
+  - Secrets used in `run:` scripts and `with:` inputs work fine — only `if:` is blocked
+
+  GitHub's documentation explicitly states: "Secrets cannot be directly referenced
+  in `if:` conditionals. Instead, consider setting secrets as job-level environment
+  variables, then referencing the environment variables to conditionally run steps."
+
+  As of 2026 this is a by-design limitation with no planned native fix.
+  `actionlint` now flags direct secret references in `if:` expressions as an error.
+
+  Sources:
+  - GitHub Docs — Using secrets in GitHub Actions (use-secrets.md)
+  - github/docs#12722 — PR documenting the `if:` condition restriction
+fix: |
+  Promote the secret to a job-level `env:` variable that evaluates the boolean (not the
+  secret value itself), then reference `env.VARIABLE_NAME` in the `if:` condition.
+
+  For job-level `if:` (not step-level), use a preceding detection job that outputs
+  whether the secret is present, and condition the downstream job on that output.
+fix_code:
+  - language: yaml
+    label: "WRONG — direct secrets reference in step if: condition"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to production
+              if: ${{ secrets.DEPLOY_KEY != '' }}  # silently wrong — step is skipped
+              run: ./deploy.sh
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+
+  - language: yaml
+    label: "CORRECT — promote secret presence to job-level env, reference in step if:"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            # Safe: evaluates to "true"/"false" string — not the secret value itself
+            HAS_DEPLOY_KEY: ${{ secrets.DEPLOY_KEY != '' }}
+          steps:
+            - name: Deploy to production
+              if: env.HAS_DEPLOY_KEY == 'true'
+              run: ./deploy.sh
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+
+  - language: yaml
+    label: "CORRECT — job-level conditional via detection job + output"
+    code: |
+      jobs:
+        check-secrets:
+          runs-on: ubuntu-latest
+          outputs:
+            has_key: ${{ steps.check.outputs.has_key }}
+          steps:
+            - id: check
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+              run: |
+                if [ -n "$DEPLOY_KEY" ]; then
+                  echo "has_key=true" >> "$GITHUB_OUTPUT"
+                else
+                  echo "has_key=false" >> "$GITHUB_OUTPUT"
+                fi
+
+        deploy:
+          needs: check-secrets
+          # Job-level if: can reference job outputs — not secrets directly
+          if: needs.check-secrets.outputs.has_key == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+
+  - language: yaml
+    label: "CORRECT — inline env check using bash within step"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy (skip gracefully if secret absent)
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+              run: |
+                if [ -z "$DEPLOY_KEY" ]; then
+                  echo "No DEPLOY_KEY configured — skipping deployment"
+                  exit 0
+                fi
+                ./deploy.sh
+prevention:
+  - "Never reference `secrets.*` directly in `if:` conditions — always promote to `env:` first."
+  - "Use `env.HAS_SECRET: ${{ secrets.MY_SECRET != '' }}` at the job level to create a safe boolean env var."
+  - "Install and run `actionlint` in CI — it now flags direct secret references in `if:` as an error."
+  - "For job-level conditionals based on secret presence, use a dedicated detection job with outputs."
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#using-secrets-in-a-workflow"
+    label: "GitHub Docs: Using secrets in a workflow (secrets cannot be in if: conditionals)"
+  - url: "https://github.com/github/docs/pull/12722"
+    label: "github/docs#12722 — Document secrets in if: conditionals limitation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif"
+    label: "Workflow syntax: steps[*].if"
+  - url: "https://github.com/rhysd/actionlint"
+    label: "actionlint — flags direct secrets in if: conditions as an error"

package/errors/known-unsolved/workflow-50-rerun-limit.yml

@@ -0,0 +1,110 @@
+id: known-unsolved-018
+title: "Workflow rerun limit of 50 exceeded — subsequent reruns fail permanently"
+category: known-unsolved
+severity: limitation
+tags:
+  - rerun
+  - retry
+  - automation
+  - limits
+  - platform-limit
+patterns:
+  - regex: "exceeded.*maximum.*reruns|maximum.*reruns.*exceeded"
+    flags: "i"
+  - regex: "rerun limit.*50|50.*rerun limit"
+    flags: "i"
+  - regex: "This workflow run was cancelled because it exceeded"
+    flags: "i"
+error_messages:
+  - "This workflow run exceeded the limit of 50 reruns"
+  - "exceeded the maximum number of reruns (50)"
+  - "Cannot rerun this workflow: rerun limit reached"
+root_cause: |
+  Since April 10, 2026, GitHub Actions enforces a hard limit of 50 reruns
+  per individual workflow run (counting both full reruns and re-runs of
+  individual job subsets). Once a workflow run reaches 50 attempts, any
+  further rerun request — whether triggered manually, via the GitHub CLI,
+  the REST API, or an automated rerun action — will fail with an error
+  annotation on the check suite.
+
+  The limit was introduced to stop automation patterns that use infinite-retry
+  loops (e.g., rerunning every failed job automatically, retrying flaky
+  infrastructure hundreds of times) from adding excessive load to GitHub's
+  infrastructure. The count is tied to the original workflow run ID — creating
+  a new workflow run by re-pushing or re-dispatching does NOT inherit the
+  count.
+
+  This limitation is most frequently encountered by:
+  - Flaky test environments that rely on automated rerun tooling
+    (k1LoW/rerun-action, lewagon/retry-workflow-action, etc.)
+  - Long-running deployment pipelines with retry-until-success patterns
+  - Teams using merge queues or merge trains that auto-requeue failed checks
+  - Internal automation that retries status checks repeatedly against a PR
+
+  There is no way to exceed this limit — it is enforced server-side with no
+  configuration option. The only resolution is to trigger a fresh workflow run.
+fix: |
+  There is no way to raise or bypass the 50-rerun limit. Mitigation strategies:
+
+  1. Fix the underlying flakiness so retries are rare (<50 per workflow run).
+  2. Trigger a fresh workflow run rather than retrying the same run ID:
+     - Re-push to the branch or rebase (creates new push event → new run)
+     - For pull_request: close and reopen the PR (creates new run ID)
+     - For workflow_dispatch: dispatch again (creates a completely new run)
+  3. Redesign retry logic to use a separate `workflow_run` triggered workflow
+     that dispatches a NEW workflow instead of rerunning the same one.
+  4. For flaky infra: fix at the infra layer (idempotent step design, retry
+     at the shell/script level within a single attempt) rather than rerunning
+     the entire workflow.
+fix_code:
+  - language: yaml
+    label: "Use shell-level retry for flaky steps instead of workflow-level rerun"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Flaky deploy step with shell retry
+              run: |
+                # Retry up to 5 times with 30s backoff — no workflow rerun needed
+                for i in 1 2 3 4 5; do
+                  echo "Attempt $i..."
+                  ./scripts/deploy.sh && break || {
+                    if [ $i -lt 5 ]; then
+                      echo "Deploy failed, retrying in 30s..."
+                      sleep 30
+                    else
+                      echo "All $i attempts failed"
+                      exit 1
+                    fi
+                  }
+                done
+  - language: yaml
+    label: "Dispatch a new workflow run instead of rerunning the same run"
+    code: |
+      # If you need automated rerun logic, trigger a fresh dispatch
+      # rather than using gh run rerun (which increments the rerun counter)
+      jobs:
+        retry-via-dispatch:
+          runs-on: ubuntu-latest
+          if: failure()
+          steps:
+            - name: Trigger fresh run via workflow_dispatch
+              run: |
+                gh workflow run ci.yml \
+                  --ref ${{ github.ref }} \
+                  --field triggered_by=auto-retry
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Treat workflow reruns as a debugging tool, not a reliability mechanism — fix flakiness at the source"
+  - "Use shell-level retry loops (for loop with sleep) for individual steps that are inherently flaky"
+  - "Use workflow_dispatch to start a fresh run rather than rerunning the same run ID when automation needs to retry"
+  - "Monitor workflows that regularly exceed 5 reruns — they signal a deeper reliability problem that needs fixing"
+docs:
+  - url: "https://github.blog/changelog/2026-04-10-actions-workflows-are-limited-to-50-reruns/"
+    label: "GitHub Changelog — Actions workflows are limited to 50 reruns (Apr 2026)"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "GitHub Docs — Re-running workflows and jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Docs — workflow_dispatch event"

package/errors/permissions-auth/check-run-status-modification-blocked.yml

@@ -0,0 +1,134 @@
+id: permissions-auth-018
+title: "GITHUB_TOKEN cannot modify check run status or conclusion after March 2025"
+category: permissions-auth
+severity: error
+tags:
+  - check-runs
+  - github-token
+  - checks-api
+  - permissions
+  - breaking-change
+patterns:
+  - regex: "Check run status and conclusions can only be updated internally by GitHub Actions"
+    flags: "i"
+  - regex: "check_run.*status.*conclusion.*updated internally"
+    flags: "i"
+  - regex: "Changes to check run status modification"
+    flags: "i"
+error_messages:
+  - "Error: Check run status and conclusions can only be updated internally by GitHub Actions. Please see https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/#changes-to-check-run-status-modification"
+  - "Check run status and conclusions can only be updated internally by GitHub Actions"
+root_cause: |
+  GitHub deprecated external modification of check run status and conclusion
+  fields on March 31, 2025. Prior to this change, workflows and third-party
+  actions (e.g., LouisBrunner/checks-action, custom Checks API calls) could
+  use the repository's GITHUB_TOKEN to call the REST API and update the status
+  (queued, in_progress, completed) or conclusion (success, failure, etc.) of
+  an existing check run that was originally created by GitHub Actions.
+
+  GitHub blocked this pattern to prevent confusion and race conditions that
+  could arise when external code overwrote the status of a check run that
+  GitHub Actions was still managing. Starting March 31, 2025, any attempt
+  to PATCH an existing Actions-created check run's status or conclusion via
+  GITHUB_TOKEN returns an error.
+
+  This affects:
+  - Actions that wrap the GitHub Checks API to create multi-step annotations
+    (e.g., LouisBrunner/checks-action)
+  - Custom workflows that read a check_run ID from a prior step and patch it
+  - External tooling that patches check run state using the built-in token
+  - Any pattern where one step creates a check run and a later step or job
+    tries to set it to "completed"
+
+  Check runs that were NOT created by GitHub Actions (created via a GitHub App
+  or OAuth token) are not affected and can still be updated by their creator.
+fix: |
+  Workflows that need to update check run status or conclusion must create
+  those check runs with a non-GITHUB_TOKEN credential so that the same
+  credential can also update them later.
+
+  Option 1 (GitHub App): Use actions/create-github-app-token to generate an
+  installation token and create check runs with that token. The same GitHub App
+  token can then update the check runs it created.
+
+  Option 2 (Remove update steps): If the check run is only being updated to
+  mark it "completed" at the end of a job, let GitHub Actions manage the
+  conclusion automatically. Remove the final PATCH step.
+
+  Option 3 (Migrate to annotations): Replace custom check run status tracking
+  with GitHub Actions step annotations (::notice::, ::warning::, ::error::).
+  These use the workflow's built-in UI and require no Checks API calls.
+fix_code:
+  - language: yaml
+    label: "Create and update check runs using a GitHub App installation token"
+    code: |
+      jobs:
+        annotate:
+          runs-on: ubuntu-latest
+          permissions:
+            # id-token:write needed if using OIDC-based App token
+            contents: read
+          steps:
+            - name: Generate GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v2
+              with:
+                app-id: ${{ vars.CHECKS_APP_ID }}
+                private-key: ${{ secrets.CHECKS_APP_PRIVATE_KEY }}
+
+            - name: Create check run
+              id: create-check
+              uses: actions/github-script@v7
+              with:
+                github-token: ${{ steps.app-token.outputs.token }}
+                script: |
+                  const { data } = await github.rest.checks.create({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    name: 'My Custom Check',
+                    head_sha: context.sha,
+                    status: 'in_progress',
+                  });
+                  return data.id;
+
+            - name: Do work...
+              run: echo "running checks..."
+
+            - name: Update check run to completed
+              uses: actions/github-script@v7
+              with:
+                # Use the App token — NOT github.token — to update the check
+                github-token: ${{ steps.app-token.outputs.token }}
+                script: |
+                  await github.rest.checks.update({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    check_run_id: ${{ steps.create-check.outputs.result }},
+                    status: 'completed',
+                    conclusion: 'success',
+                  });
+  - language: yaml
+    label: "Use built-in step annotations instead of custom check runs"
+    code: |
+      - name: Emit warning annotation
+        run: echo "::warning file=src/main.js,line=42::Deprecated API usage detected"
+
+      - name: Emit error annotation (fails step)
+        run: echo "::error title=Lint Failed::3 lint violations found in src/"
+
+      # These annotations appear in the workflow summary and PR checks UI
+      # without any Checks API calls or external tokens
+prevention:
+  - "Never use GITHUB_TOKEN to PATCH the status or conclusion of an Actions-created check run"
+  - "Create custom check runs using a GitHub App installation token so the same credential owns them end-to-end"
+  - "Prefer built-in step annotations (::warning::, ::error::) over custom Checks API calls for simple annotation needs"
+  - "Audit third-party actions that wrap the Checks API (e.g., LouisBrunner/checks-action) for compatibility with the March 2025 change"
+docs:
+  - url: "https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/#changes-to-check-run-status-modification"
+    label: "GitHub Changelog — Changes to check run status modification (Feb 2025)"
+  - url: "https://docs.github.com/en/rest/checks/runs"
+    label: "GitHub REST API — Check Runs"
+  - url: "https://github.com/LouisBrunner/checks-action/issues/369"
+    label: "LouisBrunner/checks-action#369 — Error after March 2025 enforcement"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-warning-message"
+    label: "GitHub Docs — Workflow commands for annotations"

package/errors/permissions-auth/dependabot-pr-secrets-unavailable.yml

@@ -0,0 +1,133 @@
+id: permissions-auth-013
+title: "Dependabot Pull Requests Cannot Access Repository Secrets — Read-Only Token"
+category: permissions-auth
+severity: silent-failure
+tags:
+  - dependabot
+  - secrets
+  - github-token
+  - pull-request
+  - read-only
+patterns:
+  - regex: "Context access might be invalid: secrets\\."
+    flags: "i"
+  - regex: "denied|forbidden|403"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "Context access might be invalid: secrets.NPM_TOKEN"
+  - "Error: Process completed with exit code 1."
+  - "HttpError: Resource not accessible by integration"
+root_cause: |
+  For security reasons, GitHub Actions workflows triggered by Dependabot pull requests
+  are granted a **read-only GITHUB_TOKEN** and **cannot access repository secrets**.
+
+  When a Dependabot PR triggers an `on: pull_request` workflow:
+  - `secrets.*` expressions evaluate to empty string (not an error — silently empty)
+  - `GITHUB_TOKEN` has read-only permissions (cannot write to the repository, push
+    tags, create releases, comment on PRs, etc.)
+  - Steps that need secrets (publishing to npm, Docker Hub, PyPI, etc.) fail with
+    authentication errors or silently produce wrong results
+
+  This is intentional: Dependabot opens PRs that update dependencies from external
+  sources. If Dependabot-triggered workflows had full secret access, a malicious
+  package update could exfiltrate your credentials via a modified build step.
+
+  The failure is often silent because:
+  - The secret evaluates to empty string — tools may fail with "missing credentials"
+    rather than a clear "secret unavailable" error
+  - `GITHUB_TOKEN` write failures show as 403 "Resource not accessible by integration"
+
+  Sources: dependabot/dependabot-core#3253, #5464
+fix: |
+  Choose one of these approaches depending on your security requirements:
+
+  **Option 1 (Recommended): Use Dependabot secrets**
+  Add the required secrets to the Dependabot secrets store (Settings > Secrets and
+  variables > Dependabot). Dependabot-triggered workflows can access these separately
+  from repository secrets.
+
+  **Option 2: Auto-approve and merge without secrets**
+  For dependency updates, use `pull_request_review` + `pull_request` auto-merge
+  pattern — approve Dependabot PRs that pass CI without needing secrets.
+
+  **Option 3: Use `pull_request_target` with caution**
+  `pull_request_target` runs in the base repo context and has full secret access.
+  Only use this for trusted, controlled steps (like leaving a comment) — never
+  checkout and run untrusted fork code in a `pull_request_target` step with secrets.
+
+  **Option 4: Filter out Dependabot runs**
+  Add `if: github.actor != 'dependabot[bot]'` to skip secret-requiring steps for
+  Dependabot PRs, letting CI pass without the publishing step.
+fix_code:
+  - language: yaml
+    label: "Add secrets to Dependabot secrets store (Settings → Secrets → Dependabot)"
+    code: |
+      # Add NPM_TOKEN (and any other required secrets) to:
+      # Settings > Secrets and variables > Dependabot
+      # These are separate from repository secrets and accessible to Dependabot runs.
+
+      # No workflow change needed — ${{ secrets.NPM_TOKEN }} will resolve correctly
+      # once the secret is added to the Dependabot secrets store.
+  - language: yaml
+    label: "Skip secret-requiring steps for Dependabot PRs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests
+              run: npm test
+              # Tests run for all PRs including Dependabot
+
+            - name: Publish to npm (skip for Dependabot)
+              if: github.actor != 'dependabot[bot]'
+              run: npm publish
+              env:
+                NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+              # NPM_TOKEN is empty for Dependabot — skip the step entirely
+  - language: yaml
+    label: "Auto-approve Dependabot PRs using Dependabot secrets + gh CLI"
+    code: |
+      name: Auto-approve Dependabot
+      on: pull_request
+
+      permissions:
+        pull-requests: write
+        contents: write
+
+      jobs:
+        auto-approve:
+          runs-on: ubuntu-latest
+          if: github.actor == 'dependabot[bot]'
+          steps:
+            - name: Fetch Dependabot metadata
+              id: meta
+              uses: dependabot/fetch-metadata@v2
+
+            - name: Auto-approve minor and patch updates
+              if: steps.meta.outputs.update-type != 'version-update:semver-major'
+              run: gh pr review --approve "$PR_URL"
+              env:
+                PR_URL: ${{ github.event.pull_request.html_url }}
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+                # GITHUB_TOKEN in dependabot context is read-only for repo content
+                # but CAN approve PRs when permissions: pull-requests: write is set
+prevention:
+  - "Never assume repository secrets are available in Dependabot-triggered workflows — they aren't."
+  - "Use `github.actor == 'dependabot[bot]'` conditions to branch logic for Dependabot vs human PRs."
+  - "Add required secrets to the Dependabot secrets store separately from repository secrets."
+  - "Audit CI workflows for `${{ secrets.* }}` usage and test with a Dependabot PR to confirm behavior."
+  - "Do not use `pull_request_target` with `actions/checkout` on the PR head ref — this is a security vulnerability."
+docs:
+  - url: "https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions"
+    label: "Automating Dependabot with GitHub Actions"
+  - url: "https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot"
+    label: "Configuring Dependabot secrets"
+  - url: "https://github.com/dependabot/dependabot-core/issues/3253"
+    label: "dependabot-core#3253 — secrets unavailable in Dependabot-triggered workflows"
+  - url: "https://github.com/dependabot/dependabot-core/issues/5464"
+    label: "dependabot-core#5464 — Dependabot read-only token behavior"

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"