@htekdev/actions-debugger 1.0.124 → 1.0.126

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

@@ -0,0 +1,127 @@
+id: permissions-auth-073
+title: 'GraphQL "refusing to allow a GitHub App to create or update workflow without `workflows` permission" — misleading error, actual fix is actions: write or App workflow scope'
+category: permissions-auth
+severity: error
+tags:
+  - GitHub-App
+  - workflows
+  - actions-write
+  - GraphQL
+  - pull-request
+  - misleading-error
+  - OAuth-scope
+  - enablePullRequestAutoMerge
+patterns:
+  - regex: "refusing to allow a GitHub App to create or update workflow .+ without .workflows. permission"
+    flags: 'i'
+  - regex: 'GraphQL.+Pull request.+workflow.+without.+workflows.*permission'
+    flags: 'i'
+error_messages:
+  - "GraphQL: Pull request refusing to allow a GitHub App to create or update workflow `.github/workflows/release.yml` without `workflows` permission (enablePullRequestAutoMerge)"
+  - "refusing to allow a GitHub App to create or update workflow `.github/workflows/ci.yml` without `workflows` permission"
+root_cause: |
+  When a GitHub App or the `GITHUB_TOKEN` attempts to enable auto-merge,
+  create a pull request that modifies workflow files, or perform certain
+  pull-request GraphQL mutations (`enablePullRequestAutoMerge`,
+  `createPullRequest`, etc.) on a branch that touches `.github/workflows/`,
+  GitHub's API returns a misleading error:
+
+    `GraphQL: Pull request refusing to allow a GitHub App to create or update
+     workflow '...' without 'workflows' permission`
+
+  The error message references `workflows` as if it were a value you can set
+  in the `permissions:` block of a GitHub Actions workflow. **It is not.**
+  The word `workflows` here refers to the **GitHub App OAuth scope** (which
+  grants the App permission to edit workflow files), not the `actions: write`
+  or any standard GITHUB_TOKEN permission key.
+
+  There are two distinct situations that produce this error:
+
+  1. **GitHub App missing the Workflows permission:** If your GitHub App does
+     not have the "Workflows" repository permission (a GitHub App installation
+     permission distinct from all the `permissions:` block keys), any operation
+     that modifies `.github/workflows/` through the App will be rejected with
+     this message.
+
+  2. **GITHUB_TOKEN used for auto-merge enabling on workflow-touching PRs:**
+     When a workflow uses `gh pr merge --auto` (or the GraphQL
+     `enablePullRequestAutoMerge` mutation) on a PR that modifies workflow
+     files, the GITHUB_TOKEN may lack the necessary scope even with
+     `contents: write`, because enabling auto-merge on workflow-modifying PRs
+     requires the workflows OAuth scope which GITHUB_TOKEN cannot hold.
+
+  The error message's reference to `workflows` is confusing because it is not
+  a recognized key in the YAML `permissions:` block. Developers who try to
+  add `permissions: workflows: write` get a YAML validation error ("Unknown
+  property 'workflows'"), leading to frustration when neither the permissions
+  block nor the token can be directly granted this scope.
+fix: |
+  **For GitHub Apps:**
+  Go to your GitHub App's settings → Permissions & events → Repository
+  permissions → and enable **"Workflows" permission** (set to Read & Write).
+  Then re-install the app on the repository/organization so the new permission
+  takes effect.
+
+  **For GITHUB_TOKEN on auto-merge of workflow-touching PRs:**
+  The GITHUB_TOKEN cannot hold the `workflows` OAuth scope. You must use a
+  Personal Access Token (classic, with the `workflow` scope) or a GitHub App
+  with the Workflows permission. Store either as a repository secret and use it
+  instead of `GITHUB_TOKEN` for the auto-merge step:
+
+  ```yaml
+  - name: Enable auto-merge
+    env:
+      GH_TOKEN: ${{ secrets.MY_PAT_WITH_WORKFLOW_SCOPE }}
+    run: gh pr merge --auto --squash ${{ github.event.pull_request.number }}
+  ```
+
+  **For `actions: write` confusion:**
+  Adding `actions: write` to the `permissions:` block does NOT fix this error.
+  `actions: write` governs artifacts, caches, and workflow runs — NOT the
+  ability to create or modify workflow files.
+fix_code:
+  - language: yaml
+    label: 'Use a PAT with the workflow scope instead of GITHUB_TOKEN for auto-merge on workflow-touching PRs'
+    code: |
+      jobs:
+        auto-merge:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Enable auto-merge
+              # GITHUB_TOKEN cannot hold the 'workflow' OAuth scope.
+              # Use a PAT (classic) with the 'workflow' scope stored as a secret.
+              env:
+                GH_TOKEN: ${{ secrets.PAT_WITH_WORKFLOW_SCOPE }}
+              run: |
+                gh pr merge --auto --squash "${{ github.event.pull_request.number }}"
+  - language: yaml
+    label: 'Use create-github-app-token with Workflows permission to create PRs that modify workflows'
+    code: |
+      jobs:
+        create-update-pr:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate App token (App must have Workflows read+write permission)
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.MY_APP_ID }}
+                private-key: ${{ secrets.MY_APP_PRIVATE_KEY }}
+
+            - name: Create PR modifying a workflow file
+              env:
+                GH_TOKEN: ${{ steps.app-token.outputs.token }}
+              run: |
+                gh pr create --title "Update workflow" --body "..." --base main
+prevention:
+  - 'When your GitHub App or automation needs to create PRs that touch `.github/workflows/`, verify the App installation has the "Workflows" repository permission enabled (App settings → Permissions → Workflows: Read & Write).'
+  - 'Do NOT attempt `permissions: workflows: write` in your workflow YAML — "workflows" is not a valid permission key and will cause a YAML validation error; it is an App-level OAuth scope, not a token permission.'
+  - 'For auto-merge automation on PRs that may modify workflow files, use a classic PAT with the `workflow` scope or a GitHub App with Workflows permission rather than GITHUB_TOKEN.'
+  - 'When debugging this error, the key question is: "Does the token/App have the `workflows` OAuth scope?" — not "Does the job have the right permissions: block?"'
+docs:
+  - url: 'https://github.com/cli/cli/issues/11493'
+    label: 'cli/cli#11493 — Misleading GraphQL error: "without workflows permission" when using enablePullRequestAutoMerge'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app'
+    label: 'GitHub Docs — Choosing permissions for a GitHub App (Workflows permission)'
+  - url: 'https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens'
+    label: 'GitHub Docs — Classic PAT workflow scope for modifying workflow files'

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

