@htekdev/actions-debugger 1.0.0 → 1.0.1

package/errors/permissions-auth/github-token-protected-branch-push.yml

@@ -0,0 +1,109 @@
+id: permissions-auth-006
+title: "GITHUB_TOKEN Cannot Push to Branch Protected by Required Reviews or Status Checks"
+category: permissions-auth
+severity: error
+tags:
+  - GITHUB_TOKEN
+  - branch-protection
+  - push
+  - protected-branch
+  - required-reviews
+  - bypass
+patterns:
+  - regex: "refusing to allow a GitHub App to create or update file"
+    flags: "i"
+  - regex: "protected branch hook declined"
+    flags: "i"
+  - regex: "required status check.*has not run"
+    flags: "i"
+  - regex: "GH006"
+    flags: "i"
+  - regex: "remote: error: GH006: Protected branch update failed"
+    flags: "i"
+error_messages:
+  - "remote: error: GH006: Protected branch update failed for refs/heads/main."
+  - "remote: error: Required status check \"ci\" has not run yet."
+  - "remote: error: At least 1 approving review is required by reviewers with write access."
+  - "Error: refusing to allow a GitHub App to create or update file"
+root_cause: |
+  `GITHUB_TOKEN` is a GitHub App installation token scoped to the workflow's repository.
+  It respects all branch protection rules, including:
+  - Required pull request reviews
+  - Required status checks
+  - Restrictions on who can push directly
+
+  When a workflow attempts to push directly to `main` (or another protected branch) using
+  `GITHUB_TOKEN`, GitHub rejects the push with GH006 if any of these conditions are not met.
+  This is a frequent surprise when automation workflows (bump version, update changelog,
+  auto-merge) try to push directly to a protected branch.
+
+  This is intentional — `GITHUB_TOKEN` does NOT have the ability to bypass branch
+  protections the way a classic PAT from a repository admin might.
+fix: |
+  Use a dedicated machine account PAT or a GitHub App token with bypass permission
+  granted explicitly in the branch protection rule, or restructure the workflow to create
+  a PR instead of pushing directly. For auto-merge patterns, prefer enabling auto-merge
+  on the PR itself.
+fix_code:
+  - language: yaml
+    label: "WRONG — pushing directly to protected main"
+    code: |
+      jobs:
+        bump-version:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Bump version
+              run: |
+                npm version patch
+                git push origin main   # fails: GH006 protected branch
+              env:
+                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "CORRECT — create a PR instead of pushing directly"
+    code: |
+      jobs:
+        bump-version:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+            pull-requests: write
+          steps:
+            - uses: actions/checkout@v4
+            - name: Bump version
+              run: npm version patch
+
+            - name: Create PR for version bump
+              uses: peter-evans/create-pull-request@v6
+              with:
+                token: ${{ secrets.GITHUB_TOKEN }}
+                branch: automated/version-bump
+                title: "chore: automated version bump"
+                commit-message: "chore: bump version"
+  - language: yaml
+    label: "CORRECT — use a PAT with bypass permission"
+    code: |
+      jobs:
+        bump-version:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.BOT_PAT }}   # PAT from bot account with bypass permission
+            - name: Push to protected branch
+              run: |
+                git config user.email "bot@example.com"
+                git config user.name "Automation Bot"
+                npm version patch
+                git push origin main
+prevention:
+  - "Prefer creating PRs for automated changes instead of pushing directly to protected branches."
+  - "Document which bot accounts have branch protection bypass and require PR reviews for those grants."
+  - "Consider `rulesets` (GitHub Enterprise) instead of classic branch protection — they have more granular bypass configurations."
+docs:
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches"
+    label: "About protected branches"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication"
+    label: "Automatic token authentication (GITHUB_TOKEN)"
+  - url: "https://github.com/peter-evans/create-pull-request"
+    label: "peter-evans/create-pull-request action"

package/errors/permissions-auth/oidc-aws-failure.yml

