@htekdev/actions-debugger 1.0.95 → 1.0.96

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

@@ -0,0 +1,90 @@
+id: caching-artifacts-053
+title: "download-artifact@v4 finds no artifacts in workflow_run context without run-id"
+category: caching-artifacts
+severity: error
+tags:
+  - download-artifact
+  - workflow_run
+  - run-id
+  - cross-workflow
+  - artifact
+patterns:
+  - regex: 'No artifacts found'
+    flags: 'i'
+  - regex: 'Unable to find any artifacts for the associated workflow'
+    flags: 'i'
+error_messages:
+  - "No artifacts found for the associated workflow run"
+  - "Unable to find any artifacts for the associated workflow"
+  - "Error: Unable to find any artifacts for the associated workflow run"
+root_cause: |
+  `actions/download-artifact@v4` defaults to downloading artifacts from the
+  CURRENT workflow run (`github.run_id`). In a `workflow_run`-triggered
+  workflow, the current run is the downstream (deploy) workflow — which has
+  produced no artifacts. The upstream (build) workflow's artifacts belong to
+  the triggering run, identified by `github.event.workflow_run.id`.
+
+  Without setting `run-id: ${{ github.event.workflow_run.id }}`, the download
+  step searches the current run's artifacts, finds nothing, and either fails
+  with "No artifacts found" or silently exits (depending on `if-no-files-found`
+  setting). No artifact was ever associated with the downstream run, so the
+  error can be confusing — the artifact clearly exists in the Actions UI under
+  the upstream run.
+
+  This is a distinct issue from the cross-run permissions error (ca-040):
+  that occurs when `run-id` IS set but `actions: read` permission is missing.
+  This issue occurs when `run-id` is simply not set at all.
+fix: |
+  Set `run-id: ${{ github.event.workflow_run.id }}` on the download step to
+  target the triggering workflow's run. Also provide `github-token` (required
+  for cross-run downloads) and ensure `actions: read` permission is set.
+fix_code:
+  - language: yaml
+    label: "Correct: set run-id from triggering workflow in workflow_run context"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      permissions:
+        actions: read
+        contents: read
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download build artifacts
+              uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                # Required: point to the upstream run, not the current run
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Deploy
+              run: echo "Deploying from artifact"
+  - language: yaml
+    label: "Incorrect: missing run-id causes 'No artifacts found'"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download build artifacts
+              uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                # Missing run-id — searches the CURRENT run, which has no artifacts
+prevention:
+  - "In any `workflow_run`-triggered workflow, always set `run-id: ${{ github.event.workflow_run.id }}`"
+  - "Pair with `github-token: ${{ secrets.GITHUB_TOKEN }}` and `permissions: actions: read`"
+  - "Verify artifacts exist under the triggering run via the Actions UI before debugging download steps"
+  - "Name artifacts consistently between upload (in CI) and download (in deploy) workflows"
+docs:
+  - url: "https://github.com/actions/download-artifact?tab=readme-ov-file#download-artifacts-from-other-workflow-runs-or-repositories"
+    label: "actions/download-artifact: Downloading from other workflow runs"
+  - 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"

package/errors/concurrency-timing/concurrency-timing-045.yml

@@ -0,0 +1,70 @@
+id: concurrency-timing-045
+title: "workflow_run-triggered workflows run concurrently — no upstream concurrency linkage"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - workflow_run
+  - concurrency
+  - deployment
+  - build-deploy-pipeline
+  - downstream-workflow
+patterns:
+  - regex: 'on:\s+workflow_run:'
+    flags: 'si'
+error_messages:
+  - "Multiple deployments triggered simultaneously for the same branch"
+  - "Deploy workflow triggered concurrently"
+root_cause: |
+  Workflows triggered via `on: workflow_run:` do not inherit any concurrency
+  group from the triggering (upstream) workflow. If multiple upstream runs
+  complete in quick succession — for example, two commits pushed rapidly — each
+  `completed` event spawns an independent downstream run. All downstream runs
+  execute concurrently with no serialization or cancellation, even when the
+  upstream workflow had a concurrency group that serialized upstream runs.
+
+  The downstream workflow runs in the context of the default branch and receives
+  the triggering run's metadata via `github.event.workflow_run.*`, but GitHub
+  does not propagate any concurrency scope from upstream to downstream.
+
+  For build-then-deploy pipelines this creates a race condition: two deploy runs
+  may begin simultaneously, with whichever finishes last determining the final
+  deployed state regardless of commit order.
+fix: |
+  Add an explicit `concurrency:` block to the `workflow_run`-triggered workflow,
+  keyed on `github.event.workflow_run.head_branch` to scope per branch.
+
+  Use `cancel-in-progress: true` for idempotent deploys (only the latest commit
+  matters) or `cancel-in-progress: false` for non-idempotent operations that
+  must complete once queued.
+fix_code:
+  - language: yaml
+    label: "Add explicit concurrency group to workflow_run-triggered deploy workflow"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          branches: [main]
+
+      # Without this block, concurrent CI completions spawn concurrent deploys
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: echo "Deploying ${{ github.event.workflow_run.head_sha }}"
+prevention:
+  - "Always define an explicit `concurrency:` block in `workflow_run`-triggered workflows"
+  - "Key the concurrency group on `github.event.workflow_run.head_branch` to scope by branch"
+  - "For CI-to-deploy pipelines, use `cancel-in-progress: true` so only the latest commit deploys"
+  - "Consider consolidating CI and deploy into a single workflow using `needs:` if elevated permissions are not required"
+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"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/controlling-workflow-and-job-execution"
+    label: "GitHub Docs: Controlling workflow and job execution (concurrency)"

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

