@htekdev/actions-debugger 1.0.48 → 1.0.50

package/errors/caching-artifacts/caching-artifacts-035.yml

@@ -0,0 +1,119 @@
+id: caching-artifacts-035
+title: 'actions/cache fail-on-cache-miss: true causes first-run workflow failure — no cache exists on initial or rekeyed run'
+category: caching-artifacts
+severity: error
+tags:
+  - cache
+  - fail-on-cache-miss
+  - first-run
+  - actions-cache
+  - cache-miss
+  - bootstrap
+patterns:
+  - regex: 'fail-on-cache-miss:\s*true'
+    flags: 'i'
+  - regex: 'Error: Cannot find a cache that matches the specified keys'
+    flags: 'i'
+error_messages:
+  - 'Error: Cannot find a cache that matches the specified keys'
+  - 'Cache not found for input keys: ...'
+  - '##[error]Cannot find a cache that matches the specified keys'
+root_cause: |
+  The actions/cache action added a fail-on-cache-miss input (introduced in v3.3.0,
+  available in v4). When set to true, the action exits with a non-zero status code
+  if no cache entry matches the provided key or restore-keys list. The intended use
+  case is detecting stale or misconfigured cache keys in established pipelines.
+
+  The critical problem: on the very first run of a workflow (new repository, newly
+  added cache step, or after changing the cache key expression), NO cache exists by
+  definition. With fail-on-cache-miss: true, the action fails immediately and the
+  job exits before any steps produce the artifacts that would be cached.
+
+  This creates a bootstrap deadlock:
+  1. Job starts — no cache exists — fail-on-cache-miss: true fires — job fails
+  2. Post-step cache save never runs because the job failed
+  3. Next run repeats step 1 — cache is never populated — workflow is permanently broken
+
+  The same issue occurs whenever the cache key expression changes (adding runner OS,
+  changing the hash source file, bumping a version prefix), because all existing
+  caches miss the new key pattern. Until the new cache is warm, every run fails.
+
+  Matrix builds compound the problem: each unique matrix dimension (OS × version)
+  needs its own initial run to seed the cache, so all combinations fail in parallel
+  on first use of the new key.
+fix: |
+  Remove fail-on-cache-miss: true from the actions/cache step unless you have an
+  externally pre-seeded cache and a specific requirement to guarantee it exists
+  (rare, advanced use case).
+
+  For the common use case of skipping expensive install steps on cache hit:
+  use the cache-hit output instead. cache-hit is 'true' on exact key match and
+  allows downstream steps to be conditional, while still letting the job complete
+  successfully on a miss so the cache can be populated.
+
+  If you genuinely need to gate on cache existence (e.g., a nightly build that
+  consumes a separately-seeded model or dataset cache), run a dedicated cache-warming
+  workflow first and use fail-on-cache-miss: true only after confirming the seeder
+  workflow has run at least once.
+fix_code:
+  - language: yaml
+    label: 'Use cache-hit output for conditional install instead of fail-on-cache-miss'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Cache npm dependencies
+              id: cache-npm
+              uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+                # AVOID: fail-on-cache-miss: true  ← breaks first run (deadlock)
+
+            - name: Install dependencies
+              # Only runs on cache miss — fast path skipped on hit
+              if: steps.cache-npm.outputs.cache-hit != 'true'
+              run: npm ci
+
+            - name: Build
+              run: npm run build
+
+  - language: yaml
+    label: 'Dedicated cache-warming workflow to pre-seed before fail-on-cache-miss use'
+    code: |
+      # .github/workflows/warm-cache.yml — run this first to pre-seed
+      name: Warm Cache
+      on:
+        schedule:
+          - cron: '0 6 * * 1'
+        workflow_dispatch:   # Allow manual trigger when rekeying cache
+
+      jobs:
+        warm:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Cache dependencies
+              uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            - name: Install to populate cache
+              run: npm ci
+prevention:
+  - 'Never set fail-on-cache-miss: true on a fresh workflow or after changing the cache key expression — the cache cannot exist yet'
+  - 'Use cache-hit output and conditional if: steps.id.outputs.cache-hit != true for skip-on-hit behavior without failing on miss'
+  - 'When rekeying cache (OS prefix, hash source change), trigger a manual cache-warming workflow_dispatch run before deploying the new key'
+  - 'Test new cache key expressions in a feature branch where a job failure will not block main'
+docs:
+  - url: 'https://github.com/actions/cache'
+    label: 'actions/cache README — fail-on-cache-miss input documentation'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows'
+  - url: 'https://github.com/actions/cache/blob/main/tips-and-workarounds.md'
+    label: 'actions/cache tips and workarounds — cache miss handling patterns'

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

