@htekdev/actions-debugger 1.0.124 → 1.0.126

package/errors/known-unsolved/known-unsolved-072.yml

@@ -0,0 +1,143 @@
+id: known-unsolved-072
+title: 'No parallel steps within a single job — all steps execute sequentially'
+category: known-unsolved
+severity: limitation
+tags:
+  - parallel-steps
+  - sequential
+  - performance
+  - job-structure
+  - limitation
+  - roadmap
+patterns:
+  - regex: 'parallel.*steps.*not.*support|steps.*run.*sequentially'
+    flags: 'i'
+error_messages:
+  - 'steps run sequentially — no native parallel step execution within a single job'
+root_cause: |
+  In GitHub Actions, all steps within a single job execute sequentially in the order they
+  are defined. There is no native syntax to declare that two or more steps within the same
+  job should run concurrently.
+
+  This means:
+  - A job that runs `npm install`, `eslint`, and `jest` must run them one after another,
+    even if `eslint` and `jest` are completely independent and could run simultaneously.
+  - A job that runs two independent API calls, file downloads, or build targets must wait
+    for each to complete before starting the next.
+  - The only way to achieve true parallelism in GitHub Actions is to split work across
+    multiple jobs with `needs:` dependencies — but this requires each job to set up its
+    own runner, check out the repository, restore caches, and install dependencies,
+    adding significant overhead for short tasks.
+
+  This is a long-standing community request. GitHub added it to the public roadmap as
+  "Parallel Steps in GitHub Actions" (github/roadmap#1191, GA milestone, 2025).
+
+  Common workarounds add latency (multiple jobs) or complexity (background processes).
+fix: |
+  There is no built-in fix. Workarounds:
+
+  1. Split parallel work into separate jobs using `needs:` and a matrix strategy.
+     Each job adds runner setup overhead (~15-30s), so this is most effective for
+     tasks that take minutes, not seconds.
+
+  2. Run steps as background shell processes and wait for them with `wait` (bash only).
+     This works for independent shell commands that don't need to write to GITHUB_OUTPUT,
+     GITHUB_ENV, or produce step outputs — those mechanisms are not safe for concurrent use.
+
+  3. Use `make -j N` or `./gradlew --parallel` or similar build-tool parallelism within
+     a single shell step. This parallelizes work inside one run: step without needing
+     multiple GitHub Actions steps.
+
+  4. Run a Docker Compose or docker run --detach to start background services, then
+     use a final step to check results.
+fix_code:
+  - language: yaml
+    label: 'Run independent checks in parallel via separate jobs (preferred for long tasks)'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: 22
+                cache: npm
+            - run: npm ci
+            - run: npm run lint
+
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: 22
+                cache: npm
+            - run: npm ci
+            - run: npm test
+
+        type-check:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: 22
+                cache: npm
+            - run: npm ci
+            - run: npm run typecheck
+
+        # Final gate job waits for all parallel checks
+        ci-complete:
+          needs: [lint, test, type-check]
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "All checks passed"
+
+  - language: bash
+    label: 'Background shell processes for independent shell commands (same job)'
+    code: |
+      # In a single run: step, launch parallel shell processes and wait for all
+      # WARNING: This pattern does not work with GITHUB_OUTPUT/GITHUB_ENV/GITHUB_STEP_SUMMARY
+      # from the background processes — race conditions corrupt the append-mode files.
+      # Use only for commands that write to their own output files.
+
+      ./fetch-data-source-1.sh > /tmp/source1.json &
+      PID1=$!
+
+      ./fetch-data-source-2.sh > /tmp/source2.json &
+      PID2=$!
+
+      wait $PID1 || { echo "Source 1 fetch failed"; exit 1; }
+      wait $PID2 || { echo "Source 2 fetch failed"; exit 1; }
+
+      echo "Both sources fetched in parallel"
+      ./merge-sources.py /tmp/source1.json /tmp/source2.json
+
+  - language: yaml
+    label: 'Use build tool parallelism inside a single step'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-java@v4
+              with:
+                java-version: 21
+                distribution: temurin
+            # Gradle parallel project execution — all subprojects build concurrently
+            - run: ./gradlew build --parallel --max-workers 4
+prevention:
+  - 'Design CI pipelines with parallel jobs from the start — split lint, test, and build into independent jobs to maximize parallelism today.'
+  - 'Use a shared cache with `actions/cache` to minimize the overhead of repeated `npm ci` / `pip install` across parallel jobs.'
+  - 'Track github/roadmap#1191 for the native parallel steps feature — once released, sequential-step bottlenecks can be eliminated without the multi-job overhead.'
+  - 'For build-tool tasks, always prefer build-native parallelism (`make -j`, `--parallel`, `cargo build --jobs`) over workflow-level workarounds.'
+docs:
+  - url: 'https://github.com/github/roadmap/issues/1191'
+    label: 'github/roadmap#1191 — Parallel Steps in GitHub Actions (GA milestone, open 2025)'
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps'
+    label: 'GitHub Docs — jobs.<job_id>.steps (sequential execution model)'
+  - url: 'https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs'
+    label: 'GitHub Docs — Using a matrix for parallel jobs as a workaround'

package/errors/known-unsolved/known-unsolved-073.yml

@@ -0,0 +1,172 @@
+id: known-unsolved-073
+title: '`timeout-minutes:` does not accept expressions — must be a literal integer; variables, inputs, and secrets are unsupported'
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout-minutes
+  - expressions
+  - limitation
+  - no-dynamic-value
+  - job-timeout
+  - step-timeout
+  - vars-context
+patterns:
+  - regex: 'timeout-minutes:\s*\$\{\{'
+    flags: 'i'
+  - regex: 'timeout-minutes.*vars\.|timeout-minutes.*inputs\.|timeout-minutes.*env\.'
+    flags: 'i'
+  - regex: 'Unexpected value.*timeout-minutes|timeout-minutes.*invalid'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml (Line: N, Col: M): Unexpected value 'true'"
+  - "timeout-minutes: unexpected value"
+  - "Expected Integer, String"
+root_cause: |
+  The `timeout-minutes:` field at both the **job level** and the **step level** only
+  accepts a **literal integer** (e.g., `30`, `120`). GitHub Actions does not evaluate
+  expressions (`${{ }}`) in this field.
+
+  Attempting to use any of the following will either produce a YAML validation error
+  or silently fall back to the default timeout (6 hours for jobs, unlimited for steps):
+
+  - `timeout-minutes: ${{ vars.JOB_TIMEOUT }}`      — variables context
+  - `timeout-minutes: ${{ inputs.timeout }}`         — inputs context
+  - `timeout-minutes: ${{ env.TIMEOUT_MINUTES }}`    — env context
+  - `timeout-minutes: ${{ 30 * 2 }}`                 — arithmetic expression
+  - `timeout-minutes: ${{ matrix.timeout }}`         — matrix value
+
+  This is a long-standing feature request (actions/runner#1242, opened 2021, 500+
+  reactions) with no official resolution as of June 2026. GitHub's position is that
+  expression support in `timeout-minutes:` is not currently planned.
+
+  actionlint (>=1.6.x) correctly flags `timeout-minutes: ${{ ... }}` as a type error:
+  "type of expression at 'timeout-minutes' must be number but found string type."
+  However, some older actionlint versions or CI linting setups may not catch this,
+  allowing the invalid value to reach production where it silently uses the default.
+
+  Common motivation for wanting dynamic timeouts:
+  - Different environments (staging vs production) need different timeouts.
+  - A reusable workflow caller wants to pass a timeout as an input.
+  - Matrix jobs with different test suites need proportional timeouts.
+  - Organizational policies want to set timeouts via repository variables.
+fix: |
+  There is no native fix — expressions in `timeout-minutes:` are not supported.
+
+  **Workaround 1 — Hardcode multiple job variants with `if:` conditions:**
+  Create separate job definitions for each timeout scenario, each with a hardcoded
+  `timeout-minutes:` and an `if:` condition that selects the appropriate one based
+  on the context. This is verbose but fully supported.
+
+  **Workaround 2 — Use a wrapper script with a timeout command:**
+  Instead of relying on job-level timeout, implement a timeout inside the step's run
+  script using the OS `timeout` command (Linux/macOS) or PowerShell's `Wait-Process`:
+  ```yaml
+  steps:
+    - name: Build with dynamic timeout
+      env:
+        BUILD_TIMEOUT: ${{ vars.BUILD_TIMEOUT_SECONDS || '1800' }}
+      run: timeout "$BUILD_TIMEOUT" ./build.sh
+  ```
+  This gives dynamic timeout behavior but does NOT release the runner immediately —
+  the job continues running (idle) after the script times out until the job-level
+  `timeout-minutes:` (hardcoded) fires.
+
+  **Workaround 3 — Hardcode a generous upper bound:**
+  Set `timeout-minutes:` to the maximum acceptable value for any scenario, and rely
+  on internal script logic to exit early when needed. Ensures the runner is eventually
+  released even in worst-case scenarios.
+
+  **Workaround 4 — For reusable workflows, hardcode per caller:**
+  If a reusable workflow needs caller-specified timeouts, duplicate the job definition
+  per timeout tier or create multiple reusable workflows with different timeouts.
+fix_code:
+  - language: yaml
+    label: 'Does NOT work — expression in timeout-minutes is not supported'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ vars.JOB_TIMEOUT_MINUTES }}   # ❌ Expression not supported
+          steps:
+            - run: ./build.sh
+
+      # Also does NOT work:
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ inputs.timeout || 30 }}        # ❌ inputs not supported here
+          steps:
+            - run: ./test.sh
+
+  - language: yaml
+    label: 'Workaround — use OS timeout command inside step for dynamic behavior'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 60    # ✅ Hardcoded upper bound (releases runner if script hangs)
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build with dynamic timeout from variable
+              env:
+                # Variable in seconds: default 1800 (30 min), override via repo var
+                BUILD_TIMEOUT: ${{ vars.BUILD_TIMEOUT_SECONDS || '1800' }}
+              run: timeout "$BUILD_TIMEOUT" ./build.sh
+              # The job-level 60-minute timeout catches runaway cases
+
+  - language: yaml
+    label: 'Workaround — conditional job variants for different timeout requirements'
+    code: |
+      jobs:
+        build-short:
+          if: ${{ github.event_name == 'pull_request' }}
+          runs-on: ubuntu-latest
+          timeout-minutes: 15    # ✅ Short timeout for PR checks
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh --quick
+
+        build-full:
+          if: ${{ github.ref == 'refs/heads/main' }}
+          runs-on: ubuntu-latest
+          timeout-minutes: 60    # ✅ Full timeout for main branch builds
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh --full
+
+  - language: yaml
+    label: 'Reusable workflow workaround — hardcode tiers, expose as separate workflows'
+    code: |
+      # .github/workflows/ci-fast.yml — for PRs
+      on:
+        workflow_call:
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          timeout-minutes: 15   # ✅ Fast tier
+          steps:
+            - run: ./ci.sh
+
+      # .github/workflows/ci-full.yml — for main branch
+      on:
+        workflow_call:
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          timeout-minutes: 60   # ✅ Full tier
+          steps:
+            - run: ./ci.sh
+
+prevention:
+  - 'Accept that `timeout-minutes:` requires a literal integer — design your timeouts with hardcoded values from the start.'
+  - 'Use actionlint in CI to catch `timeout-minutes: ${{ ... }}` during PR review before it reaches production.'
+  - 'Set `timeout-minutes:` to a safe upper bound to ensure runners are eventually released even when scripts hang.'
+  - 'Use step-level `run: timeout N command` for dynamic per-step timeouts without changing job-level `timeout-minutes:`.'
+  - 'Upvote actions/runner#1242 — expression support in timeout-minutes is a high-demand feature request.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Docs: Workflow syntax — jobs.<id>.timeout-minutes (literal integer only)'
+  - url: 'https://github.com/actions/runner/issues/1242'
+    label: 'actions/runner#1242: Support expressions in timeout-minutes (500+ reactions, open since 2021)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes'
+    label: 'GitHub Docs: Workflow syntax — jobs.<id>.steps[*].timeout-minutes'

