@htekdev/actions-debugger 1.0.99 → 1.0.101

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

@@ -0,0 +1,136 @@
+id: permissions-auth-059
+title: 'GITHUB_TOKEN expires after 24 hours on self-hosted runners — long-running jobs fail with "GITHUB_TOKEN has expired"'
+category: permissions-auth
+severity: error
+tags:
+  - GITHUB_TOKEN
+  - token-expiry
+  - self-hosted-runner
+  - long-running-jobs
+  - 24-hour-limit
+  - authentication
+patterns:
+  - regex: 'GITHUB_TOKEN has expired'
+    flags: 'i'
+  - regex: 'Unable to extend GITHUB_TOKEN expiration'
+    flags: 'i'
+  - regex: 'token.*expired.*self.hosted'
+    flags: 'i'
+error_messages:
+  - "Unable to extend GITHUB_TOKEN expiration time due to: GITHUB_TOKEN has expired."
+  - "Error: fatal: unable to access 'https://github.com/...': The requested URL returned error: 403"
+root_cause: |
+  `GITHUB_TOKEN` is an installation access token issued at the START of each job. Its
+  lifetime is tied to the job execution, with a hard cap determined by the runner type:
+
+  - **GitHub-hosted runners**: `GITHUB_TOKEN` lives for up to 6 hours (matching the maximum
+    job execution time). On hosted runners this limit is never the issue because the job
+    itself can't run longer than 6 hours.
+
+  - **Self-hosted runners**: Jobs can run for up to 5 days, but `GITHUB_TOKEN` can only be
+    refreshed for up to **24 hours**. If a job on a self-hosted runner exceeds 24 hours of
+    runtime, any subsequent GitHub API call, `git push`, `gh` CLI invocation, or action that
+    uses `${{ github.token }}` or `${{ secrets.GITHUB_TOKEN }}` will fail with a 401/403
+    authentication error.
+
+  The specific error message is:
+    "Unable to extend GITHUB_TOKEN expiration time due to: GITHUB_TOKEN has expired."
+
+  This is particularly common in:
+  - Large test suites or build pipelines that process massive monorepos
+  - ML/data pipelines that process large datasets sequentially
+  - Long-running deployment or migration jobs that need GitHub API access at the end
+  - Jobs with retries that collectively exceed 24 hours
+
+  Note: `actions/create-github-app-token` GitHub App tokens have a similar but shorter
+  1-hour expiry — see permissions-auth-046 for that pattern.
+fix: |
+  Several approaches, in order of recommendation:
+
+  1. **Split the job into smaller jobs** — Break the long-running job into multiple shorter
+     jobs connected by `needs:` dependencies. Each job gets its own fresh `GITHUB_TOKEN`.
+
+  2. **Use a GitHub App token** — Use `actions/create-github-app-token` to generate tokens
+     mid-job as needed, or generate a fresh token at the point in the job where you need it.
+
+  3. **Use a PAT (Personal Access Token)** — Store a long-lived PAT in repository or
+     organization secrets and use it in place of `GITHUB_TOKEN` for the API calls at the
+     end of the long-running job. PATs do not expire in 24 hours (they expire based on the
+     PAT expiration date you set). Drawback: PATs are tied to a specific user account.
+
+  4. **Use a machine user PAT** — Create a dedicated machine account and use its PAT.
+     This decouples the secret from any individual developer's account.
+fix_code:
+  - language: yaml
+    label: 'Problem: long-running self-hosted job uses GITHUB_TOKEN after 24+ hours'
+    code: |
+      jobs:
+        long-build:
+          runs-on: [self-hosted, large-runner]
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run 26-hour data processing
+              run: ./scripts/process_all_data.sh   # takes ~26 hours
+
+            # FAILS: GITHUB_TOKEN has expired by the time this step runs
+            - name: Upload results to GitHub
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: gh release upload v1.0 ./output/*.tar.gz
+  - language: yaml
+    label: 'Fix: split into jobs so each gets a fresh GITHUB_TOKEN'
+    code: |
+      jobs:
+        process-data:
+          runs-on: [self-hosted, large-runner]
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/process_all_data.sh
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output-files
+                path: ./output/
+
+        upload-release:
+          needs: process-data
+          runs-on: ubuntu-latest     # hosted runner with fresh token
+          permissions:
+            contents: write
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: output-files
+                path: ./output/
+            # GITHUB_TOKEN is fresh — just issued for this new job
+            - name: Upload to release
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: gh release upload v1.0 ./output/*.tar.gz
+  - language: yaml
+    label: 'Fix: use stored PAT when splitting jobs is not feasible'
+    code: |
+      jobs:
+        long-build:
+          runs-on: [self-hosted, large-runner]
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/process_all_data.sh
+
+            # Use a PAT stored in secrets — does not expire in 24 hours
+            - name: Upload results (using PAT)
+              env:
+                GH_TOKEN: ${{ secrets.MACHINE_USER_PAT }}   # PAT, not github.token
+              run: gh release upload v1.0 ./output/*.tar.gz
+prevention:
+  - "Design self-hosted runner jobs to complete within 24 hours, or split them into smaller jobs connected by `needs:`."
+  - "If a job genuinely requires >24 hours of runtime, use a PAT or GitHub App token for API calls instead of `GITHUB_TOKEN`."
+  - "Add a monitoring step that logs elapsed job time — alert if a job approaches 20+ hours."
+  - "Avoid using `GITHUB_TOKEN` for API calls near the end of jobs that are known to run close to the 24-hour limit."
+  - "For GitHub-hosted runners this is not an issue — the job execution limit (6 hours) is shorter than the token lifetime."
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#about-the-github_token-secret'
+    label: 'GitHub Docs: GITHUB_TOKEN — effective maximum lifetime'
+  - url: 'https://stackoverflow.com/questions/75602556/how-can-i-use-a-github-token-for-more-than-24-hours'
+    label: 'Stack Overflow: How to use GITHUB_TOKEN for more than 24 hours'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits'
+    label: 'GitHub Docs: Self-hosted runner usage limits (5-day job limit)'

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

@@ -0,0 +1,115 @@
+id: permissions-auth-060
+title: 'Fork Pull Request Workflows Cannot Access Repository Secrets — Secrets Context Is Empty'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - fork
+  - pull-request
+  - secrets
+  - security
+  - workflow-permissions
+patterns:
+  - regex: 'secrets\.[\w_]+.*empty|secrets context.*fork'
+    flags: 'i'
+error_messages:
+  - "Error: Input required and not supplied: token"
+  - "HttpError: Bad credentials"
+  - "Error: Resource not accessible by integration"
+root_cause: |
+  GitHub's security model prevents workflows triggered by `pull_request` events from
+  fork repositories from accessing repository secrets. This applies to ALL non-Dependabot
+  external contributor forks — not just Dependabot.
+
+  When a fork PR workflow runs:
+  - All `secrets.*` values resolve to empty string `''`
+  - `secrets.GITHUB_TOKEN` is replaced with a read-only token scoped only to the fork
+    repository (cannot write to the upstream repo, cannot access packages, etc.)
+  - Environment secrets are also unavailable
+  - Fine-grained PATs stored as secrets are unavailable
+
+  This is intentional — allowing forks to read secrets would enable malicious PRs to
+  exfiltrate credentials.
+
+  Common failure patterns:
+  - `actions/setup-node` with `registry-url` + `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` → 401 Unauthorized
+  - `docker/login-action` with `${{ secrets.DOCKERHUB_TOKEN }}` → login fails silently, image push 403
+  - `aws-actions/configure-aws-credentials` with role ARN from secrets → empty role, OIDC fallback
+  - Custom actions reading a `token:` input wired to `${{ secrets.MY_TOKEN }}` → action receives ''
+    and may throw "Input required and not supplied: token"
+
+  The fork PR restriction also applies to `workflow_dispatch` when triggered from a fork,
+  and to `check_suite`/`check_run` events from fork PRs.
+
+  Note: `pull_request_target` DOES have access to secrets because it runs in the context
+  of the BASE repository — but this introduces a different security risk (running untrusted
+  code with secret access) that requires careful mitigation.
+fix: |
+  For CI checks that don't need secrets (lint, unit tests, build validation), no change
+  is needed — the read-only GITHUB_TOKEN is sufficient.
+
+  For steps that require secrets:
+
+  1. Gate secret-requiring steps on `github.event.pull_request.head.repo.fork == false`
+     to skip them on fork PRs gracefully.
+  2. Use `pull_request_target` + a separate privileged job for publishing/deploying,
+     but ALWAYS check out from `github.event.pull_request.head.sha` explicitly and
+     never run untrusted code in the same job.
+  3. For package publishing, only publish from base branch pushes (not from PRs at all).
+fix_code:
+  - language: yaml
+    label: "Skip secret-requiring steps on fork PRs gracefully"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests (works on fork PRs)
+              run: npm test
+
+            - name: Publish coverage report (skip on fork PRs)
+              if: github.event.pull_request.head.repo.fork == false
+              env:
+                CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+              run: npx codecov
+  - language: yaml
+    label: "Split fork-safe CI from privileged deployment using workflow_run"
+    code: |
+      # workflow: ci.yml — runs on all PRs including forks (no secrets needed)
+      on:
+        pull_request:
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+      ---
+      # workflow: publish-coverage.yml — runs after ci.yml completes (has secrets)
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [completed]
+      jobs:
+        coverage:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Publish coverage
+              env:
+                CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+              run: echo "Publishing coverage for run ${{ github.event.workflow_run.id }}"
+prevention:
+  - "Design CI workflows to not require secrets for the build/test steps — secrets should only be needed for publish/deploy"
+  - "Check `github.event.pull_request.head.repo.fork` before any step that uses secrets to provide a clear skip message"
+  - "Do not use `pull_request_target` as a shortcut to get secrets — it runs untrusted fork code with base repo privileges, creating a severe injection risk"
+  - "Use `workflow_run` to chain a privileged follow-up workflow that runs in base repo context after fork CI succeeds"
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections"
+    label: "GitHub Docs — Security hardening: fork PR and secret access"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request"
+    label: "GitHub Docs — pull_request event: fork limitations"
+  - url: "https://securitylab.github.com/research/github-actions-preventing-pwn-requests/"
+    label: "GitHub Security Lab — Preventing pwn requests (pull_request_target risks)"

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

@@ -0,0 +1,88 @@
+id: runner-environment-169
+title: 'actions/runner 2.320.0+ container image removes SSH — "error: cannot run ssh: No such file or directory"'
+category: runner-environment
+severity: error
+tags:
+  - runner
+  - ssh
+  - openssh-client
+  - git-submodules
+  - self-hosted
+  - container-runner
+  - 2.320
+patterns:
+  - regex: 'error: cannot run ssh: No such file or directory'
+    flags: 'i'
+  - regex: 'fatal: unable to fork'
+    flags: 'i'
+  - regex: 'Unable to locate executable file: ssh'
+    flags: 'i'
+  - regex: 'error downloading.*ssh://.*No such file or directory'
+    flags: 'i'
+error_messages:
+  - "error: cannot run ssh: No such file or directory"
+  - "fatal: unable to fork"
+  - "Unable to locate executable file: ssh. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable."
+  - "error downloading 'ssh://git@github.com/...': /usr/bin/git exited with 128: error: cannot run ssh: No such file or directory"
+root_cause: |
+  Starting with actions/runner 2.320.0, the base container image
+  (ghcr.io/actions/actions-runner) no longer ships openssh-client by default.
+  Workflows that rely on git operations over SSH — including submodule cloning
+  via SSH URLs, Terragrunt module downloads over ssh://, or any step that
+  calls ssh-keyscan — fail at runtime because the ssh binary is absent from
+  the runner's PATH.
+
+  This affected both self-hosted runners built from the official container
+  image and any ephemeral runners (Actions Runner Controller / ARC) that
+  derive from ghcr.io/actions/actions-runner:2.320.0+. Hosted runners
+  (ubuntu-latest, etc.) were not affected because they use a separate,
+  pre-loaded VM image that still includes openssh-client.
+
+  The regression was introduced when the container image was slimmed down
+  between 2.319.1 and 2.320.0 without a corresponding changelog callout,
+  leaving self-hosted container runners silently broken on upgrade.
+fix: |
+  Install openssh-client in the runner container image before the runner
+  process starts. For Dockerfiles extending the official image, add an
+  explicit RUN instruction. For ARC runner deployments, add an
+  initContainers step or a containerStartupCommand to install the package.
+
+  If you do not control the image, add an installation step at the top of
+  the failing workflow job before any SSH-dependent steps.
+fix_code:
+  - language: yaml
+    label: 'Option A — Add install step in the workflow before any SSH steps'
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          steps:
+            - name: Install SSH client
+              run: |
+                apt-get update -qq && apt-get install -y --no-install-recommends openssh-client
+            - name: Checkout with submodules
+              uses: actions/checkout@v4
+              with:
+                submodules: recursive
+                ssh-key: ${{ secrets.SSH_KEY }}
+  - language: dockerfile
+    label: 'Option B — Bake openssh-client into a custom runner image'
+    code: |
+      FROM ghcr.io/actions/actions-runner:latest
+      USER root
+      RUN apt-get update && apt-get install -y --no-install-recommends openssh-client && rm -rf /var/lib/apt/lists/*
+      USER runner
+prevention:
+  - "Pin your ARC / self-hosted runner image to a tested version (e.g., ghcr.io/actions/actions-runner:2.319.1) and test upgrades in a staging environment before rolling out."
+  - "Add a pre-flight check step that runs 'which ssh || (apt-get install -y openssh-client)' if your workflow requires SSH."
+  - "Prefer HTTPS-based submodule URLs and GITHUB_TOKEN for submodule auth in GitHub Actions — this avoids SSH entirely."
+  - "Subscribe to the actions/runner GitHub Releases feed to catch breaking changes in container image composition."
+docs:
+  - url: 'https://github.com/actions/runner/issues/3490'
+    label: 'actions/runner #3490 — Runner 2.320.0 no longer has SSH installed'
+  - url: 'https://github.com/actions/runner/issues/3488'
+    label: 'actions/runner #3488 — Runner version 2.320.0 breaks custom image'
+  - url: 'https://github.com/actions/checkout/issues/1942'
+    label: 'actions/checkout #1942 — Unable to locate executable file: ssh'
+  - url: 'https://github.com/actions/runner/releases'
+    label: 'actions/runner releases'

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

@@ -0,0 +1,93 @@
+id: runner-environment-170
+title: 'windows-latest Migration to Windows Server 2025 Removes MSVC v142 (VS 2019) Toolchain'
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - msvc
+  - cmake
+  - msbuild
+  - toolchain
+  - migration
+patterns:
+  - regex: 'MSB8020.*v142.*cannot be found'
+    flags: 'i'
+  - regex: 'build tools for v142.*Platform Toolset.*v142.*cannot be found'
+    flags: 'i'
+  - regex: 'CMAKE_GENERATOR_TOOLSET.*v142.*not found'
+    flags: 'i'
+error_messages:
+  - "MSBUILD : error MSB8020: The build tools for v142 (Platform Toolset = 'v142') cannot be found."
+  - "CMake Error: The CMAKE_CXX_COMPILER: cl.exe is not able to compile a simple test program."
+  - "error MSB8020: The build tools for v142 (Platform Toolset = 'v142') cannot be found."
+root_cause: |
+  Starting November 2024, `windows-latest` was migrated to Windows Server 2025 with
+  Visual Studio 2022 17.12 as the default build environment. Windows Server 2025 runner
+  images do not include the Visual Studio 2019 build tools (MSVC v142 / toolset 14.2).
+
+  Projects that explicitly request the VS 2019 toolchain via any of these mechanisms fail:
+  - MSBuild `<PlatformToolset>v142</PlatformToolset>` in .vcxproj files
+  - CMake `-T v142` flag or `set(CMAKE_GENERATOR_TOOLSET v142)` in CMakeLists.txt
+  - MSBuild command-line flag `/p:PlatformToolset=v142`
+  - Visual Studio solution files pinned to VS 2019 (toolset version 142)
+
+  Windows Server 2022 runners (`windows-2022`) continue to offer both VS 2019
+  (v142) and VS 2022 (v143) toolchains in parallel. After the `windows-latest`
+  migration, workflows that did not pin to `windows-2022` and relied on v142
+  break silently on runners already migrated while appearing to work in older
+  runner pools.
+
+  The migration timeline:
+  - Nov 2024: windows-latest begins pointing to Windows Server 2025 (partial rollout)
+  - Early 2025: Full rollout; all new `windows-latest` queue jobs use WS 2025
+
+  Reference: https://github.com/actions/runner-images/issues/10751
+fix: |
+  Choose one of the following approaches:
+
+  1. Upgrade to the v143 (VS 2022) toolchain — recommended for long-term compatibility.
+  2. Pin to `windows-2022` runner if you cannot migrate immediately.
+  3. Install the VS 2019 build tools component manually (slow, increases job time).
+fix_code:
+  - language: yaml
+    label: "Option A: upgrade toolchain to v143 (VS 2022) in CMakeLists.txt"
+    code: |
+      # In CMakeLists.txt — remove explicit toolset pinning
+      # cmake_minimum_required(VERSION 3.20)
+      # project(MyProject)
+      # Previously had: set(CMAKE_GENERATOR_TOOLSET "v142")
+      # Remove or update to:
+      # set(CMAKE_GENERATOR_TOOLSET "v143")  # or omit to use default
+  - language: yaml
+    label: "Option B: pin to windows-2022 to keep v142 support"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-2022   # has both v142 and v143 available
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build with CMake
+              run: cmake -B build -T v142 && cmake --build build
+  - language: yaml
+    label: "Option C: install VS 2019 build tools on windows-latest (slow)"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install VS 2019 Build Tools
+              run: |
+                choco install visualstudio2019buildtools --package-parameters "--add Microsoft.VisualStudio.Component.VC.v142.x86.x64" -y
+prevention:
+  - "Audit all .vcxproj and CMakeLists.txt files for explicit v142 toolset references before migrating to windows-latest"
+  - "Pin to `windows-2022` in CI to preserve VS 2019 toolchain availability while planning an upgrade"
+  - "Watch https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md for current pre-installed toolchain versions"
+  - "Use `vswhere` in a pre-build step to detect installed VS components and fail fast with a descriptive error"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/10751"
+    label: "runner-images #10751 — windows-latest migration to Windows Server 2025"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md"
+    label: "Windows Server 2025 runner image README — pre-installed software"
+  - url: "https://learn.microsoft.com/en-us/cpp/build/cmake-presets-vs?view=msvc-170"
+    label: "Microsoft Docs — CMake toolset configuration"

package/errors/silent-failures/github-event-pull-request-null-on-non-pr-events.yml

@@ -0,0 +1,96 @@
+id: silent-failures-090
+title: '`github.event.pull_request.*` Fields Are Null on Non-PR Events — Comparisons Silently Evaluate Incorrectly'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - pull_request
+  - null-context
+  - push-event
+  - multi-event
+  - expression
+patterns:
+  - regex: 'github\.event\.pull_request\.\w+'
+    flags: 'i'
+error_messages:
+  - "Unexpected value '' in expression"
+root_cause: |
+  When a workflow is triggered by a non-pull_request event — such as `push`, `schedule`,
+  `workflow_dispatch`, `workflow_call`, or `release` — the `github.event.pull_request`
+  object is null. Every child field evaluates to empty string `""` in expressions.
+
+  This silently breaks conditions in multi-event workflows:
+
+  - `if: github.event.pull_request.draft == false`
+    On a push event, `draft` resolves to `""`. The comparison `"" == false` evaluates to
+    FALSE (empty string is not boolean false), so the step silently skips.
+
+  - `if: github.event.pull_request.merged == true`
+    Always false on push events, causing steps intended for merged-PR context to silently
+    never execute.
+
+  - `env: PR_NUMBER: ${{ github.event.pull_request.number }}`
+    Sets `PR_NUMBER` to empty string on push events. Downstream scripts that require a
+    PR number fail with "invalid argument" or use `0` as the number.
+
+  - `if: github.event.pull_request.head.repo.fork != true`
+    Always evaluates to true on push events (empty string != true), bypassing fork guards.
+
+  The root issue is that workflows triggered by multiple events (e.g., `on: [push,
+  pull_request]`) share the same `if:` conditions and `env:` references, but the
+  `github.event` object structure differs per event type. Note that `yaml-syntax-060`
+  covers the object filter `.*` operator on null — this entry covers field-level null
+  comparisons in `if:` and `env:` contexts.
+fix: |
+  Guard all `github.event.pull_request.*` access with an event type check:
+
+    if: github.event_name == 'pull_request' && github.event.pull_request.draft == false
+
+  For env variables that should only apply on PR events, set them conditionally:
+  use a step to export the variable only when running under a pull_request trigger,
+  or use separate jobs per event type.
+
+  For the fork guard pattern, use `github.event_name == 'pull_request' &&
+  github.event.pull_request.head.repo.fork` as a combined check rather than relying
+  on the fork field being non-null.
+fix_code:
+  - language: yaml
+    label: "Guard PR context access with event type check in if: condition"
+    code: |
+      jobs:
+        check-draft:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Skip if draft PR (only meaningful on PR events)
+              # Without the event_name guard, draft is "" on push — comparison silently fails
+              if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+              run: echo "Proceeding — not a draft PR"
+  - language: yaml
+    label: "Export PR-specific context safely in multi-event workflows"
+    code: |
+      on: [push, pull_request]
+      
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Export PR metadata (PR events only)
+              if: github.event_name == 'pull_request'
+              run: |
+                echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> $GITHUB_ENV
+                echo "IS_DRAFT=${{ github.event.pull_request.draft }}" >> $GITHUB_ENV
+            
+            - name: Deploy
+              run: |
+                echo "Branch: ${{ github.ref_name }}"
+                # Use PR_NUMBER only after confirming event_name == pull_request above
+prevention:
+  - "In multi-event workflows, always guard `github.event.pull_request.*` access with `github.event_name == 'pull_request'`"
+  - "Run actionlint on workflow files — it detects context availability mismatches per event type"
+  - "Test workflows manually for both push and pull_request trigger types to verify that conditional logic works as expected"
+  - "Prefer separate jobs or separate workflow files per event type rather than a single workflow handling multiple events with shared conditions"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows"
+    label: "GitHub Docs: Events that trigger workflows — context availability per event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context"
+    label: "GitHub Docs: Contexts — github.event object structure"

package/errors/silent-failures/silent-failures-091.yml

@@ -0,0 +1,94 @@
+id: silent-failures-091
+title: '`github.ref_name` Returns Ephemeral Merge Ref (`123/merge`) on `pull_request` Trigger, Not Branch Name'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - ref-name
+  - pull-request
+  - docker
+  - branch-name
+  - deployment
+patterns:
+  - regex: '\d+/merge'
+    flags: 'i'
+error_messages:
+  - "invalid reference format"
+  - "invalid tag format"
+root_cause: |
+  When a workflow is triggered by a `pull_request` event, GitHub creates an ephemeral
+  merge commit that merges the PR head into the base branch. The context variables for
+  this run reflect the merge ref, not the source branch:
+
+  - `github.ref` = `refs/pull/123/merge`
+  - `github.ref_name` = `123/merge`
+  - `github.sha` = SHA of the ephemeral merge commit
+  - `github.head_ref` = `feature-branch-name` (the actual PR branch)
+  - `github.base_ref` = `main` (the target branch)
+
+  Using `github.ref_name` in contexts that expect a branch name silently produces
+  the merge ref string `123/merge` instead:
+
+  - **Docker image tags**: `docker.io/myapp:123/merge` — Docker rejects the forward slash
+    as an invalid tag character (`invalid reference format` error), OR worse, interprets
+    `123` as a registry name.
+  - **Deployment environment names**: The environment is created as `123/merge` rather
+    than the branch name, causing routing rules to miss the deployment.
+  - **Branch-based conditional logic**: `if: github.ref_name == 'feature-foo'` always
+    evaluates to false on pull_request events.
+  - **Artifact naming**: Artifacts uploaded with the ref_name contain forward slashes,
+    causing path traversal issues on some download handlers.
+
+  `github.head_ref` is only populated for `pull_request` and `pull_request_target`
+  events, making branch detection logic that works on push but silently fails on PR
+  events harder to diagnose.
+fix: |
+  Use the correct context variable for each event type:
+
+  - For the PR's source branch name: `github.head_ref` (only set on pull_request events)
+  - For push events' branch name: `github.ref_name`
+  - For a branch name that works across both event types, use a conditional expression.
+fix_code:
+  - language: yaml
+    label: "Unified branch name across push and pull_request events"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Determine branch name
+              id: branch
+              run: |
+                if [ "${{ github.event_name }}" = "pull_request" ]; then
+                  echo "name=${{ github.head_ref }}" >> "$GITHUB_OUTPUT"
+                else
+                  echo "name=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+                fi
+
+            - name: Build and tag Docker image
+              run: |
+                # Sanitize slashes for use in image tags
+                TAG=$(echo "${{ steps.branch.outputs.name }}" | tr '/' '-')
+                docker build -t "myapp:${TAG}" .
+  - language: yaml
+    label: "Expression-based branch name (no shell step needed)"
+    code: |
+      env:
+        BRANCH_NAME: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          steps:
+            - run: echo "Deploying branch ${{ env.BRANCH_NAME }}"
+prevention:
+  - "Never use `github.ref_name` directly in Docker image tags — always sanitize forward slashes with `tr '/' '-'` or similar"
+  - "Test branch-detection expressions with both `push` and `pull_request` triggers in a dry-run workflow"
+  - "Use `github.head_ref` for PR branch name and `github.ref_name` for push branch name — they are NOT interchangeable"
+  - "Add an explicit check: if `github.ref_name` contains a `/`, the workflow is running on a pull_request or merge ref, not a regular branch"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub Docs — github context reference"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request"
+    label: "GitHub Docs — pull_request event"