@@ -0,0 +1,106 @@
+id: permissions-auth-074
+title: 'Composer leaks new-format GITHUB_TOKEN (ghs_APPID_JWT) to stderr in CI logs — CVE-2026-45793 / GHSA-f9f8-rm49-7jv2'
+category: permissions-auth
+severity: error
+tags:
+  - composer
+  - GITHUB_TOKEN
+  - token-disclosure
+  - ghs-token
+  - php
+  - setup-php
+  - CVE-2026-45793
+  - security
+  - token-format-rollout
+patterns:
+  - regex: 'Your github oauth token for .+ contains invalid characters'
+    flags: 'i'
+  - regex: 'UnexpectedValueException.+github oauth token.+invalid characters'
+    flags: 'i'
+  - regex: 'contains invalid characters: "ghs_'
+    flags: 'i'
+error_messages:
+  - 'Your github oauth token for github.com contains invalid characters: "ghs_AppID_eyJhbGc..."'
+  - '[InvalidArgumentException] Your github oauth token for github.com contains invalid characters: "ghs_..."'
+root_cause: |
+  Starting April 27, 2026, GitHub began rolling out a new stateless token format for
+  GITHUB_TOKEN and GitHub App installation tokens. The new format is `ghs_<AppID>_<JWT>`,
+  approximately 520 characters long, and uses base64url encoding which includes hyphens (`-`)
+  and underscores.
+
+  Composer versions >=2.3.0 <2.9.8 (and >=1.0 <1.10.28, >=2.0.0 <2.2.28) validate GitHub OAuth
+  tokens with the regex `^[.A-Za-z0-9_]+$`. This regex does not permit hyphens. The new
+  `ghs_APPID_JWT` token format routinely contains hyphens (base64url RFC 4648 §5 uses `-` and `_`
+  as URL-safe replacements for `+` and `/`).
+
+  When the token fails this validation, Composer throws an `UnexpectedValueException` that
+  interpolates the raw token verbatim into the error message:
+
+    `Your github oauth token for github.com contains invalid characters: "ghs_<full-token>"`
+
+  Symfony Console then prints this exception to stderr. GitHub Actions' built-in secret masker
+  matches registered values as exact substrings, but Symfony Console may wrap the message, embed
+  it in framing text (`In BaseIO.php line N:`), or interleave ANSI control sequences. As a result,
+  the masker does not redact the token, and the plaintext credential reaches the CI log.
+
+  This affects any PHP workflow that uses Composer with GITHUB_TOKEN registered as a GitHub OAuth
+  credential. Many widely-used Actions — including `shivammathur/setup-php` — automatically
+  register `GITHUB_TOKEN` into Composer's global `auth.json`, so the leak triggers without
+  any explicit user configuration.
+
+  CVSS score: 7.5 (High). CVE-2026-45793 / GHSA-f9f8-rm49-7jv2.
+fix: |
+  **Primary fix: Upgrade Composer to a patched version.**
+  - Composer 2.x (mainline): upgrade to >=2.9.8
+  - Composer 2.2.x (LTS): upgrade to >=2.2.28
+  - Composer 1.x: upgrade to >=1.10.28
+
+  The patched versions update the token validation regex to accept hyphens, preventing the
+  disclosure.
+
+  **Secondary workaround (if upgrading is not immediately possible):**
+  Explicitly unset the GitHub token from Composer's auth config before running Composer, then
+  set it via a token-safe mechanism, or use a classic `ghp_` PAT which uses the old format
+  unaffected by this regression:
+
+  ```yaml
+  - name: Remove GITHUB_TOKEN from Composer auth (workaround)
+    run: composer config --global --unset github-oauth.github.com
+  ```
+
+  **If using `shivammathur/setup-php`:** The action pins a Composer version; ensure you're on
+  a version that ships Composer >=2.9.8.
+fix_code:
+  - language: yaml
+    label: 'Pin Composer to patched version in GitHub Actions workflow'
+    code: |
+      - name: Install dependencies
+        run: |
+          # Ensure Composer is on a patched version before running install.
+          # Composer 2.9.8+ fixes CVE-2026-45793 (GITHUB_TOKEN disclosure with new ghs_ format)
+          composer self-update --2 2.9.8
+          composer install --no-interaction --prefer-dist
+  - language: yaml
+    label: 'Use shivammathur/setup-php with Composer version pinned to patched release'
+    code: |
+      - name: Set up PHP and Composer
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          tools: composer:2.9.8  # Pin to patched version fixing CVE-2026-45793
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - 'Always pin Composer to a specific patched version in CI (e.g., `composer:2.9.8` in setup-php tools). Do not rely on "latest" which may ship a vulnerable version during the rollout window.'
+  - 'Audit your workflow logs for lines matching `contains invalid characters` — these indicate a credential has been disclosed to the log.'
+  - 'Be aware that `shivammathur/setup-php` auto-registers `GITHUB_TOKEN` into Composer auth by default; upgrading to a patched Composer is the only reliable mitigation.'
+  - 'For repositories that do not need Composer to make authenticated GitHub API calls, you can disable auto-registration: `COMPOSER_AUTH: ''{}''` in the env block prevents auto-injection.'
+docs:
+  - url: 'https://github.com/advisories/GHSA-f9f8-rm49-7jv2'
+    label: 'GHSA-f9f8-rm49-7jv2 — Composer leaks GITHUB_TOKEN in CI logs (CVE-2026-45793)'
+  - url: 'https://github.com/composer/composer/security/advisories/GHSA-f9f8-rm49-7jv2'
+    label: 'composer/composer security advisory — GHSA-f9f8-rm49-7jv2 details and affected versions'
+  - url: 'https://github.blog/changelog/2026-04-24-notice-about-upcoming-new-format-for-github-app-installation-tokens/'
+    label: 'GitHub Changelog — Notice about new format for GitHub App installation tokens (April 2026)'
+  - url: 'https://github.com/composer/composer/issues/12849'
+    label: 'composer/composer#12849 — New format for GitHub Tokens (upstream issue report)'

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