package/errors/permissions-auth/permissions-auth-071.yml

@@ -0,0 +1,144 @@
+id: permissions-auth-071
+title: 'OIDC token not available in pull_request events from forks — id-token: write cannot be granted'
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - fork
+  - pull-request
+  - id-token
+  - attestation
+  - aws
+  - azure
+  - workload-identity
+patterns:
+  - regex: 'Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+    flags: 'i'
+  - regex: 'Could not fetch an OIDC token.*id-token.*write'
+    flags: 'i'
+  - regex: 'Error: Action failed with error: Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL'
+    flags: 'i'
+error_messages:
+  - 'Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+  - 'Could not fetch an OIDC token. Did you remember to add `id-token: write` to your workflow permissions?'
+  - 'Error: Action failed with error: Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+root_cause: |
+  GitHub Actions workflows triggered by `pull_request` events from forked repositories cannot
+  mint OIDC tokens, even when `id-token: write` is explicitly set in the workflow `permissions:` block.
+
+  The restriction is enforced by GitHub's security model for fork pull requests:
+  - Fork PRs run with the permissions of the fork, not the base repository.
+  - GitHub documentation states: "You can use the permissions key to add and remove read
+    permissions for forked repositories, but typically you can't grant write access."
+  - The `id-token: write` scope is a WRITE permission. The ACTIONS_ID_TOKEN_REQUEST_URL
+    environment variable is only set when the runtime has write-level token access.
+  - When the variable is absent, any action or toolkit call to `core.getIDToken()` fails with
+    "Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable".
+
+  This commonly impacts:
+  - Cloud provider OIDC authentication (AWS configure-aws-credentials, Azure login, GCP auth)
+  - actions/attest-build-provenance and actions/attest for build attestation on PRs
+  - Any action that relies on `@actions/core` `getIDToken()` for OIDC federation
+
+  The restriction exists to prevent malicious fork contributors from using OIDC tokens to
+  authenticate against production cloud accounts or push malicious artifacts.
+fix: |
+  Option 1 — Use `pull_request_target` instead of `pull_request` (CAUTION required).
+  `pull_request_target` runs in the context of the base repository and CAN mint OIDC tokens.
+  However, it executes in the base repo's context with full access to base repo secrets —
+  this is a significant security risk if the workflow checks out or executes fork code without
+  proper isolation. Read all security guides before using this trigger.
+
+  Option 2 — Split the workflow into two parts.
+  Use `pull_request` for the build/test phase (no OIDC). Use a separate workflow triggered
+  by `workflow_run` or manual approval to perform OIDC-protected operations (attestation, deploy)
+  after verifying the PR code is safe.
+
+  Option 3 — Use a GitHub App token with explicit repository permissions for operations
+  that do not strictly require OIDC (e.g., package publishing). This avoids the OIDC
+  restriction entirely.
+
+  Option 4 — Only run OIDC-dependent steps on `push` events to protected branches (post-merge),
+  not on `pull_request` events from forks. Guard OIDC steps with:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false
+fix_code:
+  - language: yaml
+    label: 'Guard OIDC steps — skip for fork PRs, run only for same-repo PRs or push'
+    code: |
+      jobs:
+        build-and-attest:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+            attestations: write
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build artifact
+              run: ./build.sh
+
+            # OIDC-dependent steps: skip if fork PR (id-token write not available)
+            - name: Attest build provenance
+              if: >
+                github.event_name != 'pull_request' ||
+                github.event.pull_request.head.repo.full_name == github.repository
+              uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: './dist/app'
+
+  - language: yaml
+    label: 'Split workflow: use workflow_run to run OIDC steps after fork PR merges'
+    code: |
+      # Workflow 1: runs on pull_request — builds and uploads artifact (no OIDC)
+      on:
+        pull_request:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: ./dist/
+
+      ---
+
+      # Workflow 2: runs after workflow 1 completes — performs OIDC operations
+      on:
+        workflow_run:
+          workflows: ['Build']
+          types: [completed]
+      jobs:
+        attest:
+          # Only runs on base-repo push events completing after a merge
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            attestations: write
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: './dist/app'
+prevention:
+  - 'Never assume `id-token: write` is sufficient — fork PRs override write permissions to read-only regardless of the workflow `permissions:` block.'
+  - 'Add an explicit `if:` guard on every OIDC-dependent step to skip it for fork PRs: `if: github.event.pull_request.head.repo.fork == false`.'
+  - 'Use `pull_request_target` only after thoroughly reading the security hardening guide — it runs in base repo context and is vulnerable to pwn requests if fork code is checked out.'
+  - 'For attestation workflows, run attestation as a post-merge step on `push` to the default branch, not on PRs from forks.'
+docs:
+  - url: 'https://github.com/actions/attest-build-provenance/issues/99'
+    label: 'actions/attest-build-provenance#99 — OIDC unavailable in fork PR workflows (open)'
+  - url: 'https://github.com/aws-actions/configure-aws-credentials/issues/373'
+    label: 'aws-actions/configure-aws-credentials#373 — OIDC fails for pull request from fork'
+  - 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 for forked repos'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-pull_request_target-safely'
+    label: 'GitHub Docs — Security hardening for pull_request_target'