@@ -0,0 +1,100 @@
+id: permissions-auth-037
+title: 'Environment secrets are only accessible to jobs that declare a matching environment: key — other jobs silently receive empty string'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - environment
+  - secrets
+  - environment-secrets
+  - deployment-environment
+  - job-scoped
+  - secret-scope
+patterns:
+  - regex: 'environment:\s*[a-z0-9_-]+.*secrets\.|secrets\.[A-Z_]+'
+    flags: 'i'
+error_messages:
+  - "(No error — secrets.<SECRET_NAME> resolves to '' in jobs that do not declare the matching environment:)"
+root_cause: |
+  GitHub Actions supports three secret scopes with different visibility:
+  1. Repository secrets — available to all jobs in all workflows in the repository
+  2. Organization secrets — available to authorized repositories/workflows
+  3. Environment secrets — ONLY available to jobs that declare environment: <env-name>
+
+  Environment secrets are scoped to a specific deployment environment and are
+  intentionally isolated. A job that references secrets.MY_ENV_SECRET without
+  declaring environment: production receives '' (empty string) for that secret
+  with no error, no warning, and no indication that the secret exists elsewhere.
+
+  This isolation is a security feature: environment secrets are only released to
+  jobs that have satisfied environment protection rules (required reviewers, wait
+  timers, deployment branch policies). However it becomes a silent failure when:
+
+  - A secret is accidentally created in an environment instead of the repository scope
+  - A reusable workflow job uses the secret but the caller job did not declare environment:
+  - A job is refactored to remove environment: (to skip protection rules in testing) but
+    still references the now-inaccessible environment secret
+  - A developer expects an environment secret to work like a repository secret
+
+  The effect is indistinguishable from the secret not existing: the value is '' and the
+  job may fail with an auth error, a blank config value, or silently produce wrong output.
+fix: |
+  Determine the intended scope:
+  - If the secret should be accessible to all jobs: create it as a repository secret
+    (Settings > Secrets and variables > Actions > Repository secrets)
+  - If the secret must be gated by deployment protection rules: keep it as an environment
+    secret AND add environment: <env-name> to every job that needs it
+  - If both a repository secret and an environment secret share the same name:
+    the environment secret takes precedence in jobs that declare that environment
+
+  Use the GitHub Settings UI to confirm which scope a secret belongs to before
+  debugging unexpected empty values in run steps.
+fix_code:
+  - language: yaml
+    label: 'Add environment: to the job that needs the environment-scoped secret'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # Without this environment: key, secrets.DEPLOY_API_KEY is ''
+          # even though it exists as an environment secret for 'production'
+          environment: production
+          steps:
+            - name: Deploy to production
+              env:
+                API_KEY: ${{ secrets.DEPLOY_API_KEY }}
+              run: echo "Deploying with scoped key"
+
+  - language: yaml
+    label: 'Separate build (no environment) from deploy (with environment) to scope protection rules to deploy only'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # No environment: here — only repository-scoped secrets are needed for build
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Building artifacts"
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          environment: production   # Required reviewers or wait timer enforced here
+          steps:
+            - name: Deploy
+              env:
+                # DEPLOY_KEY is an environment secret — only available because
+                # environment: production is declared on this job
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+              run: echo "Deploying with environment-scoped secret"
+prevention:
+  - 'When creating a secret, confirm its intended scope: environment secrets require the matching environment: on every job that needs them'
+  - 'If a secret is needed in a build job (no deployment environment), create it as a repository secret not an environment secret'
+  - 'Add environment: to reusable workflow caller jobs when the called workflow references environment-scoped secrets'
+  - 'Use the GitHub Settings UI to audit secret scopes when debugging empty secret values'
+docs:
+  - url: 'https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment'
+    label: 'GitHub Docs: Using environments for deployment'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-environment'
+    label: 'GitHub Docs: Creating secrets for an environment'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment'
+    label: 'GitHub Docs: jobs.<job_id>.environment syntax'

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