@@ -0,0 +1,137 @@
+id: permissions-auth-075
+title: 'OIDC token missing `repository_custom_property_*` claim — custom property must be defined at org level, not just repo level'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - OIDC
+  - custom-properties
+  - trust-policy
+  - AWS
+  - Azure
+  - claim-missing
+  - org-level
+  - AccessDenied
+  - cloud-auth
+patterns:
+  - regex: 'repository_custom_property'
+    flags: 'i'
+  - regex: '(?:AccessDenied|is not authorized).+sts:AssumeRoleWithWebIdentity'
+    flags: 'i'
+  - regex: 'OpenIDConnectTokenVerificationFailed|sub.*claim.*condition.*failed|conditions.*not.*met'
+    flags: 'i'
+error_messages:
+  - 'Error: User: arn:aws:sts::ACCOUNT:assumed-role/... is not authorized to perform: sts:AssumeRoleWithWebIdentity'
+  - 'Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity'
+  - 'ClientAssertionCredential authentication failed: AADSTS70021'
+  - 'Error: No federated identity credential with issuer https://token.actions.githubusercontent.com matches'
+root_cause: |
+  GitHub Actions OIDC tokens gained support for `repository_custom_property_*` claims in
+  March 2026 (GA April 2, 2026 changelog). These claims allow trust policies on AWS, Azure,
+  and other cloud providers to filter access based on how a repository is classified within
+  an organization (e.g., `repository_custom_property_environment: production`).
+
+  However, there is a critical prerequisite that is not prominently documented:
+  **custom property definitions must be created at the organization level** — not just at the
+  repository level — for the corresponding claims to appear in OIDC tokens.
+
+  Specifically:
+  1. The custom property must be defined in the organization's custom properties schema
+     (Settings → Custom properties at the org level).
+  2. The property must be set/assigned a value for the repository in question.
+
+  When a property is created only at the **repository level** (via repo-specific custom
+  properties without an org-level schema entry), or when the property exists at the org
+  level but has no value set for the specific repository, the `repository_custom_property_*`
+  claim is simply **absent** from the OIDC token rather than being set to null or an empty
+  string.
+
+  Trust policies that include a condition requiring a specific `repository_custom_property_*`
+  claim evaluate to no-match and deny authentication. The cloud provider returns a generic
+  `AccessDenied` / `is not authorized` error with no indication that the claim is missing.
+  The workflow author sees a cloud authentication failure with no clear link to the OIDC
+  token contents.
+
+  This is a silent configuration error: the workflow appears to run normally until the
+  authentication step fails, and there is no warning during workflow setup or YAML validation
+  that the property is misconfigured.
+fix: |
+  **Step 1: Verify the OIDC token contents.**
+  Add a debug step to print the OIDC token claims before the cloud auth step:
+
+  ```yaml
+  - name: Debug OIDC claims
+    run: |
+      TOKEN=$(curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+        "$ACTIONS_ID_TOKEN_REQUEST_URL" | jq -r '.value')
+      echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .
+  ```
+
+  If `repository_custom_property_*` claims are absent, the property is not defined at the
+  org level or has no value for this repository.
+
+  **Step 2: Define the custom property at the organization level.**
+  Navigate to the GitHub organization → Settings → Custom properties and create the property
+  definition there. Repository-level-only properties do NOT produce OIDC claims.
+
+  **Step 3: Assign a value to the property for the target repository.**
+  After creating the org-level property definition, explicitly set the value for each
+  repository that needs the claim by going to the repository's Settings → Custom properties
+  or using the REST API.
+
+  **If you cannot use org-level properties:** Fall back to other OIDC sub-claim conditions
+  such as `repository`, `ref`, `environment`, or `job_workflow_ref` which are always present
+  in Actions OIDC tokens.
+fix_code:
+  - language: yaml
+    label: 'Add OIDC debug step to inspect claims before cloud auth'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - name: Debug OIDC token claims (remove after debugging)
+              run: |
+                TOKEN=$(curl -sS \
+                  -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+                  "$ACTIONS_ID_TOKEN_REQUEST_URL" | jq -r '.value')
+                # Print decoded payload (base64url decode the second segment)
+                echo "$TOKEN" | cut -d. -f2 | \
+                  python3 -c "import sys,base64,json; data=sys.stdin.read().strip(); \
+                    padded=data+'=='*((-len(data))%4); \
+                    print(json.dumps(json.loads(base64.urlsafe_b64decode(padded)), indent=2))"
+
+            - name: Configure AWS credentials via OIDC
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::ACCOUNT:role/my-role
+                aws-region: us-east-1
+  - language: yaml
+    label: 'AWS trust policy condition using repository_custom_property_* (requires org-level property)'
+    code: |
+      # AWS IAM trust policy condition requiring a custom property claim.
+      # PREREQUISITE: The property must be defined at org level AND set on the repository.
+      # If the claim is absent, AWS returns AccessDenied with no indication of missing claim.
+      {
+        "Condition": {
+          "StringEquals": {
+            "token.actions.githubusercontent.com:repository_custom_property_environment": "production"
+          }
+        }
+      }
+prevention:
+  - 'Always create custom property definitions at the **organization level** (Org Settings → Custom properties), not just at the repository level. Repo-level-only properties do NOT appear in OIDC tokens.'
+  - 'After creating an org-level property, explicitly set a value for each target repository. A property defined but not assigned a value for a repo is also absent from the OIDC token.'
+  - 'Before deploying trust policies that use `repository_custom_property_*` conditions, verify the claim is present in the OIDC token by printing decoded token claims in a debug step.'
+  - 'When trust policy conditions reference `repository_custom_property_*`, always have a fallback monitoring alert for `AccessDenied` / `is not authorized` errors to catch misconfigured or unset properties quickly.'
+docs:
+  - url: 'https://github.com/github/docs/issues/43779'
+    label: 'github/docs#43779 — custom properties docs gap: org-level definition required for OIDC claims'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#defining-trust-conditions-on-cloud-roles-using-oidc-claims'
+    label: 'GitHub Docs — About security hardening with OIDC: defining trust conditions using claims'
+  - url: 'https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/'
+    label: 'GitHub Changelog — April 2026: Actions OIDC tokens now support repository custom properties'
+  - url: 'https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization'
+    label: 'GitHub Docs — Managing custom properties for repositories in your organization'