package/errors/permissions-auth/permissions-auth-072.yml

@@ -0,0 +1,112 @@
+id: permissions-auth-072
+title: 'actions/labeler fails with "You do not have permission to create labels" — missing issues: write'
+category: permissions-auth
+severity: error
+tags:
+  - actions/labeler
+  - issues
+  - labels
+  - permissions
+  - issues-write
+  - GITHUB_TOKEN
+  - HttpError
+patterns:
+  - regex: 'You do not have permission to create labels on this repository'
+    flags: 'i'
+  - regex: 'HttpError.+do not have permission to create labels'
+    flags: 'i'
+  - regex: '"resource":"Repository","field":"label","code":"unauthorized"'
+    flags: 'i'
+error_messages:
+  - 'HttpError: You do not have permission to create labels on this repository.: {"resource":"Repository","field":"label","code":"unauthorized"}'
+  - 'Error: You do not have permission to create labels on this repository.'
+root_cause: |
+  `actions/labeler` requires the `issues: write` permission on the
+  `GITHUB_TOKEN` whenever it needs to **create** a label that does not yet
+  exist in the repository. The labeler's `create-labels: true` setting (or
+  its equivalent in older versions that auto-create missing labels) triggers a
+  `POST /repos/{owner}/{repo}/labels` API call.
+
+  In 2023+, GitHub tightened default token permissions. Repositories and
+  organizations that enable "Read repository contents and packages permissions"
+  as the default GITHUB_TOKEN permission, or workflows that explicitly
+  enumerate `permissions:` without including `issues: write`, will cause the
+  label-creation API call to return HTTP 403:
+
+    `HttpError: You do not have permission to create labels on this repository.`
+
+  Note: If all labels already exist in the repository, the action only calls
+  `GET /repos/{owner}/{repo}/labels` (read) and `POST .../issues/{number}/labels`
+  (adding a label to an issue/PR — also requires issues:write). In practice,
+  any labeling operation that modifies issues or creates labels needs this
+  permission. The error is especially confusing because it surfaces as an
+  `HttpError` that looks like a GitHub API error rather than a clear
+  "permission denied" message.
+fix: |
+  Add `issues: write` to the workflow or job permissions block:
+
+  ```yaml
+  permissions:
+    issues: write
+    pull-requests: write  # Also needed if labeling pull requests
+    contents: read
+  ```
+
+  If the repository uses the default broad permissions and the error occurs on
+  a fork PR (where fork PRs receive read-only tokens regardless of the
+  workflow's permissions block), add a guard:
+
+  ```yaml
+  if: github.event.pull_request.head.repo.full_name == github.repository
+  ```
+
+  to skip label creation on fork PRs where the token cannot be elevated.
+fix_code:
+  - language: yaml
+    label: 'Add issues: write permission to the labeler job'
+    code: |
+      name: Label PRs
+
+      on:
+        pull_request_target:
+          types: [opened, synchronize, reopened]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            issues: write       # Required to create new labels
+            pull-requests: write # Required to add labels to pull requests
+            contents: read
+          steps:
+            - uses: actions/labeler@v5
+              with:
+                repo-token: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: 'Skip labeler on fork PRs where token is always read-only'
+    code: |
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          # Skip on forks — their GITHUB_TOKEN is read-only regardless of permissions block
+          if: github.event.pull_request.head.repo.full_name == github.repository
+          permissions:
+            issues: write
+            pull-requests: write
+            contents: read
+          steps:
+            - uses: actions/labeler@v5
+              with:
+                repo-token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - 'Always include `issues: write` and `pull-requests: write` when using actions/labeler, even if the labeler config only applies existing labels — it still needs write to apply labels to PRs/issues.'
+  - 'Pre-create all labels defined in `.github/labeler.yml` in the repository settings so the action never needs to create them, reducing the permission surface needed (though issues:write is still needed for applying labels to issues/PRs).'
+  - 'When using `pull_request` trigger (not `pull_request_target`), fork PRs receive a read-only GITHUB_TOKEN by design; switch to `pull_request_target` or handle fork PRs with a separate read-only path.'
+  - 'Use the permissions checker in your CI review process: verify labeler workflows include explicit `permissions:` blocks before merging.'
+docs:
+  - url: 'https://github.com/actions/labeler/issues/870'
+    label: 'actions/labeler#870 — HttpError: You do not have permission to create labels on this repository'
+  - 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://github.com/actions/labeler#token'
+    label: 'actions/labeler — Token and permissions requirements'