@@ -0,0 +1,103 @@
+id: runner-environment-104
+title: 'Private container registry image (ghcr.io, Docker Hub private) requires credentials: in the container: block — a docker login step is too late'
+category: runner-environment
+severity: error
+tags:
+  - container
+  - ghcr
+  - private-registry
+  - credentials
+  - docker-pull
+  - job-container
+  - services
+patterns:
+  - regex: 'pull access denied.*repository does not exist or may require.*login'
+    flags: 'i'
+  - regex: 'unauthorized.*authentication required|denied.*requested access to the resource is denied'
+    flags: 'i'
+error_messages:
+  - 'Error response from daemon: pull access denied for ghcr.io/org/image, repository does not exist or may require docker login: denied'
+  - 'Error: unauthorized: authentication required'
+  - 'Error pulling image: denied: requested access to the resource is denied'
+  - 'toomanyrequests: You have reached your pull rate limit'
+root_cause: |
+  When a job specifies a container image via jobs.<id>.container.image:, GitHub Actions
+  pulls the image before the job starts — before any steps execute. There is no
+  opportunity to authenticate with a docker login step because steps run inside the
+  already-running container.
+
+  Many workflows attempt to call docker/login-action or similar in a step, but by
+  then the container pull has either succeeded or already failed. The login step
+  has no effect on the original image pull.
+
+  The same limitation applies to services containers (jobs.<id>.services.<id>.image:):
+  all service containers are also pulled at job startup before any steps run.
+
+  Common scenarios that hit this error:
+  - Private GitHub Container Registry (ghcr.io) images requiring a PAT with
+    read:packages scope
+  - Docker Hub private repository images (rate-limited or private-tier)
+  - Self-hosted or corporate registries requiring Basic auth
+  - AWS ECR private images (ECR is not directly supported via credentials: block —
+    see fix for the ECR-specific workaround)
+fix: |
+  Provide credentials in the container: or services: block using the credentials: key.
+  These credentials are used at image pull time, before any steps begin.
+
+  For ghcr.io: use github.actor as username and a PAT with read:packages scope as
+  password. If the package is in the same org and the repository has package access,
+  secrets.GITHUB_TOKEN may also work.
+
+  For Docker Hub: use a Docker Hub username and access token (not password).
+
+  For AWS ECR private images: use a self-hosted runner with ECR credentials
+  pre-configured on the host, or build a public mirror of your private image.
+  The credentials: block does not support dynamic ECR token retrieval.
+fix_code:
+  - language: yaml
+    label: 'Authenticate to a private ghcr.io image using credentials in the container block'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          container:
+            image: ghcr.io/myorg/private-runner:latest
+            # credentials: evaluated at job startup BEFORE any steps run
+            credentials:
+              username: ${{ github.actor }}
+              password: ${{ secrets.GHCR_PAT }}
+              # For same-org packages with package access enabled:
+              # password: ${{ secrets.GITHUB_TOKEN }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Running inside authenticated private container"
+
+  - language: yaml
+    label: 'Private Docker Hub image in a services block using credentials'
+    code: |
+      jobs:
+        integration-test:
+          runs-on: ubuntu-latest
+          services:
+            database:
+              image: myorg/private-db:5.7
+              # credentials: here too — service images are pulled before steps
+              credentials:
+                username: ${{ secrets.DOCKER_USERNAME }}
+                password: ${{ secrets.DOCKER_TOKEN }}
+              ports:
+                - 5432:5432
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Integration test against private DB image"
+prevention:
+  - 'Always use the credentials: block inside container: or services: for private images — a docker login step in run: is too late'
+  - 'For same-org ghcr.io images, configure package visibility to allow GITHUB_TOKEN to avoid managing a separate PAT'
+  - 'Test authentication separately with docker pull from a local machine using the same credentials before wiring into a workflow'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idcontainer'
+    label: 'GitHub Docs: jobs.<job_id>.container.credentials'
+  - url: 'https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions'
+    label: 'GitHub Docs: Using GITHUB_TOKEN with GitHub Packages (ghcr.io)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idservicesservice_idcredentials'
+    label: 'GitHub Docs: jobs.<job_id>.services.<service_id>.credentials'

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