package/errors/runner-environment/runner-environment-227.yml

@@ -0,0 +1,106 @@
+id: runner-environment-227
+title: 'Bash script handler unquoted path breaks job hooks and run steps in directories with spaces'
+category: runner-environment
+severity: error
+tags:
+  - bash
+  - hooks
+  - spaces
+  - path
+  - job-hooks
+  - self-hosted
+  - script-handler
+patterns:
+  - regex: 'bash: .+: No such file or directory'
+    flags: 'i'
+  - regex: 'ACTIONS_RUNNER_HOOK_JOB_STARTED.+No such file'
+    flags: 'i'
+  - regex: 'bash.*--noprofile.*--norc.*-e.*-o pipefail'
+    flags: 'i'
+error_messages:
+  - 'bash: /Volumes/My: No such file or directory'
+  - 'bash: Shared Files/hook.sh: No such file or directory'
+  - 'Error: Process completed with exit code 127.'
+root_cause: |
+  In the GitHub Actions runner source code, the default argument template for the bash
+  shell handler (`ScriptHandlerHelpers.cs`) does not quote the script path placeholder:
+
+    _defaultArguments["bash"] = "--noprofile --norc -e -o pipefail {0}";
+
+  When `{0}` is replaced with a path containing spaces — such as
+  `/Volumes/My Shared Files/hook.sh` — the resulting command becomes:
+
+    bash --noprofile --norc -e -o pipefail /Volumes/My Shared Files/hook.sh
+
+  Bash treats this as three separate arguments: `/Volumes/My`, `Shared`, and
+  `Files/hook.sh`. The first token is not a valid path, so bash exits with
+  "No such file or directory" and exit code 127.
+
+  By contrast, the PowerShell and cmd templates DO quote the path:
+    _defaultArguments["pwsh"]       = "-command \"& '{0}'\"";
+    _defaultArguments["powershell"] = "-command \". '{0}'\"";
+    _defaultArguments["cmd"]        = "/D /E:ON /V:OFF /S /C \"CALL \"{0}\"\"";
+
+  Only bash and sh are affected. The affected scenarios include:
+  - Job hooks (ACTIONS_RUNNER_HOOK_JOB_STARTED, ACTIONS_RUNNER_HOOK_JOB_COMPLETED)
+    when the hook script resides in a directory whose path contains spaces — a common
+    case on macOS with Tart VMs that mount shared directories at
+    `/Volumes/My Shared Files/`.
+  - `run:` steps where the runner's _work directory path contains spaces (less common
+    but possible on custom self-hosted runner installations).
+
+  The bug affects all released runner versions (no version introduced it — the
+  template has always been unquoted). A fix was proposed in the issue but had not
+  shipped as of the issue filing date.
+fix: |
+  Workaround: avoid spaces in the path to hook scripts and runner working directories.
+
+  1. Move hook scripts to a path with no spaces (e.g., `/opt/runner-hooks/hook.sh`
+     instead of `/Volumes/My Shared Files/hooks/hook.sh`).
+     Set ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner-hooks/job-started.sh in the
+     runner environment (`.env` file or system environment).
+
+  2. On macOS with Tart VMs, use a symlink from a space-free path to the shared
+     volume's hook script:
+       ln -s "/Volumes/My Shared Files/hook.sh" /opt/hooks/job-started.sh
+     Set the env var to the symlink path.
+
+  3. Wrap the script invocation in a no-space wrapper script that calls the real path.
+
+  There is no supported way to override the bash argument template at the user level.
+  The permanent fix requires a runner source code change (quoting `{0}`).
+fix_code:
+  - language: bash
+    label: 'Create a space-free symlink to the actual hook script'
+    code: |
+      # On macOS: create a symlink from a no-space path to the hook in the shared volume
+      mkdir -p /opt/runner-hooks
+      ln -sf "/Volumes/My Shared Files/hooks/job-started.sh" /opt/runner-hooks/job-started.sh
+      ln -sf "/Volumes/My Shared Files/hooks/job-completed.sh" /opt/runner-hooks/job-completed.sh
+
+      # In the runner's .env file (located in the runner install directory):
+      # ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner-hooks/job-started.sh
+      # ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/opt/runner-hooks/job-completed.sh
+
+  - language: bash
+    label: 'Move hook scripts to a space-free directory at runner setup time'
+    code: |
+      # Preferred: install hook scripts in a path with no spaces from the start
+      sudo mkdir -p /usr/local/runner-hooks
+      sudo cp ./hooks/job-started.sh /usr/local/runner-hooks/
+      sudo chmod +x /usr/local/runner-hooks/job-started.sh
+
+      # In .env:
+      # ACTIONS_RUNNER_HOOK_JOB_STARTED=/usr/local/runner-hooks/job-started.sh
+prevention:
+  - 'Always install runner hook scripts under paths with no spaces — use /opt/, /usr/local/, or /home/<user>/ prefixes.'
+  - 'On macOS Tart VM hosts, avoid mounting shared directories with spaces in the volume name; use snake_case or hyphenated names (e.g., My_Shared_Files).'
+  - 'After configuring ACTIONS_RUNNER_HOOK_JOB_STARTED, test the hook manually by running bash --noprofile --norc -e -o pipefail <path> to catch path issues before the runner is live.'
+  - 'If the runner work directory path contains spaces, reconfigure the runner with a clean no-space _work path.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4404'
+    label: 'actions/runner#4404 — Bash script handler does not quote the script path'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job'
+    label: 'GitHub Docs — Running scripts before or after a job (job hooks)'
+  - url: 'https://github.com/actions/runner/blob/main/src/Runner.Worker/Handlers/ScriptHandlerHelpers.cs'
+    label: 'actions/runner source — ScriptHandlerHelpers.cs (unquoted bash template)'

