@htekdev/actions-debugger 1.0.47 → 1.0.49

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

@@ -0,0 +1,96 @@
+id: permissions-auth-036
+title: 'GITHUB_TOKEN cannot push commits to branches protected by "Require signed commits" — token identity cannot sign'
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - signed-commits
+  - branch-protection
+  - gpg
+  - push
+  - protected-branch
+patterns:
+  - regex: 'GH006.*Protected branch.*signed|Commits must have verified signatures'
+    flags: 'i'
+  - regex: 'Changes must be signed|protected branch.*signed.*commits'
+    flags: 'i'
+error_messages:
+  - 'remote: error: GH006: Protected branch update failed for refs/heads/main.'
+  - 'remote: error: Commits must have verified signatures.'
+  - 'remote: error: Changes must be signed.'
+root_cause: |
+  GitHub's "Require signed commits" branch protection rule requires every pushed commit
+  to carry a verified GPG or SSH signature. The GITHUB_TOKEN is a short-lived bearer token
+  scoped to a workflow run — it has no associated GPG or SSH signing key and cannot produce
+  verified commit signatures.
+
+  This means any workflow that creates commits and pushes them using GITHUB_TOKEN will fail
+  on branches protected by "Require signed commits", regardless of the token's permission
+  level. Having contents: write permission is necessary but not sufficient: the signature
+  requirement is enforced by a separate push hook after permission checks pass.
+
+  Common workflow patterns that hit this:
+  - Auto-commit actions (stefanzweifel/auto-commit-action, EndBug/add-and-commit) that
+    commit generated files (changelogs, coverage badges, built assets) back to main
+  - Release workflows that bump version numbers in committed files before tagging
+  - Automated dependency update workflows that commit lockfile changes
+  - Documentation generation workflows that commit generated API docs or OpenAPI specs
+
+  The GH006 error appears in the push step's output but the job may not fail loudly if
+  the step's exit code is not checked carefully. In some auto-commit actions, the failure
+  surfaces as an unexpected empty push with no error surfaced to the workflow summary.
+fix: |
+  Option 1 — Create a pull request instead of direct push (recommended): Use
+  peter-evans/create-pull-request or similar to push the auto-generated commit to a
+  feature branch, then open a PR. Feature branches are not subject to the main branch's
+  "Require signed commits" protection.
+
+  Option 2 — GitHub App with bypass: Create a GitHub App and add it to the branch
+  protection "Allow specific actors to bypass required pull request reviews and required
+  status checks" bypass list. Generate tokens for the App in the workflow and push with
+  the App token. The App's bot commits can bypass the signed-commits requirement if
+  explicitly listed as a bypass actor.
+
+  Option 3 — Signed commits via GitHub App SSH key: Configure a GitHub App with an
+  SSH signing key. Use the App installation token and the App's SSH key for commit
+  signing via GIT_COMMITTER_EMAIL and gpg.format = ssh configuration.
+
+  The GITHUB_TOKEN itself cannot be configured for commit signing — this is a platform
+  limitation with no in-token workaround.
+fix_code:
+  - language: yaml
+    label: 'Create a pull request instead of pushing directly — avoids signed commits requirement on main'
+    code: |
+      jobs:
+        update-generated:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+            pull-requests: write
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Regenerate files
+              run: make generate
+
+            - name: Create pull request for generated output
+              uses: peter-evans/create-pull-request@v7
+              with:
+                commit-message: 'chore: regenerate auto-generated files'
+                branch: automated/regenerate-output
+                title: 'chore: automated file regeneration'
+                body: 'Automated regeneration triggered by CI. Merge after review.'
+                # Commit targets the feature branch, not main — signed-commits rule on
+                # main does not apply to the automated/ branch
+prevention:
+  - 'Before enabling "Require signed commits" on a branch, audit all workflows that push commits using GITHUB_TOKEN to that branch'
+  - 'Use the create-pull-request pattern for auto-generated commits rather than pushing directly to protected branches'
+  - 'Document in workflow files that GITHUB_TOKEN cannot push to branches with signed-commits protection'
+  - 'If a GitHub App bypass is used, rotate the App private key regularly and scope permissions to the minimum required'
+docs:
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-signed-commits'
+    label: 'GitHub Docs: Require signed commits branch protection'
+  - url: 'https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification'
+    label: 'GitHub Docs: About commit signature verification'
+  - url: 'https://github.com/orgs/community/discussions/13836'
+    label: 'GitHub Community #13836: GITHUB_TOKEN cannot push to branch requiring signed commits'

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-103.yml

