@htekdev/actions-debugger 1.0.123 → 1.0.125

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

@@ -0,0 +1,144 @@
+id: permissions-auth-071
+title: 'OIDC token not available in pull_request events from forks — id-token: write cannot be granted'
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - fork
+  - pull-request
+  - id-token
+  - attestation
+  - aws
+  - azure
+  - workload-identity
+patterns:
+  - regex: 'Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+    flags: 'i'
+  - regex: 'Could not fetch an OIDC token.*id-token.*write'
+    flags: 'i'
+  - regex: 'Error: Action failed with error: Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL'
+    flags: 'i'
+error_messages:
+  - 'Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+  - 'Could not fetch an OIDC token. Did you remember to add `id-token: write` to your workflow permissions?'
+  - 'Error: Action failed with error: Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+root_cause: |
+  GitHub Actions workflows triggered by `pull_request` events from forked repositories cannot
+  mint OIDC tokens, even when `id-token: write` is explicitly set in the workflow `permissions:` block.
+
+  The restriction is enforced by GitHub's security model for fork pull requests:
+  - Fork PRs run with the permissions of the fork, not the base repository.
+  - GitHub documentation states: "You can use the permissions key to add and remove read
+    permissions for forked repositories, but typically you can't grant write access."
+  - The `id-token: write` scope is a WRITE permission. The ACTIONS_ID_TOKEN_REQUEST_URL
+    environment variable is only set when the runtime has write-level token access.
+  - When the variable is absent, any action or toolkit call to `core.getIDToken()` fails with
+    "Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable".
+
+  This commonly impacts:
+  - Cloud provider OIDC authentication (AWS configure-aws-credentials, Azure login, GCP auth)
+  - actions/attest-build-provenance and actions/attest for build attestation on PRs
+  - Any action that relies on `@actions/core` `getIDToken()` for OIDC federation
+
+  The restriction exists to prevent malicious fork contributors from using OIDC tokens to
+  authenticate against production cloud accounts or push malicious artifacts.
+fix: |
+  Option 1 — Use `pull_request_target` instead of `pull_request` (CAUTION required).
+  `pull_request_target` runs in the context of the base repository and CAN mint OIDC tokens.
+  However, it executes in the base repo's context with full access to base repo secrets —
+  this is a significant security risk if the workflow checks out or executes fork code without
+  proper isolation. Read all security guides before using this trigger.
+
+  Option 2 — Split the workflow into two parts.
+  Use `pull_request` for the build/test phase (no OIDC). Use a separate workflow triggered
+  by `workflow_run` or manual approval to perform OIDC-protected operations (attestation, deploy)
+  after verifying the PR code is safe.
+
+  Option 3 — Use a GitHub App token with explicit repository permissions for operations
+  that do not strictly require OIDC (e.g., package publishing). This avoids the OIDC
+  restriction entirely.
+
+  Option 4 — Only run OIDC-dependent steps on `push` events to protected branches (post-merge),
+  not on `pull_request` events from forks. Guard OIDC steps with:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false
+fix_code:
+  - language: yaml
+    label: 'Guard OIDC steps — skip for fork PRs, run only for same-repo PRs or push'
+    code: |
+      jobs:
+        build-and-attest:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+            attestations: write
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build artifact
+              run: ./build.sh
+
+            # OIDC-dependent steps: skip if fork PR (id-token write not available)
+            - name: Attest build provenance
+              if: >
+                github.event_name != 'pull_request' ||
+                github.event.pull_request.head.repo.full_name == github.repository
+              uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: './dist/app'
+
+  - language: yaml
+    label: 'Split workflow: use workflow_run to run OIDC steps after fork PR merges'
+    code: |
+      # Workflow 1: runs on pull_request — builds and uploads artifact (no OIDC)
+      on:
+        pull_request:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: ./dist/
+
+      ---
+
+      # Workflow 2: runs after workflow 1 completes — performs OIDC operations
+      on:
+        workflow_run:
+          workflows: ['Build']
+          types: [completed]
+      jobs:
+        attest:
+          # Only runs on base-repo push events completing after a merge
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            attestations: write
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: './dist/app'
+prevention:
+  - 'Never assume `id-token: write` is sufficient — fork PRs override write permissions to read-only regardless of the workflow `permissions:` block.'
+  - 'Add an explicit `if:` guard on every OIDC-dependent step to skip it for fork PRs: `if: github.event.pull_request.head.repo.fork == false`.'
+  - 'Use `pull_request_target` only after thoroughly reading the security hardening guide — it runs in base repo context and is vulnerable to pwn requests if fork code is checked out.'
+  - 'For attestation workflows, run attestation as a post-merge step on `push` to the default branch, not on PRs from forks.'
+docs:
+  - url: 'https://github.com/actions/attest-build-provenance/issues/99'
+    label: 'actions/attest-build-provenance#99 — OIDC unavailable in fork PR workflows (open)'
+  - url: 'https://github.com/aws-actions/configure-aws-credentials/issues/373'
+    label: 'aws-actions/configure-aws-credentials#373 — OIDC fails for pull request from fork'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Docs — GITHUB_TOKEN permissions for forked repos'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-pull_request_target-safely'
+    label: 'GitHub Docs — Security hardening for pull_request_target'

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