@@ -0,0 +1,99 @@
+id: permissions-auth-054
+title: "OIDC sub claim format changes when environment: block added — IdP trust policy breaks"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - environment
+  - aws
+  - gcp
+  - azure
+  - sub-claim
+  - trust-policy
+  - deployment-protection
+patterns:
+  - regex: 'Not authorized to perform sts:AssumeRoleWithWebIdentity'
+    flags: 'i'
+  - regex: 'Error: Credentials could not be loaded'
+    flags: 'i'
+  - regex: 'Permission.*denied.*generateAccessToken|WorkloadIdentityPool.*rejected'
+    flags: 'i'
+error_messages:
+  - "Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers"
+  - "Permission 'iam.serviceAccounts.getOpenIdToken' denied on resource"
+  - "The provided token could not be validated"
+root_cause: |
+  GitHub Actions OIDC token `sub` (subject) claim format depends on whether the
+  job has an `environment:` key. Without an environment, the subject is:
+    `repo:OWNER/REPO:ref:refs/heads/BRANCH`
+
+  When `environment: production` is present on the job, the format changes to:
+    `repo:OWNER/REPO:environment:production`
+
+  The branch/ref component is replaced entirely by the environment name. AWS IAM
+  role trust policies, GCP Workload Identity Federation conditions, and Azure
+  federated credential filters that matched the branch-ref format now receive a
+  token with a different sub claim and reject the OIDC exchange with a 403 or
+  permission-denied error.
+
+  This commonly occurs when a team adds environment protection rules (required
+  reviewers, wait timers) to an existing workflow that already had OIDC
+  credentials working. CI passes before adding `environment:` but fails after.
+fix: |
+  Update the IdP trust policy to match the new subject format containing the
+  environment name. Options:
+  1. Narrow to environment: change the condition to match
+     `repo:OWNER/REPO:environment:production`.
+  2. Use a wildcard: match `repo:OWNER/REPO:*` to accept both formats (less secure).
+  3. GitHub subject claim customization (Enterprise): define a consistent sub
+     claim format that does not change based on environment presence.
+fix_code:
+  - language: yaml
+    label: "Workflow: annotate environment and required OIDC permissions"
+    code: |
+      permissions:
+        id-token: write
+        contents: read
+
+      jobs:
+        deploy:
+          # Adding this key changes the OIDC sub claim format — update IdP trust policy
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/DeployRole
+                aws-region: us-east-1
+                # AWS trust policy must now use:
+                # "token.actions.githubusercontent.com:sub":
+                #   "StringEquals": "repo:org/repo:environment:production"
+                # (not "repo:org/repo:ref:refs/heads/main")
+  - language: yaml
+    label: "AWS IAM trust policy: match environment sub claim"
+    code: |
+      # AWS IAM Role Trust Policy — update Condition after adding environment:
+      # Before (no environment):
+      #   "token.actions.githubusercontent.com:sub": "repo:org/repo:ref:refs/heads/main"
+      #
+      # After (with environment: production):
+      #   "token.actions.githubusercontent.com:sub": "repo:org/repo:environment:production"
+      #
+      # Wildcard to accept both (less restrictive):
+      #   "token.actions.githubusercontent.com:sub":
+      #     StringLike: "repo:org/repo:*"
+      #
+      # GCP: update attribute.repository_environment or use attribute mapping
+prevention:
+  - "Before adding `environment:` to a job using OIDC, audit and update all IdP trust policies"
+  - "Document the expected sub claim format in trust policy comments to avoid future confusion"
+  - "Use GitHub's OIDC token debugger step to inspect the actual sub claim at runtime"
+  - "For consistent sub format across environment and non-environment jobs, consider subject claim customization"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#filtering-for-a-specific-environment"
+    label: "GitHub Docs: OIDC filtering for a specific environment"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository"
+    label: "GitHub Docs: Customizing subject claims"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services"
+    label: "GitHub Docs: Configuring OIDC in AWS"

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