@@ -0,0 +1,100 @@
+id: runner-environment-103
+title: "actions/setup-go cache skipped with 'no file matched go.sum' when go.sum is absent or not at workspace root"
+category: runner-environment
+severity: warning
+tags:
+  - setup-go
+  - go
+  - cache
+  - go-sum
+  - monorepo
+  - cache-miss
+  - cache-dependency-path
+patterns:
+  - regex: 'No file.*matched.*go\.sum|go\.sum.*not.*found.*cache'
+    flags: 'i'
+  - regex: 'setup-go.*cache.*skip|Unable to find.*go\.sum'
+    flags: 'i'
+error_messages:
+  - 'Warning: No file in /home/runner/work/repo/repo matched to [**/go.sum, !**/vendor/**], make sure you have checked out the target repository'
+  - 'go.sum not found, module cache will not be saved'
+  - 'Cache miss — no go.sum file located at expected path'
+root_cause: |
+  actions/setup-go uses go.sum as the cache key hash source. When cache: true (the default
+  since setup-go@v4), the action runs hashFiles('**/go.sum') to compute the cache key.
+  If no go.sum file is found anywhere in the workspace, the action emits a warning and
+  silently skips saving and restoring the module cache entirely — the job continues with
+  exit 0 but all Go dependencies are downloaded from scratch on every run.
+
+  Common root causes:
+
+  1. New project: go mod tidy has not been run — go.sum does not yet exist in the repo.
+
+  2. Monorepo layout: Go modules live under subdirectories (e.g., services/api/go.sum).
+     The default glob **/go.sum should find nested files, but when combined with the
+     !**/vendor/** exclusion or when the repo structure is non-standard, detection can fail.
+
+  3. Go workspace (go.work): modules are organized under subdirectories managed by a
+     go.work file; individual go.sum files may be present but not at the expected root.
+
+  4. Ordering issue: actions/setup-go runs before actions/checkout, so go.sum is not
+     yet in the workspace when the cache key is computed.
+
+  5. go.sum is listed in .gitignore (non-standard but seen in internal tooling repos
+     that regenerate dependencies on every run).
+
+  The missing-cache warning is only visible in the setup-go step's log output and does
+  not fail the workflow. On large Go projects, silent cache bypass wastes 60-120+ seconds
+  downloading modules from proxy.golang.org on every CI run.
+fix: |
+  For monorepo or nested module layouts, explicitly set cache-dependency-path to the
+  location of the go.sum file(s). A glob pattern can match multiple modules if needed.
+
+  For new projects: run go mod tidy locally and commit go.sum before pushing.
+
+  For go.work workspaces: list each module's go.sum explicitly in cache-dependency-path
+  to ensure all modules participate in the cache key.
+
+  Always confirm actions/checkout runs before actions/setup-go in the steps list.
+fix_code:
+  - language: yaml
+    label: 'Set cache-dependency-path for a nested module in a monorepo'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - uses: actions/setup-go@v5
+          with:
+            go-version: '1.22'
+            cache: true
+            # Explicit path overrides default glob — required when go.sum is not at repo root
+            cache-dependency-path: services/api/go.sum
+
+  - language: yaml
+    label: 'Multiple modules in a go.work workspace — list all go.sum paths'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - uses: actions/setup-go@v5
+          with:
+            go-version: '1.22'
+            cache: true
+            # Multi-line value: each module go.sum contributes to the aggregate cache key
+            cache-dependency-path: |
+              services/api/go.sum
+              services/worker/go.sum
+              pkg/shared/go.sum
+prevention:
+  - 'Always run go mod tidy before the first commit to ensure go.sum exists in the repository'
+  - 'In monorepos, explicitly set cache-dependency-path rather than relying on the default **/go.sum glob'
+  - 'Check the setup-go step output for "No file matched" warnings — caching may be silently disabled without failing the job'
+  - 'Ensure actions/checkout runs before actions/setup-go so go.sum is present when the cache key is computed'
+  - 'Never add go.sum to .gitignore — it is required for reproducible builds and module cache keying'
+docs:
+  - url: 'https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs'
+    label: 'actions/setup-go: Caching dependency files and build outputs'
+  - url: 'https://github.com/actions/setup-go/issues/289'
+    label: 'setup-go #289: Cache fails when go.sum not at repository root'
+  - url: 'https://docs.github.com/en/actions/use-cases-and-examples/building-and-testing/building-and-testing-go'
+    label: 'GitHub Docs: Building and testing Go'

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/silent-failures/silent-failures-051.yml