@@ -0,0 +1,112 @@
+id: permissions-auth-072
+title: 'actions/labeler fails with "You do not have permission to create labels" — missing issues: write'
+category: permissions-auth
+severity: error
+tags:
+  - actions/labeler
+  - issues
+  - labels
+  - permissions
+  - issues-write
+  - GITHUB_TOKEN
+  - HttpError
+patterns:
+  - regex: 'You do not have permission to create labels on this repository'
+    flags: 'i'
+  - regex: 'HttpError.+do not have permission to create labels'
+    flags: 'i'
+  - regex: '"resource":"Repository","field":"label","code":"unauthorized"'
+    flags: 'i'
+error_messages:
+  - 'HttpError: You do not have permission to create labels on this repository.: {"resource":"Repository","field":"label","code":"unauthorized"}'
+  - 'Error: You do not have permission to create labels on this repository.'
+root_cause: |
+  `actions/labeler` requires the `issues: write` permission on the
+  `GITHUB_TOKEN` whenever it needs to **create** a label that does not yet
+  exist in the repository. The labeler's `create-labels: true` setting (or
+  its equivalent in older versions that auto-create missing labels) triggers a
+  `POST /repos/{owner}/{repo}/labels` API call.
+
+  In 2023+, GitHub tightened default token permissions. Repositories and
+  organizations that enable "Read repository contents and packages permissions"
+  as the default GITHUB_TOKEN permission, or workflows that explicitly
+  enumerate `permissions:` without including `issues: write`, will cause the
+  label-creation API call to return HTTP 403:
+
+    `HttpError: You do not have permission to create labels on this repository.`
+
+  Note: If all labels already exist in the repository, the action only calls
+  `GET /repos/{owner}/{repo}/labels` (read) and `POST .../issues/{number}/labels`
+  (adding a label to an issue/PR — also requires issues:write). In practice,
+  any labeling operation that modifies issues or creates labels needs this
+  permission. The error is especially confusing because it surfaces as an
+  `HttpError` that looks like a GitHub API error rather than a clear
+  "permission denied" message.
+fix: |
+  Add `issues: write` to the workflow or job permissions block:
+
+  ```yaml
+  permissions:
+    issues: write
+    pull-requests: write  # Also needed if labeling pull requests
+    contents: read
+  ```
+
+  If the repository uses the default broad permissions and the error occurs on
+  a fork PR (where fork PRs receive read-only tokens regardless of the
+  workflow's permissions block), add a guard:
+
+  ```yaml
+  if: github.event.pull_request.head.repo.full_name == github.repository
+  ```
+
+  to skip label creation on fork PRs where the token cannot be elevated.
+fix_code:
+  - language: yaml
+    label: 'Add issues: write permission to the labeler job'
+    code: |
+      name: Label PRs
+
+      on:
+        pull_request_target:
+          types: [opened, synchronize, reopened]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            issues: write       # Required to create new labels
+            pull-requests: write # Required to add labels to pull requests
+            contents: read
+          steps:
+            - uses: actions/labeler@v5
+              with:
+                repo-token: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: 'Skip labeler on fork PRs where token is always read-only'
+    code: |
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          # Skip on forks — their GITHUB_TOKEN is read-only regardless of permissions block
+          if: github.event.pull_request.head.repo.full_name == github.repository
+          permissions:
+            issues: write
+            pull-requests: write
+            contents: read
+          steps:
+            - uses: actions/labeler@v5
+              with:
+                repo-token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - 'Always include `issues: write` and `pull-requests: write` when using actions/labeler, even if the labeler config only applies existing labels — it still needs write to apply labels to PRs/issues.'
+  - 'Pre-create all labels defined in `.github/labeler.yml` in the repository settings so the action never needs to create them, reducing the permission surface needed (though issues:write is still needed for applying labels to issues/PRs).'
+  - 'When using `pull_request` trigger (not `pull_request_target`), fork PRs receive a read-only GITHUB_TOKEN by design; switch to `pull_request_target` or handle fork PRs with a separate read-only path.'
+  - 'Use the permissions checker in your CI review process: verify labeler workflows include explicit `permissions:` blocks before merging.'
+docs:
+  - url: 'https://github.com/actions/labeler/issues/870'
+    label: 'actions/labeler#870 — HttpError: You do not have permission to create labels on this repository'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'GitHub Docs — Controlling permissions for GITHUB_TOKEN'
+  - url: 'https://github.com/actions/labeler#token'
+    label: 'actions/labeler — Token and permissions requirements'

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

@@ -0,0 +1,127 @@
+id: permissions-auth-073
+title: 'GraphQL "refusing to allow a GitHub App to create or update workflow without `workflows` permission" — misleading error, actual fix is actions: write or App workflow scope'
+category: permissions-auth
+severity: error
+tags:
+  - GitHub-App
+  - workflows
+  - actions-write
+  - GraphQL
+  - pull-request
+  - misleading-error
+  - OAuth-scope
+  - enablePullRequestAutoMerge
+patterns:
+  - regex: "refusing to allow a GitHub App to create or update workflow .+ without .workflows. permission"
+    flags: 'i'
+  - regex: 'GraphQL.+Pull request.+workflow.+without.+workflows.*permission'
+    flags: 'i'
+error_messages:
+  - "GraphQL: Pull request refusing to allow a GitHub App to create or update workflow `.github/workflows/release.yml` without `workflows` permission (enablePullRequestAutoMerge)"
+  - "refusing to allow a GitHub App to create or update workflow `.github/workflows/ci.yml` without `workflows` permission"
+root_cause: |
+  When a GitHub App or the `GITHUB_TOKEN` attempts to enable auto-merge,
+  create a pull request that modifies workflow files, or perform certain
+  pull-request GraphQL mutations (`enablePullRequestAutoMerge`,
+  `createPullRequest`, etc.) on a branch that touches `.github/workflows/`,
+  GitHub's API returns a misleading error:
+
+    `GraphQL: Pull request refusing to allow a GitHub App to create or update
+     workflow '...' without 'workflows' permission`
+
+  The error message references `workflows` as if it were a value you can set
+  in the `permissions:` block of a GitHub Actions workflow. **It is not.**
+  The word `workflows` here refers to the **GitHub App OAuth scope** (which
+  grants the App permission to edit workflow files), not the `actions: write`
+  or any standard GITHUB_TOKEN permission key.
+
+  There are two distinct situations that produce this error:
+
+  1. **GitHub App missing the Workflows permission:** If your GitHub App does
+     not have the "Workflows" repository permission (a GitHub App installation
+     permission distinct from all the `permissions:` block keys), any operation
+     that modifies `.github/workflows/` through the App will be rejected with
+     this message.
+
+  2. **GITHUB_TOKEN used for auto-merge enabling on workflow-touching PRs:**
+     When a workflow uses `gh pr merge --auto` (or the GraphQL
+     `enablePullRequestAutoMerge` mutation) on a PR that modifies workflow
+     files, the GITHUB_TOKEN may lack the necessary scope even with
+     `contents: write`, because enabling auto-merge on workflow-modifying PRs
+     requires the workflows OAuth scope which GITHUB_TOKEN cannot hold.
+
+  The error message's reference to `workflows` is confusing because it is not
+  a recognized key in the YAML `permissions:` block. Developers who try to
+  add `permissions: workflows: write` get a YAML validation error ("Unknown
+  property 'workflows'"), leading to frustration when neither the permissions
+  block nor the token can be directly granted this scope.
+fix: |
+  **For GitHub Apps:**
+  Go to your GitHub App's settings → Permissions & events → Repository
+  permissions → and enable **"Workflows" permission** (set to Read & Write).
+  Then re-install the app on the repository/organization so the new permission
+  takes effect.
+
+  **For GITHUB_TOKEN on auto-merge of workflow-touching PRs:**
+  The GITHUB_TOKEN cannot hold the `workflows` OAuth scope. You must use a
+  Personal Access Token (classic, with the `workflow` scope) or a GitHub App
+  with the Workflows permission. Store either as a repository secret and use it
+  instead of `GITHUB_TOKEN` for the auto-merge step:
+
+  ```yaml
+  - name: Enable auto-merge
+    env:
+      GH_TOKEN: ${{ secrets.MY_PAT_WITH_WORKFLOW_SCOPE }}
+    run: gh pr merge --auto --squash ${{ github.event.pull_request.number }}
+  ```
+
+  **For `actions: write` confusion:**
+  Adding `actions: write` to the `permissions:` block does NOT fix this error.
+  `actions: write` governs artifacts, caches, and workflow runs — NOT the
+  ability to create or modify workflow files.
+fix_code:
+  - language: yaml
+    label: 'Use a PAT with the workflow scope instead of GITHUB_TOKEN for auto-merge on workflow-touching PRs'
+    code: |
+      jobs:
+        auto-merge:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Enable auto-merge
+              # GITHUB_TOKEN cannot hold the 'workflow' OAuth scope.
+              # Use a PAT (classic) with the 'workflow' scope stored as a secret.
+              env:
+                GH_TOKEN: ${{ secrets.PAT_WITH_WORKFLOW_SCOPE }}
+              run: |
+                gh pr merge --auto --squash "${{ github.event.pull_request.number }}"
+  - language: yaml
+    label: 'Use create-github-app-token with Workflows permission to create PRs that modify workflows'
+    code: |
+      jobs:
+        create-update-pr:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate App token (App must have Workflows read+write permission)
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.MY_APP_ID }}
+                private-key: ${{ secrets.MY_APP_PRIVATE_KEY }}
+
+            - name: Create PR modifying a workflow file
+              env:
+                GH_TOKEN: ${{ steps.app-token.outputs.token }}
+              run: |
+                gh pr create --title "Update workflow" --body "..." --base main
+prevention:
+  - 'When your GitHub App or automation needs to create PRs that touch `.github/workflows/`, verify the App installation has the "Workflows" repository permission enabled (App settings → Permissions → Workflows: Read & Write).'
+  - 'Do NOT attempt `permissions: workflows: write` in your workflow YAML — "workflows" is not a valid permission key and will cause a YAML validation error; it is an App-level OAuth scope, not a token permission.'
+  - 'For auto-merge automation on PRs that may modify workflow files, use a classic PAT with the `workflow` scope or a GitHub App with Workflows permission rather than GITHUB_TOKEN.'
+  - 'When debugging this error, the key question is: "Does the token/App have the `workflows` OAuth scope?" — not "Does the job have the right permissions: block?"'
+docs:
+  - url: 'https://github.com/cli/cli/issues/11493'
+    label: 'cli/cli#11493 — Misleading GraphQL error: "without workflows permission" when using enablePullRequestAutoMerge'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app'
+    label: 'GitHub Docs — Choosing permissions for a GitHub App (Workflows permission)'
+  - url: 'https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens'
+    label: 'GitHub Docs — Classic PAT workflow scope for modifying workflow files'

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