@@ -0,0 +1,93 @@
+id: yaml-syntax-059
+title: "needs: key does not accept runtime expressions — must be static job IDs"
+category: yaml-syntax
+severity: error
+tags:
+  - needs
+  - expressions
+  - dynamic-jobs
+  - job-dependencies
+  - parse-time
+  - actionlint
+patterns:
+  - regex: "The pipeline is not valid.*needs|needs.*references.*job.*does not exist"
+    flags: 'i'
+  - regex: 'Unrecognized named-value.*steps.*in needs|needs.*invalid.*expression'
+    flags: 'i'
+error_messages:
+  - "The pipeline is not valid. Job 'deploy' needs 'steps' which does not exist"
+  - "Unrecognized named-value: 'steps'"
+  - "Job 'X' depends on unknown job '${{ fromJSON(...) }}'"
+  - "needs: field value '${{ ... }}' is not a valid job identifier"
+root_cause: |
+  The `needs:` key in a GitHub Actions job definition must contain static job ID
+  strings. It is evaluated at workflow parse time — before any step or job runs
+  — so runtime expressions such as `${{ steps.gen.outputs.jobs }}` or
+  `${{ fromJSON(env.DYNAMIC_JOBS) }}` are not evaluated. They are treated as
+  literal strings, and since no job with that literal name exists, GitHub reports
+  a validation error or the dependency is silently ignored.
+
+  This surprises developers who successfully use `fromJSON()` in `matrix:` or
+  `env:` blocks (which ARE expression-capable) and assume `needs:` works the
+  same way. The difference is that the job dependency graph must be fully
+  resolved before execution begins; expressions in `needs:` would create a
+  circular dependency at parse time.
+
+  actionlint statically detects this and reports: "needs: field cannot be
+  computed by a dynamic value. Use a literal value instead."
+fix: |
+  Job dependencies must be statically defined. Use one of these patterns:
+  1. List all potential dependent jobs statically; use `if:` conditions on
+     each downstream job to skip those not needed.
+  2. Use a matrix fan-out + fan-in pattern where the fan-in job has a single
+     static `needs:` on the matrix job name (not individual matrix legs).
+  3. Restructure so the dependency graph is known at workflow authoring time.
+fix_code:
+  - language: yaml
+    label: "Correct: static needs: with if: conditions to control execution"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            should_deploy: ${{ steps.check.outputs.deploy }}
+          steps:
+            - id: check
+              run: echo "deploy=true" >> $GITHUB_OUTPUT
+
+        deploy:
+          # Static needs: always declared; if: controls whether it runs
+          needs: [build]
+          if: needs.build.outputs.should_deploy == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+  - language: yaml
+    label: "Incorrect: expression in needs: causes parse-time validation error"
+    code: |
+      jobs:
+        generate:
+          runs-on: ubuntu-latest
+          outputs:
+            jobs: ${{ steps.list.outputs.jobs }}
+          steps:
+            - id: list
+              run: echo 'jobs=["build","lint"]' >> $GITHUB_OUTPUT
+
+        # ERROR: needs: does not evaluate expressions — this is a parse-time failure
+        deploy:
+          needs: ${{ fromJSON(needs.generate.outputs.jobs) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "this never runs"
+prevention:
+  - "Always use static job ID string literals in `needs:` — no expressions, no fromJSON()"
+  - "Use actionlint to pre-validate workflows before pushing: it catches invalid expression contexts"
+  - "For dynamic fan-in, depend on the matrix job name itself, not individual matrix leg names"
+  - "Use `if: contains(needs.*.result, 'failure')` for conditional logic after static needs"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds"
+    label: "GitHub Docs: jobs.<job_id>.needs"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint: Static checker for GitHub Actions workflow files"
+

package/package.json

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