@@ -0,0 +1,111 @@
+id: runner-environment-105
+title: 'macOS 12 (Monterey) runner retired September 2024 — runs-on: macos-12 workflows fail or queue indefinitely'
+category: runner-environment
+severity: error
+tags:
+  - macos-12
+  - runner-retirement
+  - macos-monterey
+  - deprecated-runner
+  - github-hosted
+  - runs-on
+patterns:
+  - regex: 'runs-on:\s*macos-12'
+    flags: 'i'
+  - regex: 'No runner matching the specified labels was found.*macos-12|Requested labels: macos-12'
+    flags: 'i'
+error_messages:
+  - 'No runner matching the specified labels was found: macos-12'
+  - '##[error]No runner matching the specified labels was found'
+  - 'Runner not found matching labels: [macos-12]'
+root_cause: |
+  GitHub retired the macOS 12 (Monterey) hosted runner on September 1, 2024. After
+  this date, workflows specifying runs-on: macos-12 can no longer be scheduled on a
+  GitHub-hosted runner matching that label.
+
+  Depending on repository and organization settings, affected jobs may:
+  - Fail immediately with "No runner matching the specified labels was found"
+  - Queue indefinitely waiting for a runner that will never be provisioned
+  - Show a "This job was skipped" status with no clear error message
+
+  GitHub announced the deprecation on May 20, 2024 (90+ days notice) and made it
+  official with a deprecation flag on July 1, 2024. Hard retirement occurred
+  September 1, 2024.
+
+  macOS 12 was the Monterey release. GitHub's macOS runner fleet moved to:
+  - macOS 13 (Ventura) — Intel x86-64, became the Intel baseline
+  - macOS 14 (Sonoma) — Apple Silicon M1, new default for macos-latest (Oct 2024)
+  - macOS 15 (Sequoia) — Apple Silicon M2, macos-latest as of January 2025
+
+  Common sources of this error after retirement:
+  - Long-lived workflow files written when macOS 12 was current
+  - Forks and template repositories with outdated runner labels
+  - Composite actions that pin macos-12 in their action.yml runs: block
+  - Third-party reusable workflows that have not been updated
+fix: |
+  Replace runs-on: macos-12 with a supported macOS runner label. Choose based on
+  architecture requirements:
+
+  - macos-13       — Intel x86-64, macOS Ventura (closest to macOS 12 behavior)
+  - macos-14       — Apple Silicon M1, macOS Sonoma
+  - macos-15       — Apple Silicon M2, macOS Sequoia
+  - macos-latest   — currently macOS 15 / Apple Silicon as of January 2025
+
+  IMPORTANT: macos-14 and later use Apple Silicon (M1/M2). If your workflow depends
+  on Intel x86-64 architecture (Homebrew formula paths differ, Rosetta 2 needed for
+  old binaries, or x86-specific compiler flags), migrate to macos-13, not macos-latest.
+
+  After migrating, verify:
+  - Homebrew default prefix changed from /usr/local (Intel) to /opt/homebrew (ARM)
+  - Xcode version availability — use actions/setup-xcode for explicit version pinning
+  - System Python and Ruby versions differ between macOS generations
+  - Any hardcoded SDKROOT or architecture flags targeting x86-64
+fix_code:
+  - language: yaml
+    label: 'Replace retired macos-12 with macos-13 (Intel) or macos-14/15 (Apple Silicon)'
+    code: |
+      jobs:
+        build-intel:
+          # Before: runs-on: macos-12  ← retired September 1, 2024
+          # Intel x86-64 — closest behavioral match to macOS 12:
+          runs-on: macos-13
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make build
+
+        build-arm:
+          # Apple Silicon M1/M2 — use for new projects or ARM-compatible builds:
+          runs-on: macos-latest   # macOS 15 / Apple Silicon as of Jan 2025
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make build
+
+  - language: yaml
+    label: 'Matrix across macOS versions to validate compatibility before committing to one'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              # Test Intel (13) and Apple Silicon (14) in parallel
+              os: [macos-13, macos-14]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Test on ${{ matrix.os }}
+              run: make test
+prevention:
+  - 'Subscribe to the GitHub Changelog (github.blog/changelog) for runner retirement notices — typically 90+ days notice'
+  - 'Pin to a specific macOS version (macos-13, macos-14) rather than macos-latest for reproducible builds; macos-latest advances'
+  - 'Be aware of architecture differences: macos-13 is Intel x86-64; macos-14 and later are Apple Silicon'
+  - 'Search workflow files periodically for retired labels: look for macos-12, macos-11, ubuntu-18.04, windows-2019'
+docs:
+  - url: 'https://github.blog/changelog/2024-05-20-actions-upcoming-changes-to-github-hosted-macos-runners/'
+    label: 'GitHub Changelog: Upcoming changes to macOS runners (May 2024)'
+  - url: 'https://github.blog/changelog/2024-07-01-github-actions-macos-12-is-now-deprecated/'
+    label: 'GitHub Changelog: macOS 12 is now deprecated (July 2024)'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources'
+    label: 'GitHub Docs: Supported runners and hardware resources'

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