@@ -0,0 +1,106 @@
+id: permissions-auth-074
+title: 'Composer leaks new-format GITHUB_TOKEN (ghs_APPID_JWT) to stderr in CI logs — CVE-2026-45793 / GHSA-f9f8-rm49-7jv2'
+category: permissions-auth
+severity: error
+tags:
+  - composer
+  - GITHUB_TOKEN
+  - token-disclosure
+  - ghs-token
+  - php
+  - setup-php
+  - CVE-2026-45793
+  - security
+  - token-format-rollout
+patterns:
+  - regex: 'Your github oauth token for .+ contains invalid characters'
+    flags: 'i'
+  - regex: 'UnexpectedValueException.+github oauth token.+invalid characters'
+    flags: 'i'
+  - regex: 'contains invalid characters: "ghs_'
+    flags: 'i'
+error_messages:
+  - 'Your github oauth token for github.com contains invalid characters: "ghs_AppID_eyJhbGc..."'
+  - '[InvalidArgumentException] Your github oauth token for github.com contains invalid characters: "ghs_..."'
+root_cause: |
+  Starting April 27, 2026, GitHub began rolling out a new stateless token format for
+  GITHUB_TOKEN and GitHub App installation tokens. The new format is `ghs_<AppID>_<JWT>`,
+  approximately 520 characters long, and uses base64url encoding which includes hyphens (`-`)
+  and underscores.
+
+  Composer versions >=2.3.0 <2.9.8 (and >=1.0 <1.10.28, >=2.0.0 <2.2.28) validate GitHub OAuth
+  tokens with the regex `^[.A-Za-z0-9_]+$`. This regex does not permit hyphens. The new
+  `ghs_APPID_JWT` token format routinely contains hyphens (base64url RFC 4648 §5 uses `-` and `_`
+  as URL-safe replacements for `+` and `/`).
+
+  When the token fails this validation, Composer throws an `UnexpectedValueException` that
+  interpolates the raw token verbatim into the error message:
+
+    `Your github oauth token for github.com contains invalid characters: "ghs_<full-token>"`
+
+  Symfony Console then prints this exception to stderr. GitHub Actions' built-in secret masker
+  matches registered values as exact substrings, but Symfony Console may wrap the message, embed
+  it in framing text (`In BaseIO.php line N:`), or interleave ANSI control sequences. As a result,
+  the masker does not redact the token, and the plaintext credential reaches the CI log.
+
+  This affects any PHP workflow that uses Composer with GITHUB_TOKEN registered as a GitHub OAuth
+  credential. Many widely-used Actions — including `shivammathur/setup-php` — automatically
+  register `GITHUB_TOKEN` into Composer's global `auth.json`, so the leak triggers without
+  any explicit user configuration.
+
+  CVSS score: 7.5 (High). CVE-2026-45793 / GHSA-f9f8-rm49-7jv2.
+fix: |
+  **Primary fix: Upgrade Composer to a patched version.**
+  - Composer 2.x (mainline): upgrade to >=2.9.8
+  - Composer 2.2.x (LTS): upgrade to >=2.2.28
+  - Composer 1.x: upgrade to >=1.10.28
+
+  The patched versions update the token validation regex to accept hyphens, preventing the
+  disclosure.
+
+  **Secondary workaround (if upgrading is not immediately possible):**
+  Explicitly unset the GitHub token from Composer's auth config before running Composer, then
+  set it via a token-safe mechanism, or use a classic `ghp_` PAT which uses the old format
+  unaffected by this regression:
+
+  ```yaml
+  - name: Remove GITHUB_TOKEN from Composer auth (workaround)
+    run: composer config --global --unset github-oauth.github.com
+  ```
+
+  **If using `shivammathur/setup-php`:** The action pins a Composer version; ensure you're on
+  a version that ships Composer >=2.9.8.
+fix_code:
+  - language: yaml
+    label: 'Pin Composer to patched version in GitHub Actions workflow'
+    code: |
+      - name: Install dependencies
+        run: |
+          # Ensure Composer is on a patched version before running install.
+          # Composer 2.9.8+ fixes CVE-2026-45793 (GITHUB_TOKEN disclosure with new ghs_ format)
+          composer self-update --2 2.9.8
+          composer install --no-interaction --prefer-dist
+  - language: yaml
+    label: 'Use shivammathur/setup-php with Composer version pinned to patched release'
+    code: |
+      - name: Set up PHP and Composer
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          tools: composer:2.9.8  # Pin to patched version fixing CVE-2026-45793
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - 'Always pin Composer to a specific patched version in CI (e.g., `composer:2.9.8` in setup-php tools). Do not rely on "latest" which may ship a vulnerable version during the rollout window.'
+  - 'Audit your workflow logs for lines matching `contains invalid characters` — these indicate a credential has been disclosed to the log.'
+  - 'Be aware that `shivammathur/setup-php` auto-registers `GITHUB_TOKEN` into Composer auth by default; upgrading to a patched Composer is the only reliable mitigation.'
+  - 'For repositories that do not need Composer to make authenticated GitHub API calls, you can disable auto-registration: `COMPOSER_AUTH: ''{}''` in the env block prevents auto-injection.'
+docs:
+  - url: 'https://github.com/advisories/GHSA-f9f8-rm49-7jv2'
+    label: 'GHSA-f9f8-rm49-7jv2 — Composer leaks GITHUB_TOKEN in CI logs (CVE-2026-45793)'
+  - url: 'https://github.com/composer/composer/security/advisories/GHSA-f9f8-rm49-7jv2'
+    label: 'composer/composer security advisory — GHSA-f9f8-rm49-7jv2 details and affected versions'
+  - url: 'https://github.blog/changelog/2026-04-24-notice-about-upcoming-new-format-for-github-app-installation-tokens/'
+    label: 'GitHub Changelog — Notice about new format for GitHub App installation tokens (April 2026)'
+  - url: 'https://github.com/composer/composer/issues/12849'
+    label: 'composer/composer#12849 — New format for GitHub Tokens (upstream issue report)'

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