@@ -1,85 +1,85 @@
-id: permissions-auth-002
-title: "OIDC Federation Failures with AWS"
-category: permissions-auth
-severity: error
-tags:
-  - oidc
-  - aws
-  - sts
-  - iam
-  - federation
-patterns:
-  - regex: "Not authorized to perform sts:AssumeRoleWithWebIdentity"
-    flags: "i"
-  - regex: "InvalidIdentityToken"
-    flags: "i"
-  - regex: "No OpenIDConnect provider found in your account"
-    flags: "i"
-  - regex: "audience.*sts\\.amazonaws\\.com"
-    flags: "i"
-error_messages:
-  - "Not authorized to perform sts:AssumeRoleWithWebIdentity"
-  - "InvalidIdentityToken"
-  - "No OpenIDConnect provider found in your account"
-root_cause: |
-  GitHub's OIDC token must match the AWS IAM trust policy exactly. Failures usually come
-  from one of three mismatches: the workflow is missing `id-token: write`, the IAM role
-  trust policy expects the wrong `aud` value, or the `sub` claim does not match the repo,
-  branch, environment, or tag that is actually requesting the token.
-
-  Any one of those mismatches is enough for AWS STS to reject the federation request.
-fix: |
-  Grant `id-token: write`, verify the GitHub OIDC provider exists in AWS, and align the IAM
-  trust policy's `aud` and `sub` conditions with the workflow that is assuming the role.
-fix_code:
-  - language: yaml
-    label: "Grant OIDC permission in the workflow"
-    code: |
-      permissions:
-        id-token: write
-        contents: read
-
-      jobs:
-        deploy:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - uses: aws-actions/configure-aws-credentials@v4
-              with:
-                role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
-                aws-region: us-east-1
-  - language: json
-    label: "Example AWS trust policy for GitHub OIDC"
-    code: |
-      {
-        "Version": "2012-10-17",
-        "Statement": [
-          {
-            "Effect": "Allow",
-            "Principal": {
-              "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
-            },
-            "Action": "sts:AssumeRoleWithWebIdentity",
-            "Condition": {
-              "StringEquals": {
-                "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
-              },
-              "StringLike": {
-                "token.actions.githubusercontent.com:sub": "repo:owner/repo:ref:refs/heads/main"
-              }
-            }
-          }
-        ]
-      }
-prevention:
-  - "Treat the OIDC `aud` and `sub` claims as part of your contract and document them with the role."
-  - "Test branch, tag, and environment-specific subjects before rolling OIDC out broadly."
-  - "Always include `id-token: write` when using cloud federation from GitHub Actions."
-docs:
-  - url: "https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services"
-    label: "Configuring OpenID Connect in Amazon Web Services"
-  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect"
-    label: "About security hardening with OpenID Connect"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "OIDC federation with AWS"
+id: permissions-auth-002
+title: "OIDC Federation Failures with AWS"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - aws
+  - sts
+  - iam
+  - federation
+patterns:
+  - regex: "Not authorized to perform sts:AssumeRoleWithWebIdentity"
+    flags: "i"
+  - regex: "InvalidIdentityToken"
+    flags: "i"
+  - regex: "No OpenIDConnect provider found in your account"
+    flags: "i"
+  - regex: "audience.*sts\\.amazonaws\\.com"
+    flags: "i"
+error_messages:
+  - "Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "InvalidIdentityToken"
+  - "No OpenIDConnect provider found in your account"
+root_cause: |
+  GitHub's OIDC token must match the AWS IAM trust policy exactly. Failures usually come
+  from one of three mismatches: the workflow is missing `id-token: write`, the IAM role
+  trust policy expects the wrong `aud` value, or the `sub` claim does not match the repo,
+  branch, environment, or tag that is actually requesting the token.
+
+  Any one of those mismatches is enough for AWS STS to reject the federation request.
+fix: |
+  Grant `id-token: write`, verify the GitHub OIDC provider exists in AWS, and align the IAM
+  trust policy's `aud` and `sub` conditions with the workflow that is assuming the role.
+fix_code:
+  - language: yaml
+    label: "Grant OIDC permission in the workflow"
+    code: |
+      permissions:
+        id-token: write
+        contents: read
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
+                aws-region: us-east-1
+  - language: json
+    label: "Example AWS trust policy for GitHub OIDC"
+    code: |
+      {
+        "Version": "2012-10-17",
+        "Statement": [
+          {
+            "Effect": "Allow",
+            "Principal": {
+              "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
+            },
+            "Action": "sts:AssumeRoleWithWebIdentity",
+            "Condition": {
+              "StringEquals": {
+                "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+              },
+              "StringLike": {
+                "token.actions.githubusercontent.com:sub": "repo:owner/repo:ref:refs/heads/main"
+              }
+            }
+          }
+        ]
+      }
+prevention:
+  - "Treat the OIDC `aud` and `sub` claims as part of your contract and document them with the role."
+  - "Test branch, tag, and environment-specific subjects before rolling OIDC out broadly."
+  - "Always include `id-token: write` when using cloud federation from GitHub Actions."
+docs:
+  - url: "https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services"
+    label: "Configuring OpenID Connect in Amazon Web Services"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect"
+    label: "About security hardening with OpenID Connect"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "OIDC federation with AWS"

package/errors/permissions-auth/oidc-azure-subject-mismatch.yml

@@ -0,0 +1,91 @@
+id: permissions-auth-007
+title: "OIDC Azure Federated Credential Subject Claim Mismatch"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - azure
+  - federated-identity
+  - subject-claim
+  - entra-id
+  - workload-identity
+patterns:
+  - regex: "AADSTS70021"
+    flags: "i"
+  - regex: "No matching federated identity record found"
+    flags: "i"
+  - regex: "federated credential.*subject.*does not match"
+    flags: "i"
+  - regex: "AADSTS70021: No matching federated identity record found for presented assertion"
+    flags: "i"
+error_messages:
+  - "AADSTS70021: No matching federated identity record found for presented assertion subject"
+  - "ClientAuthenticationFailed: AADSTS70021: No matching federated identity record found for presented assertion subject 'repo:owner/repo:ref:refs/heads/feature-branch'"
+root_cause: |
+  Azure Entra ID (formerly Azure AD) federated credentials for GitHub Actions use the
+  OIDC token's `sub` (subject) claim to verify the caller's identity. The `sub` claim
+  is constructed from the workflow's context: repository, ref type (branch, tag,
+  environment, or pull_request), and the specific value.
+
+  The federated credential in Azure must be configured with an entity type and value that
+  **exactly matches** the subject claim of the token GitHub issues. A mismatch on any
+  component — wrong branch name, missing environment, entity type set to `Branch` when
+  the workflow runs from a `pull_request` — causes Azure to reject the token with
+  AADSTS70021.
+
+  Common mismatches:
+  - Entity type set to `Branch: main` but workflow runs from a PR or tag
+  - Using an `environment:` in the workflow job but the federated credential entity type
+    is `Branch` not `Environment`
+  - Repo name case mismatch (Azure is case-sensitive, GitHub is not)
+fix: |
+  Ensure the federated credential's entity type and value exactly match the workflow
+  context. For workflows that run across multiple refs, create one federated credential
+  per entity type (branch, tag, environment, PR) or use the `*` wildcard where supported.
+fix_code:
+  - language: yaml
+    label: "Workflow using environment — federated credential must use entity type Environment"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: production        # subject: repo:owner/repo:environment:production
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: azure/login@v2
+              with:
+                client-id: ${{ secrets.AZURE_CLIENT_ID }}
+                tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+                subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+  - language: json
+    label: "Azure federated credential — must use Environment entity type"
+    code: |
+      {
+        "name": "github-actions-production",
+        "subject": "repo:myorg/myrepo:environment:production",
+        "issuer": "https://token.actions.githubusercontent.com",
+        "audiences": ["api://AzureADTokenExchange"]
+      }
+  - language: json
+    label: "Azure federated credential — branch push (no environment)"
+    code: |
+      {
+        "name": "github-actions-main-branch",
+        "subject": "repo:myorg/myrepo:ref:refs/heads/main",
+        "issuer": "https://token.actions.githubusercontent.com",
+        "audiences": ["api://AzureADTokenExchange"]
+      }
+prevention:
+  - "Print the OIDC token subject before `azure/login` to debug mismatches: `run: echo '${{ toJSON(github) }}' | jq .token_id`"
+  - "Create separate federated credentials for each entity type: one for branches, one per environment, one for tags."
+  - "Repo and org names in the subject claim are case-sensitive in Azure — match them exactly."
+  - "Use `azure/login@v2 --debug` flag to see the exact subject claim being presented."
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure"
+    label: "Configuring OpenID Connect in Azure"
+  - url: "https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust"
+    label: "Configure a federated identity credential (Microsoft Learn)"
+  - url: "https://learn.microsoft.com/en-us/entra/identity-platform/error-codes#aadsts70021"
+    label: "AADSTS70021 error code reference"