@@ -0,0 +1,102 @@
+id: silent-failures-052
+title: 'Step outputs referenced in the job-level env: block are always empty string — job env is evaluated before any steps run'
+category: silent-failures
+severity: silent-failure
+tags:
+  - env
+  - steps-outputs
+  - job-level
+  - context-evaluation
+  - expression
+  - environment-variables
+patterns:
+  - regex: 'steps\.[a-z0-9_-]+\.outputs\.[a-z0-9_-]+'
+    flags: 'i'
+error_messages:
+  - "(No error — steps.<id>.outputs.<name> silently resolves to '' when used in a job-level env: block)"
+root_cause: |
+  GitHub Actions evaluates the jobs.<id>.env: block once at job initialization, before
+  any steps begin executing. At that point, the steps context exists but all step
+  outputs are empty — no step has run yet, so no outputs have been set.
+
+  This means that ${{ steps.my-step.outputs.value }} in the jobs.<id>.env: block
+  always resolves to '' regardless of what the step later produces. The job does not
+  fail or warn — the environment variable is simply set to empty string and all steps
+  that reference it via $VAR or %VAR% receive nothing.
+
+  This is a context availability limitation documented by GitHub, but it is easy to
+  miss because the expression syntax is valid and the job runs without error.
+
+  Affected env: scopes (evaluated before steps run):
+  - jobs.<id>.env: — job-level env block
+  - The workflow-level env: block also cannot access steps.*, for the same reason
+
+  Env scopes that CAN access step outputs (evaluated per-step):
+  - jobs.<id>.steps.<id>.env: — step-level env block, evaluated when that step runs
+
+  Common mistake: a developer sets a job-level env var to a computed step output
+  (e.g., a parsed version string or a generated artifact path) and then uses that
+  var in multiple subsequent steps, not realizing it is always empty.
+fix: |
+  Move the env: block referencing step outputs from job level down to the individual
+  step level. Step-level env: blocks are evaluated when that step runs, so earlier
+  step outputs are already populated.
+
+  If the same value is needed across many steps, pass it via $GITHUB_OUTPUT and
+  reference it inline with ${{ steps.step-id.outputs.name }} in each step's run:.
+fix_code:
+  - language: yaml
+    label: 'Move env that references step outputs from job level to step level'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+
+          # WRONG: job-level env block — evaluated before any step runs
+          # steps.version.outputs.tag is '' here, no matter what the step produces
+          # env:
+          #   RELEASE_TAG: ${{ steps.version.outputs.tag }}
+
+          steps:
+            - name: Compute release tag
+              id: version
+              run: echo "tag=v1.2.3" >> $GITHUB_OUTPUT
+
+            - name: Build with release tag
+              # CORRECT: step-level env block — evaluated when this step runs
+              # steps.version.outputs.tag is populated by the prior step at this point
+              env:
+                RELEASE_TAG: ${{ steps.version.outputs.tag }}
+              run: echo "Building $RELEASE_TAG"
+
+            - name: Publish with release tag
+              env:
+                RELEASE_TAG: ${{ steps.version.outputs.tag }}
+              run: echo "Publishing $RELEASE_TAG"
+
+  - language: yaml
+    label: 'Use inline expression in run steps to avoid repeating step-level env blocks'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Resolve version
+              id: version
+              run: echo "tag=v2.0.0" >> $GITHUB_OUTPUT
+
+            - name: Tag Docker image
+              # Reference step output directly in run — no env: block needed
+              run: echo "Tagging image as ${{ steps.version.outputs.tag }}"
+
+            - name: Push Docker image
+              run: echo "Pushing tag ${{ steps.version.outputs.tag }}"
+prevention:
+  - 'Never reference steps.<id>.outputs.* in the jobs.<id>.env: block — use step-level env: or inline expressions in run: instead'
+  - 'Enable actionlint locally to catch step output references in job-level env blocks before they reach CI'
+  - 'When the same step output is needed in many steps, document it with a comment on the generating step so readers know where to look'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability'
+    label: 'GitHub Docs: Context availability — which contexts are accessible at each location'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables'
+    label: 'GitHub Docs: Store information in variables'