@@ -0,0 +1,137 @@
+id: permissions-auth-075
+title: 'OIDC token missing `repository_custom_property_*` claim — custom property must be defined at org level, not just repo level'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - OIDC
+  - custom-properties
+  - trust-policy
+  - AWS
+  - Azure
+  - claim-missing
+  - org-level
+  - AccessDenied
+  - cloud-auth
+patterns:
+  - regex: 'repository_custom_property'
+    flags: 'i'
+  - regex: '(?:AccessDenied|is not authorized).+sts:AssumeRoleWithWebIdentity'
+    flags: 'i'
+  - regex: 'OpenIDConnectTokenVerificationFailed|sub.*claim.*condition.*failed|conditions.*not.*met'
+    flags: 'i'
+error_messages:
+  - 'Error: User: arn:aws:sts::ACCOUNT:assumed-role/... is not authorized to perform: sts:AssumeRoleWithWebIdentity'
+  - 'Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity'
+  - 'ClientAssertionCredential authentication failed: AADSTS70021'
+  - 'Error: No federated identity credential with issuer https://token.actions.githubusercontent.com matches'
+root_cause: |
+  GitHub Actions OIDC tokens gained support for `repository_custom_property_*` claims in
+  March 2026 (GA April 2, 2026 changelog). These claims allow trust policies on AWS, Azure,
+  and other cloud providers to filter access based on how a repository is classified within
+  an organization (e.g., `repository_custom_property_environment: production`).
+
+  However, there is a critical prerequisite that is not prominently documented:
+  **custom property definitions must be created at the organization level** — not just at the
+  repository level — for the corresponding claims to appear in OIDC tokens.
+
+  Specifically:
+  1. The custom property must be defined in the organization's custom properties schema
+     (Settings → Custom properties at the org level).
+  2. The property must be set/assigned a value for the repository in question.
+
+  When a property is created only at the **repository level** (via repo-specific custom
+  properties without an org-level schema entry), or when the property exists at the org
+  level but has no value set for the specific repository, the `repository_custom_property_*`
+  claim is simply **absent** from the OIDC token rather than being set to null or an empty
+  string.
+
+  Trust policies that include a condition requiring a specific `repository_custom_property_*`
+  claim evaluate to no-match and deny authentication. The cloud provider returns a generic
+  `AccessDenied` / `is not authorized` error with no indication that the claim is missing.
+  The workflow author sees a cloud authentication failure with no clear link to the OIDC
+  token contents.
+
+  This is a silent configuration error: the workflow appears to run normally until the
+  authentication step fails, and there is no warning during workflow setup or YAML validation
+  that the property is misconfigured.
+fix: |
+  **Step 1: Verify the OIDC token contents.**
+  Add a debug step to print the OIDC token claims before the cloud auth step:
+
+  ```yaml
+  - name: Debug OIDC claims
+    run: |
+      TOKEN=$(curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+        "$ACTIONS_ID_TOKEN_REQUEST_URL" | jq -r '.value')
+      echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .
+  ```
+
+  If `repository_custom_property_*` claims are absent, the property is not defined at the
+  org level or has no value for this repository.
+
+  **Step 2: Define the custom property at the organization level.**
+  Navigate to the GitHub organization → Settings → Custom properties and create the property
+  definition there. Repository-level-only properties do NOT produce OIDC claims.
+
+  **Step 3: Assign a value to the property for the target repository.**
+  After creating the org-level property definition, explicitly set the value for each
+  repository that needs the claim by going to the repository's Settings → Custom properties
+  or using the REST API.
+
+  **If you cannot use org-level properties:** Fall back to other OIDC sub-claim conditions
+  such as `repository`, `ref`, `environment`, or `job_workflow_ref` which are always present
+  in Actions OIDC tokens.
+fix_code:
+  - language: yaml
+    label: 'Add OIDC debug step to inspect claims before cloud auth'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - name: Debug OIDC token claims (remove after debugging)
+              run: |
+                TOKEN=$(curl -sS \
+                  -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+                  "$ACTIONS_ID_TOKEN_REQUEST_URL" | jq -r '.value')
+                # Print decoded payload (base64url decode the second segment)
+                echo "$TOKEN" | cut -d. -f2 | \
+                  python3 -c "import sys,base64,json; data=sys.stdin.read().strip(); \
+                    padded=data+'=='*((-len(data))%4); \
+                    print(json.dumps(json.loads(base64.urlsafe_b64decode(padded)), indent=2))"
+
+            - name: Configure AWS credentials via OIDC
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::ACCOUNT:role/my-role
+                aws-region: us-east-1
+  - language: yaml
+    label: 'AWS trust policy condition using repository_custom_property_* (requires org-level property)'
+    code: |
+      # AWS IAM trust policy condition requiring a custom property claim.
+      # PREREQUISITE: The property must be defined at org level AND set on the repository.
+      # If the claim is absent, AWS returns AccessDenied with no indication of missing claim.
+      {
+        "Condition": {
+          "StringEquals": {
+            "token.actions.githubusercontent.com:repository_custom_property_environment": "production"
+          }
+        }
+      }
+prevention:
+  - 'Always create custom property definitions at the **organization level** (Org Settings → Custom properties), not just at the repository level. Repo-level-only properties do NOT appear in OIDC tokens.'
+  - 'After creating an org-level property, explicitly set a value for each target repository. A property defined but not assigned a value for a repo is also absent from the OIDC token.'
+  - 'Before deploying trust policies that use `repository_custom_property_*` conditions, verify the claim is present in the OIDC token by printing decoded token claims in a debug step.'
+  - 'When trust policy conditions reference `repository_custom_property_*`, always have a fallback monitoring alert for `AccessDenied` / `is not authorized` errors to catch misconfigured or unset properties quickly.'
+docs:
+  - url: 'https://github.com/github/docs/issues/43779'
+    label: 'github/docs#43779 — custom properties docs gap: org-level definition required for OIDC claims'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#defining-trust-conditions-on-cloud-roles-using-oidc-claims'
+    label: 'GitHub Docs — About security hardening with OIDC: defining trust conditions using claims'
+  - url: 'https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/'
+    label: 'GitHub Changelog — April 2026: Actions OIDC tokens now support repository custom properties'
+  - url: 'https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization'
+    label: 'GitHub Docs — Managing custom properties for repositories in your organization'