package/errors/runner-environment/disk-space.yml

@@ -1,57 +1,57 @@
-id: runner-environment-002
-title: "Runner Out of Disk Space"
-category: runner-environment
-severity: error
-tags:
-  - runner
-  - disk-space
-  - docker
-  - enospc
-  - ubuntu-latest
-patterns:
-  - regex: "No space left on device"
-    flags: "i"
-  - regex: "ENOSPC"
-    flags: "i"
-  - regex: "write .+ no space left on device"
-    flags: "i"
-error_messages:
-  - "No space left on device"
-  - "ENOSPC: no space left on device"
-root_cause: |
-  GitHub-hosted runners have finite disk space, and large Docker layers, Android SDKs,
-  toolchains, browser caches, or build artifacts can exhaust it mid-job. This frequently
-  shows up on `ubuntu-latest` when workflows build containers or multiple large targets.
-
-  The underlying job logic may be correct, but the runner image simply runs out of storage.
-fix: |
-  Free disk space early in the job, reduce artifact retention, and avoid downloading heavy
-  toolchains you do not need. If the workload is consistently too large, move the job to a
-  larger runner or split the build across jobs.
-fix_code:
-  - language: yaml
-    label: "Free disk space before heavy build steps"
-    code: |
-      jobs:
-        build:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - uses: jlumbroso/free-disk-space@v1
-              with:
-                large-packages: true
-                docker-images: true
-                tool-cache: false
-            - run: docker build -t app .
-prevention:
-  - "Measure disk usage before and after large build steps with `df -h`."
-  - "Delete temporary artifacts and caches you do not need inside the job."
-  - "Avoid monolithic jobs that build every target on one runner."
-docs:
-  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners"
-    label: "About GitHub-hosted runners"
-  - url: "https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job"
-    label: "Choosing the runner for a job"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Runner disk space exhaustion"
+id: runner-environment-002
+title: "Runner Out of Disk Space"
+category: runner-environment
+severity: error
+tags:
+  - runner
+  - disk-space
+  - docker
+  - enospc
+  - ubuntu-latest
+patterns:
+  - regex: "No space left on device"
+    flags: "i"
+  - regex: "ENOSPC"
+    flags: "i"
+  - regex: "write .+ no space left on device"
+    flags: "i"
+error_messages:
+  - "No space left on device"
+  - "ENOSPC: no space left on device"
+root_cause: |
+  GitHub-hosted runners have finite disk space, and large Docker layers, Android SDKs,
+  toolchains, browser caches, or build artifacts can exhaust it mid-job. This frequently
+  shows up on `ubuntu-latest` when workflows build containers or multiple large targets.
+
+  The underlying job logic may be correct, but the runner image simply runs out of storage.
+fix: |
+  Free disk space early in the job, reduce artifact retention, and avoid downloading heavy
+  toolchains you do not need. If the workload is consistently too large, move the job to a
+  larger runner or split the build across jobs.
+fix_code:
+  - language: yaml
+    label: "Free disk space before heavy build steps"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: jlumbroso/free-disk-space@v1
+              with:
+                large-packages: true
+                docker-images: true
+                tool-cache: false
+            - run: docker build -t app .
+prevention:
+  - "Measure disk usage before and after large build steps with `df -h`."
+  - "Delete temporary artifacts and caches you do not need inside the job."
+  - "Avoid monolithic jobs that build every target on one runner."
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners"
+  - url: "https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job"
+    label: "Choosing the runner for a job"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner disk space exhaustion"

