@htekdev/actions-debugger 1.0.0 → 1.0.2

package/errors/permissions-auth/gcp-oidc-workload-identity-misconfigured.yml

@@ -0,0 +1,130 @@
+id: permissions-auth-008
+title: "GCP OIDC Workload Identity: Pool Path vs Provider Path / Project ID vs Number"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - gcp
+  - google-cloud
+  - workload-identity
+  - auth
+patterns:
+  - regex: "Invalid value for [\"']?audience[\"']?"
+    flags: "i"
+  - regex: "Error code invalid_request.*Invalid value for.*audience"
+    flags: "i"
+  - regex: "workloadIdentityPools.*not.*providers"
+    flags: "i"
+  - regex: "project.*number.*not.*project.*id"
+    flags: "i"
+  - regex: "OAuthError.*Invalid value for.*audience"
+    flags: "i"
+  - regex: "Error parsing credentials.*workload_identity_provider"
+    flags: "i"
+error_messages:
+  - "ERROR: gcloud crashed (OAuthError): Error code invalid_request: Invalid value for \"audience\"."
+  - "Error: google-github-actions/auth failed with: Error code invalid_request: Invalid value for \"audience\"."
+  - "The workload_identity_provider must be the full provider resource name, not the pool resource name."
+root_cause: |
+  `google-github-actions/auth` OIDC authentication fails with "Invalid value for audience"
+  when either of two common misconfiguration patterns is present:
+
+  **Mistake 1 — Pool path instead of Provider path**
+  The `workload_identity_provider` input requires the full *Provider* resource name:
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`
+
+  Many developers mistakenly supply only the *Pool* path (omitting `/providers/PROVIDER_ID`):
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID`
+
+  GCP's STS token endpoint rejects the audience because it expects the provider URI, not the pool URI.
+
+  **Mistake 2 — Project ID (string) instead of Project Number (integer)**
+  The path requires the numeric GCP project number (e.g. `123456789012`), NOT the human-readable
+  project ID (e.g. `my-gcp-project`). Workload Identity Federation does not accept project IDs.
+  Using a project ID causes the STS endpoint to return "Invalid value for audience" because the
+  resource path does not resolve to a valid identity provider.
+
+  **Mistake 3 — Missing `id-token: write` permission**
+  If `permissions.id-token` is not explicitly set to `write` at the job or workflow level,
+  GitHub will not mint an OIDC token and the auth step fails with a permissions error rather
+  than a token exchange error.
+fix: |
+  Verify the `workload_identity_provider` value against the exact format required:
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER`
+
+  Retrieve the correct value:
+    gcloud iam workload-identity-pools providers describe PROVIDER_ID \
+      --project=PROJECT_ID \
+      --location=global \
+      --workload-identity-pool=POOL_ID \
+      --format='value(name)'
+
+  Ensure `id-token: write` is set in the job permissions block.
+
+  Wait at least 5 minutes after changes to Workload Identity Pool / Provider / IAM bindings
+  before testing — these resources are eventually consistent.
+fix_code:
+  - language: yaml
+    label: "Correct workload_identity_provider format (provider path + project number)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write    # REQUIRED — grants GitHub the right to mint an OIDC token
+            contents: read
+
+          steps:
+            - uses: actions/checkout@v4
+
+            - id: auth
+              uses: google-github-actions/auth@v2
+              with:
+                # CORRECT: full provider path with numeric project number
+                workload_identity_provider: >-
+                  projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+                service_account: my-service-account@my-project.iam.gserviceaccount.com
+  - language: yaml
+    label: "Common mistake — pool path (missing /providers/...) causes audience error"
+    code: |
+      # WRONG: pool path only — gcloud crashes with "Invalid value for audience"
+      # workload_identity_provider: >-
+      #   projects/123456789012/locations/global/workloadIdentityPools/my-pool
+
+      # ALSO WRONG: project ID string instead of project number
+      # workload_identity_provider: >-
+      #   projects/my-gcp-project/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+
+      # CORRECT:
+      # workload_identity_provider: >-
+      #   projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+  - language: yaml
+    label: "Store provider path in a repository variable to avoid typos"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: google-github-actions/auth@v2
+              with:
+                # Store full provider path as a repository variable to avoid typos
+                workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
+                service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
+prevention:
+  - "Always use `gcloud iam workload-identity-pools providers describe` to copy the exact provider path."
+  - "Store the full provider path in a GitHub Actions variable (`vars.GCP_WIF_PROVIDER`) to prevent manual typos."
+  - "Use numeric project number — retrieve it with `gcloud projects describe PROJECT_ID --format='value(projectNumber)'`."
+  - "After changing Workload Identity Pool config, wait 5 minutes before testing (eventual consistency)."
+  - "Confirm `id-token: write` permission is present at job (not just workflow) level."
+docs:
+  - url: "https://github.com/google-github-actions/auth#setup"
+    label: "google-github-actions/auth: Setup and configuration"
+  - url: "https://github.com/google-github-actions/auth/blob/main/docs/TROUBLESHOOTING.md"
+    label: "google-github-actions/auth: Troubleshooting guide"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform"
+    label: "Configuring OIDC in Google Cloud Platform"
+  - url: "https://cloud.google.com/iam/docs/workload-identity-federation-with-deployment-pipelines"
+    label: "GCP: Workload Identity Federation with deployment pipelines"

package/errors/permissions-auth/github-token-403.yml

@@ -1,64 +1,64 @@
-id: permissions-auth-001
-title: "GITHUB_TOKEN Permission Denied (403)"
-category: permissions-auth
-severity: error
-tags:
-  - github-token
-  - permissions
-  - 403
-  - auth
-  - push
-patterns:
-  - regex: "remote: Permission to .+\\.git denied to github-actions\\[bot\\]"
-    flags: "i"
-  - regex: "fatal: unable to access 'https://github\\.com/.+': The requested URL returned error: 403"
-    flags: "i"
-  - regex: "Resource not accessible by integration"
-    flags: "i"
-error_messages:
-  - "remote: Permission to org/repo.git denied to github-actions[bot]."
-  - "fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
-  - "Resource not accessible by integration"
-root_cause: |
-  Since February 2023, newly created repositories default `GITHUB_TOKEN` to read-only
-  permissions in many cases. A workflow that tries to push commits, create releases, or
-  modify pull requests without an explicit `permissions:` block can suddenly fail with 403
-  or integration access errors.
-
-  The token exists, but it does not have the scopes the job assumed it had.
-fix: |
-  Add the minimum required `permissions:` block at the workflow or job level. For pushes,
-  tags, or release creation, that usually means `contents: write`. For pull request comments
-  or checks, grant the specific write permission those APIs require.
-fix_code:
-  - language: yaml
-    label: "Grant explicit write permissions to GITHUB_TOKEN"
-    code: |
-      name: Release
-
-      on:
-        push:
-          branches:
-            - main
-
-      permissions:
-        contents: write
-
-      jobs:
-        release:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - run: git push origin HEAD:main
-prevention:
-  - "Assume `GITHUB_TOKEN` is read-only unless you explicitly grant the needed permission."
-  - "Set least-privilege `permissions:` blocks on every workflow instead of relying on defaults."
-  - "Match API usage to the smallest write scope required."
-docs:
-  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
-    label: "Automatic token authentication"
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions"
-    label: "permissions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "GITHUB_TOKEN 403 and read-only defaults"
+id: permissions-auth-001
+title: "GITHUB_TOKEN Permission Denied (403)"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - permissions
+  - 403
+  - auth
+  - push
+patterns:
+  - regex: "remote: Permission to .+\\.git denied to github-actions\\[bot\\]"
+    flags: "i"
+  - regex: "fatal: unable to access 'https://github\\.com/.+': The requested URL returned error: 403"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "remote: Permission to org/repo.git denied to github-actions[bot]."
+  - "fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
+  - "Resource not accessible by integration"
+root_cause: |
+  Since February 2023, newly created repositories default `GITHUB_TOKEN` to read-only
+  permissions in many cases. A workflow that tries to push commits, create releases, or
+  modify pull requests without an explicit `permissions:` block can suddenly fail with 403
+  or integration access errors.
+
+  The token exists, but it does not have the scopes the job assumed it had.
+fix: |
+  Add the minimum required `permissions:` block at the workflow or job level. For pushes,
+  tags, or release creation, that usually means `contents: write`. For pull request comments
+  or checks, grant the specific write permission those APIs require.
+fix_code:
+  - language: yaml
+    label: "Grant explicit write permissions to GITHUB_TOKEN"
+    code: |
+      name: Release
+
+      on:
+        push:
+          branches:
+            - main
+
+      permissions:
+        contents: write
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: git push origin HEAD:main
+prevention:
+  - "Assume `GITHUB_TOKEN` is read-only unless you explicitly grant the needed permission."
+  - "Set least-privilege `permissions:` blocks on every workflow instead of relying on defaults."
+  - "Match API usage to the smallest write scope required."
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
+    label: "Automatic token authentication"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions"
+    label: "permissions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "GITHUB_TOKEN 403 and read-only defaults"

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"