package/errors/triggers/triggers-037.yml

@@ -0,0 +1,79 @@
+id: triggers-037
+title: 'on.release types: [published] does not fire for pre-releases — prereleased is a separate event type'
+category: triggers
+severity: silent-failure
+tags:
+  - release
+  - prereleased
+  - published
+  - event-types
+  - pre-release
+  - trigger-filter
+patterns:
+  - regex: 'on:\s*\n\s+release:\s*\n\s+types:\s*\[.*published(?!.*prereleased)'
+    flags: 'i'
+error_messages:
+  - "(No error — workflow simply does not trigger when a pre-release is published via the GitHub UI or API)"
+root_cause: |
+  GitHub's release event distinguishes two separate activity types for publishing:
+  - published: fires when a full (non-pre) release is published (is_prerelease: false)
+  - prereleased: fires when a pre-release is published (is_prerelease: true)
+
+  The published type does NOT include pre-releases. A workflow with
+  types: [published] will never fire when "Set as a pre-release" is checked in
+  the GitHub UI, or when a release is created with prerelease: true via the Releases API.
+
+  This silently skips release automation (npm publish, Docker image push, deployment
+  pipelines) for pre-release versions (e.g., v2.0.0-rc.1, v1.5.0-beta.3).
+  No warning, no skipped-run entry in the Actions tab — the event simply never arrives.
+
+  Note: the created type fires for both releases AND pre-releases when they are first
+  created as drafts, not when published. The released type fires for both
+  published and prereleased events and is the simplest way to catch both.
+fix: |
+  To fire on BOTH full releases and pre-releases: add prereleased to the types list,
+  or switch to types: [released] which fires for both without listing each type.
+
+  To fire ONLY on pre-releases: use types: [prereleased].
+
+  To distinguish inside the workflow: check github.event.release.prerelease (boolean).
+fix_code:
+  - language: yaml
+    label: 'Include prereleased to fire for both full releases and pre-releases'
+    code: |
+      on:
+        release:
+          # published fires only for full releases
+          # prereleased fires only for pre-releases
+          # List both to catch all published releases
+          types: [published, prereleased]
+
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Set dist-tag based on release type
+              id: meta
+              run: |
+                if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+                  echo "dist_tag=next" >> $GITHUB_OUTPUT
+                else
+                  echo "dist_tag=latest" >> $GITHUB_OUTPUT
+                fi
+
+  - language: yaml
+    label: 'Use released to always fire for both release types without listing each'
+    code: |
+      on:
+        release:
+          # released is equivalent to [published, prereleased] — fires for both
+          types: [released]
+prevention:
+  - 'Always include prereleased in types: if pre-release automation is expected (npm publish, Docker push, deploy)'
+  - 'Test release workflows by creating a GitHub pre-release — verify the workflow appears in the Actions tab'
+  - 'Use github.event.release.prerelease (boolean) to branch behavior inside the workflow rather than relying on separate trigger types'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#release'
+    label: 'GitHub Docs: release event and activity types'
+  - url: 'https://docs.github.com/en/rest/releases/releases#create-a-release'
+    label: 'GitHub REST API: Create a release (prerelease field)'

package/errors/triggers/triggers-038.yml