package/errors/runner-environment/docker-buildx-not-setup.yml

@@ -0,0 +1,106 @@
+id: runner-environment-014
+title: "Docker BuildKit / buildx Not Enabled by Default — Legacy Build Flags Fail"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - buildx
+  - BuildKit
+  - multi-platform
+  - cache-from
+  - runner
+  - container
+patterns:
+  - regex: "buildx.*not found"
+    flags: "i"
+  - regex: "failed to solve.*no matching manifest"
+    flags: "i"
+  - regex: "DOCKER_BUILDKIT.*invalid"
+    flags: "i"
+  - regex: "multi-platform build is not supported"
+    flags: "i"
+  - regex: "unknown flag: --platform"
+    flags: "i"
+error_messages:
+  - "ERROR: multiple platforms feature is currently not supported for docker driver."
+  - "error: failed to solve: no matching manifest for linux/arm64 in the manifest list entries"
+  - "unknown flag: --platform"
+  - "docker: 'buildx' is not a docker command."
+root_cause: |
+  GitHub Actions runners ship with Docker installed, but the default `docker` driver
+  does not support multi-platform builds (`--platform linux/arm64,linux/amd64`) or
+  advanced BuildKit features like `--cache-from=type=gha`. These require the `docker-container`
+  driver via `docker buildx`.
+
+  On Ubuntu runners, `DOCKER_BUILDKIT=1` is available but `buildx` multi-platform support
+  requires a buildx builder instance to be set up explicitly. When workflows use
+  `docker/build-push-action@v5` or `docker buildx build` without first running
+  `docker/setup-buildx-action`, the build fails with driver capability errors.
+
+  Additionally, `cache-from: type=gha` (GitHub Actions cache) only works with the
+  BuildKit `docker-container` driver — it fails silently or errors on the default `docker`
+  driver.
+fix: |
+  Always call `docker/setup-buildx-action` before any `docker buildx` command or before
+  using `docker/build-push-action`. For multi-platform builds, pass the platform list
+  to the setup step.
+fix_code:
+  - language: yaml
+    label: "WRONG — multi-platform build without buildx setup"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Build multi-platform image
+          run: |
+            docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .
+            # ERROR: multiple platforms feature is currently not supported for docker driver
+  - language: yaml
+    label: "CORRECT — setup buildx before multi-platform build"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - name: Set up Docker Buildx
+          uses: docker/setup-buildx-action@v3   # creates docker-container driver
+
+        - name: Login to registry
+          uses: docker/login-action@v3
+          with:
+            registry: ghcr.io
+            username: ${{ github.actor }}
+            password: ${{ secrets.GITHUB_TOKEN }}
+
+        - name: Build and push
+          uses: docker/build-push-action@v6
+          with:
+            context: .
+            platforms: linux/amd64,linux/arm64
+            push: true
+            tags: ghcr.io/${{ github.repository }}:latest
+            cache-from: type=gha
+            cache-to: type=gha,mode=max
+  - language: yaml
+    label: "CORRECT — single platform with GHA cache (still needs buildx)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: docker/setup-buildx-action@v3
+        - uses: docker/build-push-action@v6
+          with:
+            context: .
+            push: false
+            load: true
+            tags: myapp:test
+            cache-from: type=gha
+            cache-to: type=gha,mode=max
+prevention:
+  - "Always add `docker/setup-buildx-action@v3` as a step before any `docker buildx` or `docker/build-push-action` usage."
+  - "Use `docker/build-push-action` instead of raw `docker build` for all CI image builds — it handles BuildKit setup and caching correctly."
+  - "For ARM64/multi-arch builds, expect 3-5x longer build times on x86 runners due to QEMU emulation."
+docs:
+  - url: "https://docs.docker.com/build/ci/github-actions/"
+    label: "Docker Build in GitHub Actions (Docker docs)"
+  - url: "https://github.com/docker/setup-buildx-action"
+    label: "docker/setup-buildx-action"
+  - url: "https://github.com/docker/build-push-action"
+    label: "docker/build-push-action"