package/errors/runner-environment/runner-environment-228.yml

@@ -0,0 +1,117 @@
+id: runner-environment-228
+title: 'setup-node@v6 cache detection fails when .yarnrc.yml contains approvedGitRepositories (yarn 4.14+)'
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - yarn
+  - cache
+  - yarnrc
+  - approvedGitRepositories
+  - yarn-4
+  - cache-detection
+patterns:
+  - regex: 'Unrecognized or legacy configuration settings found: approvedGitRepositories'
+    flags: 'i'
+  - regex: "The 'yarn config get cacheFolder' command failed with exit code"
+    flags: 'i'
+  - regex: 'yarn config get cacheFolder.*exit code: 1'
+    flags: 'i'
+error_messages:
+  - "Usage Error: Unrecognized or legacy configuration settings found: approvedGitRepositories - run \"yarn config -v\" to see the list of settings supported in Yarn"
+  - "Error: The 'yarn config get cacheFolder' command failed with exit code: 1"
+root_cause: |
+  Yarn 4.14 introduced the `approvedGitRepositories` security setting in `.yarnrc.yml`.
+  This key enforces an allowlist of Git repository URLs that yarn is permitted to fetch
+  packages from, blocking unapproved source URLs with:
+
+    "Request to '<url>' has been blocked because it doesn't match any of the
+    patterns in 'approvedGitRepositories'"
+
+  However, any `.yarnrc.yml` key that is unrecognized or deprecated by the currently
+  installed version of yarn causes yarn to abort ALL config commands with:
+
+    "Usage Error: Unrecognized or legacy configuration settings found: approvedGitRepositories"
+
+  The `actions/setup-node@v6` action detects the yarn cache folder path by executing
+  `yarn config get cacheFolder` early in the action — before any Node.js version is
+  installed and before yarn itself is updated. If the runner's bundled yarn version is
+  older than 4.14, it does not recognize `approvedGitRepositories` and aborts.
+
+  The action catches the non-zero exit code and surfaces the error:
+    "Error: The 'yarn config get cacheFolder' command failed with exit code: 1"
+
+  This failure prevents setup-node from resolving the yarn cache path, breaking the
+  entire step. Users frequently observe this when:
+  - Upgrading to yarn 4.14+ and adding `approvedGitRepositories` to `.yarnrc.yml`
+  - Running on hosted runners where the system yarn version is older than 4.14
+  - Running on self-hosted runners with a frozen yarn version
+
+  The root issue is that yarn's unrecognized-key validation is global — it aborts even
+  read-only config queries when any single key is unrecognized, even if that key is not
+  related to the query.
+fix: |
+  Option 1 — Remove cache:yarn from setup-node (safest immediate fix).
+  Set cache: '' or omit the cache: input entirely. Manage yarn caching with a separate
+  actions/cache step pointed directly at the yarn cache directory.
+
+  Option 2 — Pin the yarn version in the runner environment to match .yarnrc.yml.
+  Ensure the yarn version on the runner is >= 4.14.0 so it recognizes
+  approvedGitRepositories before setup-node calls yarn config get.
+
+  Option 3 — Upgrade setup-node to a version that handles this gracefully.
+  Track actions/setup-node#1534 for a fix that makes cache folder detection resilient
+  to yarn config validation errors.
+
+  Option 4 — Use a separate cache step instead of setup-node's built-in cache.
+  This avoids the setup-node yarn version probe entirely.
+fix_code:
+  - language: yaml
+    label: 'Remove cache:yarn from setup-node and use a standalone cache step'
+    code: |
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          # Do NOT set cache: yarn — it triggers yarn config get cacheFolder
+          # which fails when approvedGitRepositories is in .yarnrc.yml
+
+      # Manage yarn cache manually
+      - name: Get yarn cache directory
+        id: yarn-cache-dir
+        run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
+
+      - uses: actions/cache@v4
+        with:
+          path: ${{ steps.yarn-cache-dir.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - run: yarn install --immutable
+
+  - language: yaml
+    label: 'Pin yarn version to 4.14+ before setup-node runs'
+    code: |
+      - name: Enable corepack with matching yarn version
+        run: |
+          corepack enable
+          corepack prepare yarn@4.14.1 --activate
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn   # Now safe — yarn 4.14+ recognizes approvedGitRepositories
+prevention:
+  - 'After adding any new key to .yarnrc.yml, verify it is recognized by running yarn config -v locally and confirming the key appears in the supported list.'
+  - 'When using setup-node cache:yarn with yarn 4+, pin the yarn version via packageManager in package.json or via corepack before the setup-node step.'
+  - 'Monitor actions/setup-node release notes for fixes to yarn cache detection resilience (issue #1534).'
+  - 'If .yarnrc.yml uses security features added in a recent yarn release, document the minimum required yarn version in your repo README and CI setup guide.'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1534'
+    label: 'actions/setup-node#1534 — Problem with yarn v4.14 config approvedGitRepositories'
+  - url: 'https://github.com/yarnpkg/berry/issues/7108'
+    label: 'yarnpkg/berry#7108 — approvedGitRepositories config key tracking issue'
+  - url: 'https://yarnpkg.com/configuration/yarnrc#approvedGitRepositories'
+    label: 'Yarn docs — approvedGitRepositories configuration'
+  - url: 'https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data'
+    label: 'setup-node — Advanced usage: caching packages data'