@@ -0,0 +1,126 @@
+id: triggers-038
+title: 'workflow_run.conclusion is null when the upstream run was cancelled before any job started — if: checks silently skip'
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-run
+  - conclusion
+  - cancelled
+  - null-conclusion
+  - if-condition
+  - cross-workflow
+patterns:
+  - regex: 'github\.event\.workflow_run\.conclusion\s*==\s*[''"]success[''"]'
+    flags: 'i'
+  - regex: 'github\.event\.workflow_run\.conclusion\s*==\s*[''"]failure[''"]'
+    flags: 'i'
+error_messages:
+  - "(No error — triggered workflow runs but all jobs/steps with if: github.event.workflow_run.conclusion == 'success' silently skip)"
+root_cause: |
+  When a downstream workflow uses on: workflow_run (types: [completed]), it fires
+  whenever an upstream workflow run reaches a terminal state. The
+  github.event.workflow_run.conclusion field is expected to reflect the outcome of
+  that upstream run.
+
+  However, if the upstream run was cancelled before any job started — for example,
+  due to a concurrent push triggering cancel-in-progress on the queued run, or a
+  manual UI cancellation before the run left the queue — the conclusion field is
+  null, not "cancelled".
+
+  GitHub's API returns: { "conclusion": null, "status": "cancelled" } for runs
+  cancelled while still queued. This is documented behavior: conclusion is only set
+  when at least one job has run to completion.
+
+  The effect on downstream conditional logic:
+    if: github.event.workflow_run.conclusion == 'success'    → false (null != string)
+    if: github.event.workflow_run.conclusion == 'failure'    → false
+    if: github.event.workflow_run.conclusion == 'cancelled'  → also false (null != string)
+    if: github.event.workflow_run.conclusion != 'success'    → TRUE (null != string)
+
+  The downstream workflow's workflow_run completed event fires and the workflow
+  starts, but every job with a success/failure/cancelled equality check is silently
+  skipped. A CD pipeline gated on CI success may appear to trigger but produce no
+  deployment with no error surfaced to the developer.
+
+  This can also silently allow deployment jobs protected by
+  conclusion != 'failure' to run when the upstream was an early cancellation.
+fix: |
+  Treat workflow_run.conclusion as nullable. Always verify it is not null before
+  comparing to an expected value:
+
+  Option A — Explicit null check (most readable):
+    if: github.event.workflow_run.conclusion != null && github.event.workflow_run.conclusion == 'success'
+
+  Option B — contains() with fromJSON allowlist (handles null gracefully; null is
+  not in the list, so the condition evaluates false without error):
+    if: contains(fromJSON('["success"]'), github.event.workflow_run.conclusion)
+
+  Option C — Guard step that fails fast and visibly when conclusion is unexpected,
+  so silent skips become explicit failures:
+    - run: |
+        if [ "$CONCLUSION" != "success" ]; then
+          echo "Upstream conclusion was: $CONCLUSION"
+          exit 1
+        fi
+      env:
+        CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+fix_code:
+  - language: yaml
+    label: 'Use contains() with fromJSON to handle null conclusion safely'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [completed]
+
+      jobs:
+        deploy:
+          # contains() returns false when conclusion is null — no null-equality error
+          if: |
+            contains(fromJSON('["success"]'), github.event.workflow_run.conclusion) &&
+            github.event.workflow_run.head_branch == 'main'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: echo "Deploying after confirmed CI success"
+
+  - language: yaml
+    label: 'Guard step that fails visibly on null or unexpected conclusion'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [completed]
+
+      jobs:
+        verify-conclusion:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check upstream conclusion
+              env:
+                CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+              run: |
+                echo "Upstream workflow conclusion: $CONCLUSION"
+                if [ "$CONCLUSION" != "success" ]; then
+                  echo "Expected 'success', got '$CONCLUSION' (possibly null if cancelled before job start)"
+                  exit 1
+                fi
+
+        deploy:
+          needs: verify-conclusion
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: echo "Deploying"
+prevention:
+  - 'Always treat workflow_run.conclusion as nullable — a run cancelled while queued has conclusion: null, not "cancelled"'
+  - 'Use contains(fromJSON(...), github.event.workflow_run.conclusion) instead of == equality — contains() handles null safely'
+  - 'Add a guard step that prints the actual conclusion value to make silent skips visible during debugging'
+  - 'Prefer repository_dispatch for cross-workflow chaining when you need explicit control over the payload and conclusion semantics'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run event — conclusion field behavior'
+  - url: 'https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#get-a-workflow-run'
+    label: 'GitHub REST API: Workflow run — conclusion is nullable'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github.event.workflow_run context properties'