@@ -0,0 +1,107 @@
+id: silent-failures-051
+title: 'environment.url expression evaluates to empty string when referencing steps.*.outputs — resolved before steps run'
+category: silent-failures
+severity: silent-failure
+tags:
+  - environment
+  - deployment-url
+  - step-outputs
+  - expression-evaluation
+  - dynamic-url
+  - deployment-widget
+patterns:
+  - regex: 'environment.*url.*steps\.\w+\.outputs\.\w+'
+    flags: 'i'
+  - regex: 'deployment.*url.*empty|environment.*url.*not.*set|page_url.*empty'
+    flags: 'i'
+error_messages:
+  - 'Deployment environment shows no URL in GitHub UI despite environment.url referencing a step output'
+  - 'Deployment URL is empty string — steps.deploy.outputs.url is non-empty in the step logs'
+root_cause: |
+  The jobs.<id>.environment.url field is evaluated at job scheduling time — before ANY steps
+  in the job have run and before any step outputs exist. Expressions that reference
+  steps.*.outputs.* from the same job silently resolve to empty string. GitHub does not
+  emit a warning or error when this occurs.
+
+  This is a fundamental evaluation ordering constraint: the environment block (both name and
+  url) is part of the workflow plan GitHub evaluates once when the job is queued. The job
+  has not yet started, so step outputs are undefined and resolve to empty.
+
+  Contexts SAFE to use in environment.url (available at scheduling time):
+  - github.* — static for the run
+  - vars.* — repository/org/environment variables
+  - inputs.* — workflow_dispatch or workflow_call inputs
+  - needs.<prior-job>.outputs.* — outputs from already-completed upstream jobs
+  - env.* declared at the job level
+
+  Contexts that silently resolve to empty in environment.url:
+  - steps.*.outputs.* — step has not run yet
+  - steps.*.conclusion / steps.*.outcome — step has not run yet
+  - Any runtime-computed value from within the same job
+
+  Common scenario: a deploy step creates a preview URL (e.g., Vercel preview, Heroku review
+  app, AWS CloudFormation output), writes it to GITHUB_OUTPUT, and the developer tries to
+  surface it via environment.url so it appears in the GitHub deployment widget on the PR.
+  The widget shows no URL, and no error is ever raised.
+fix: |
+  Route the dynamic deployment URL through job outputs of the deploy job, then reference
+  needs.deploy.outputs.<name> in a dependent job's environment.url. The needs context IS
+  available at scheduling time for downstream jobs because the upstream job has already
+  completed.
+
+  For cases where the URL can be computed entirely from pre-execution contexts (github.ref_name,
+  inputs.*, vars.*), use a static URL expression directly in environment.url without
+  any step output dependency.
+fix_code:
+  - language: yaml
+    label: 'Two-job pattern — expose deployment URL as job output, reference via needs in downstream job'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          outputs:
+            # Promote step output to job output — available to downstream jobs via needs
+            app_url: ${{ steps.deploy.outputs.url }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Deploy
+              id: deploy
+              run: |
+                DEPLOY_URL="https://preview-${{ github.run_id }}.example.com"
+                echo "url=${DEPLOY_URL}" >> $GITHUB_OUTPUT
+
+        link-deployment:
+          needs: deploy
+          runs-on: ubuntu-latest
+          environment:
+            name: preview
+            # needs.deploy.outputs.* resolves correctly — deploy job already completed
+            url: ${{ needs.deploy.outputs.app_url }}
+          steps:
+            - run: echo "Linked deployment to ${{ needs.deploy.outputs.app_url }}"
+
+  - language: yaml
+    label: 'Static URL pattern using pre-execution context (no step output dependency)'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment:
+            name: preview
+            # github.ref_name is available at scheduling time — always resolves correctly
+            url: 'https://preview-${{ github.ref_name }}.example.com'
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "deploying..."
+prevention:
+  - 'Never reference steps.*.outputs.* directly in environment.url — promote to a job output and reference via needs in a downstream job instead'
+  - 'Test environment.url by checking the deployment widget on a pull request — an empty URL indicates the expression evaluated to empty string at scheduling time'
+  - 'Document the two-job deploy-then-link pattern in team workflow templates to prevent rediscovery'
+  - 'If the URL requires a step output, always add an outputs: block to the job and reference it via needs.<job>.outputs.<name> in a downstream job'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment'
+    label: 'GitHub Docs: jobs.<job_id>.environment syntax'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'GitHub Docs: Passing information between jobs'
+  - url: 'https://github.com/orgs/community/discussions/9366'
+    label: 'GitHub Community #9366: Dynamic environment URL from step output resolves to empty'

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-036.yml

@@ -0,0 +1,73 @@
+id: triggers-036
+title: 'branches-ignore filter does not suppress tag pushes — tags always fire unless tags-ignore is also specified'
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - branches-ignore
+  - tags
+  - tag-push
+  - filter
+  - trigger-bypass
+patterns:
+  - regex: 'on.*push.*branches-ignore|branches-ignore.*\*\*'
+    flags: 'i'
+  - regex: 'tag.*push.*trigger.*unexpected|branches-ignore.*tags.*still.*fire'
+    flags: 'i'
+error_messages:
+  - "Workflow triggered by tag push despite branches-ignore: ['**'] — expected no branch pushes to trigger"
+  - 'v1.2.3 tag push fires a workflow that should only run on branch pushes'
+root_cause: |
+  GitHub Actions push event filters (branches:, branches-ignore:, paths:, paths-ignore:) apply
+  only to branch-ref pushes. Tag pushes target a refs/tags/* ref, not a refs/heads/* ref, and
+  are entirely unaffected by branch filters.
+
+  When a workflow declares on: push with branches-ignore: but no tags: or tags-ignore: filter,
+  all tag pushes trigger the workflow unconditionally regardless of the branch filter.
+
+  A critical misunderstanding: adding branches-ignore: ['**'] looks like it "disables all push
+  triggers" but it only disables branch pushes. Tag pushes still fire unconditionally.
+
+  GitHub documentation states that push event filters are independent per ref type: branch
+  filters only affect refs/heads/* pushes, and tag filters only affect refs/tags/* pushes.
+  They do not compose across ref types — setting one does not implicitly filter the other.
+
+  Consequence: release tag pushes (v1.2.3) trigger CI and CD workflows not designed for them,
+  potentially running expensive test suites or deploying artifacts on every version tag.
+  This is among the top-voted GitHub Community questions about push event triggers and
+  appears repeatedly in Stack Overflow answers on the [github-actions] tag.
+fix: |
+  Add an explicit tags-ignore: ['**'] filter to prevent all tag pushes from triggering the
+  workflow. Alternatively, use an explicit branches: allowlist — but note that branch
+  allowlists also do not suppress tag pushes; tags-ignore: is always required separately.
+
+  For workflows intended ONLY for tags (release workflows), remove branches filters entirely
+  and add tags: with the desired semver glob pattern.
+fix_code:
+  - language: yaml
+    label: 'Add tags-ignore to explicitly suppress all tag pushes alongside branches-ignore'
+    code: |
+      on:
+        push:
+          branches-ignore:
+            - 'dependabot/**'
+          tags-ignore:
+            - '**'    # Required — branches-ignore does NOT suppress tag pushes
+  - language: yaml
+    label: 'Release workflow — run only on semver tags, no branch triggers'
+    code: |
+      on:
+        push:
+          tags:
+            - 'v[0-9]+.[0-9]+.[0-9]+'    # Only fires on semver tags like v1.2.3
+          # No branches filter — exclusive tag-only trigger
+prevention:
+  - "When adding branches or branches-ignore filters, always decide explicitly whether tag pushes should be included or excluded — then set tags: or tags-ignore: accordingly"
+  - 'Use actionlint to validate push trigger filter combinations before committing'
+  - 'Document the intent in workflow comments: "This workflow runs on branch pushes only. Tag pushes excluded via tags-ignore."'
+  - 'Audit release tag workflows to confirm they use tags: filters rather than relying on implicit gaps in branch filters'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push'
+    label: 'GitHub Docs: push event — filter pattern cheat sheet'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
+    label: 'GitHub Docs: on.push branches/tags filter syntax'

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/package.json

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