package/errors/yaml-syntax/yaml-syntax-036.yml

@@ -0,0 +1,100 @@
+id: yaml-syntax-036
+title: 'run-name: using github.event.head_commit.message shows "undefined" for schedule and workflow_dispatch events'
+category: yaml-syntax
+severity: warning
+tags:
+  - run-name
+  - head-commit-message
+  - schedule
+  - workflow-dispatch
+  - null-property
+  - expression
+patterns:
+  - regex: 'run-name:.*head_commit\.message'
+    flags: 'i'
+error_messages:
+  - "(Run title in the UI displays 'undefined' or 'Deploy by @actor from undefined' — no log error is emitted)"
+root_cause: |
+  The run-name: workflow key (introduced October 2022) lets you set a custom title
+  for each workflow run using GitHub Actions expressions. The GitHub Docs examples
+  include the pattern:
+
+    run-name: Deploy by @${{ github.actor }} from ${{ github.event.head_commit.message }}
+
+  However, github.event.head_commit is ONLY populated for on: push events. For
+  on: schedule, on: workflow_dispatch, on: pull_request, on: release, and most other
+  event types, the head_commit object is absent from the event payload. Accessing
+  github.event.head_commit.message on a null object evaluates to '' in some contexts
+  but renders as "undefined" in the Actions UI run title.
+
+  The result is a workflow run title like:
+    "Deploy by @octocat from undefined"
+  or simply "undefined" — confusing in the Actions tab and audit logs.
+
+  The workflow parses without error because the expression is syntactically valid.
+  The problem only surfaces at runtime when a non-push event triggers the workflow.
+  This is especially common in workflows that have both on: push and on: schedule or
+  on: workflow_dispatch triggers.
+fix: |
+  Use the || short-circuit operator to provide fallback values for event types where
+  head_commit is absent. GitHub Actions expressions treat || as a null/false fallback:
+
+    run-name: "${{ github.event.head_commit.message || github.event.inputs.reason || 'Scheduled run' }}"
+
+  Prefer contexts that are populated for ALL event types:
+  - github.actor — always set (the user or app that triggered the run)
+  - github.ref_name — always set (branch or tag short name)
+  - github.run_number — always set (monotonically increasing per workflow)
+  - github.event.inputs.* — set for workflow_dispatch when inputs are defined
+fix_code:
+  - language: yaml
+    label: 'Add || fallback so run-name is readable for all trigger types'
+    code: |
+      name: Deploy
+      # Without || fallback, schedule and workflow_dispatch show "undefined"
+      # github.event.head_commit is ONLY available on push events
+      run-name: "${{ github.event.head_commit.message || github.event.inputs.reason || 'Scheduled run' }}"
+      on:
+        push:
+          branches: [main]
+        schedule:
+          - cron: '0 8 * * 1'
+        workflow_dispatch:
+          inputs:
+            reason:
+              description: 'Reason for manual trigger'
+              required: false
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: 'Use always-populated contexts for a universally safe run-name'
+    code: |
+      name: Deploy
+      # github.actor, github.ref_name, and github.run_number are set for every event
+      run-name: '${{ github.actor }} on ${{ github.ref_name }} (#${{ github.run_number }})'
+      on:
+        push:
+        schedule:
+          - cron: '0 8 * * 1'
+        workflow_dispatch:
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - 'Test run-name expressions against every trigger in your on: block — head_commit is only available for push events'
+  - 'Always provide a || fallback: github.event.head_commit.message || ''Scheduled run'' handles both push and non-push'
+  - 'Prefer github.actor, github.ref_name, and github.run_number — these are populated for every event type'
+  - 'Check context availability in the GitHub Docs contexts reference before using event-specific properties in run-name'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#run-name'
+    label: 'GitHub Docs: Workflow syntax — run-name'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github context — event-specific property availability'
+  - url: 'https://github.blog/changelog/2022-10-05-github-actions-run-name-and-workflow-run-title/'
+    label: 'GitHub Changelog: run-name and workflow run title (October 2022)'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.48",
+  "version": "1.0.50",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",