diff --git a/errors/known-unsolved/codeql-merge-queue-status-not-reported.yml b/errors/known-unsolved/codeql-merge-queue-status-not-reported.yml new file mode 100644 index 0000000..66e3070 --- /dev/null +++ b/errors/known-unsolved/codeql-merge-queue-status-not-reported.yml @@ -0,0 +1,96 @@ +id: known-unsolved-142 +title: 'CodeQL Scans Triggered by merge_group Event Do Not Report "Code Scanning Results / CodeQL" Status Check to PR' +category: known-unsolved +severity: limitation +tags: + - codeql + - merge-queue + - merge_group + - required-status-check + - code-scanning + - branch-protection + - pull-request +patterns: + - regex: 'merge_group.*codeql|codeql.*merge_group' + flags: 'i' + - regex: 'Code scanning results.*CodeQL.*[Ww]aiting|CodeQL.*Expected.*[Ww]aiting.*status' + flags: 'i' +error_messages: + - "Code scanning results / CodeQL — Expected — Waiting for status to be reported" + - "Required status check 'Code scanning results / CodeQL' is not present on this commit" +root_cause: | + When GitHub Actions workflows run `github/codeql-action/analyze` on a `merge_group` + trigger (pull request merge queue), CodeQL successfully performs the analysis and + uploads the SARIF results — but the Code Scanning status check is NOT posted back to + the pull request. + + GitHub's merge queue creates ephemeral merge commits (refs like + `gh-readonly-queue/main/...`) that exist only for the duration of the queue check. + The CodeQL status posted to this merge commit SHA is not propagated back to the + PR head commit SHA that branch protection rules evaluate. + + As a result: + - The merge queue job completes successfully with CodeQL analysis done + - The SARIF results are uploaded to the code scanning results + - But the "Code scanning results / CodeQL" required status check on the PR shows + "Expected — Waiting for status to be reported" + - The PR cannot merge while CodeQL is a required branch protection status check + + This is a GitHub platform architectural limitation: the merge queue and code scanning + status reporting pipelines are not integrated. There is no runner-side fix available; + it requires a platform change from GitHub. + + Note: CodeQL on `pull_request` events DOES correctly report status, because + pull request events target the PR head SHA directly. +fix: | + There is no complete fix as of mid-2026. Workarounds: + + 1. Run CodeQL on `pull_request` (not `merge_group`) so status reports to the PR head + commit. Do not require the merge_group CodeQL check in branch protection. + + 2. Remove "Code scanning results / CodeQL" from required merge queue status checks. + Keep it as a required check for pull_request events only. + + 3. Track https://github.com/github/codeql-action/issues/1537 for official resolution. +fix_code: + - language: yaml + label: 'Run CodeQL on pull_request so PR status is correctly reported' + code: | + name: CodeQL Analysis + + on: + push: + branches: [main] + pull_request: # Use pull_request for required status checks + branches: [main] + # merge_group: # Omit or do NOT require this in branch protection until fixed + # branches: [main] + schedule: + - cron: '0 12 * * 1' + + jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + steps: + - uses: actions/checkout@v4 + - uses: github/codeql-action/init@v3 + with: + languages: javascript + - uses: github/codeql-action/autobuild@v3 + - uses: github/codeql-action/analyze@v3 +prevention: + - 'Do not set "Code scanning results / CodeQL" as a required status check for merge queue until GitHub resolves this gap' + - 'Use pull_request trigger for CodeQL scans that feed into required branch protection status checks' + - 'Track github/codeql-action#1537 for updates on merge_group CodeQL status reporting' +docs: + - url: https://github.com/github/codeql-action/issues/1537 + label: "GitHub Issue #1537 — GitHub merge queue builds don't report CodeQL status" + - url: https://docs.github.com/en/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page + label: 'About the code scanning tool status page — GitHub Docs' + - url: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue + label: 'Managing a merge queue — GitHub Docs' \ No newline at end of file diff --git a/errors/runner-environment/add-to-project-content-already-exists-in-project.yml b/errors/runner-environment/add-to-project-content-already-exists-in-project.yml new file mode 100644 index 0000000..28b7d66 --- /dev/null +++ b/errors/runner-environment/add-to-project-content-already-exists-in-project.yml @@ -0,0 +1,71 @@ +id: runner-environment-495 +title: 'actions/add-to-project Fails With "Content already exists in this project" When Issue Already in Board' +category: runner-environment +severity: error +tags: + - add-to-project + - github-projects + - idempotency + - graphql + - content-already-exists + - projects-v2 +patterns: + - regex: 'Content already exists in this project' + flags: 'i' + - regex: 'add-to-project.*Content already exists|Content already exists.*add-to-project' + flags: 'i' +error_messages: + - "Error: Content already exists in this project" + - "Failed to add issue to project: Content already exists in this project" +root_cause: | + The `actions/add-to-project` action uses the GitHub Projects v2 GraphQL API mutation + `addProjectV2ItemById` to add issues and pull requests to a project board. When the + action attempts to add an item that is already present in the project, the API returns + a GraphQL error: "Content already exists in this project." + + The action does not handle this response gracefully — it treats the duplicate-add error + as fatal and fails the workflow step instead of treating it as a no-op success. + + Common triggers: + 1. Issue was drafted directly on the project board (already added before `issues: opened` fires) + 2. Issue was re-opened (`issues: reopened`) but remains in the project from its previous open state + 3. A trigger label was added to an issue (`issues: labeled`) that was already in the project +fix: | + Restrict the workflow trigger events to only fire when an issue is genuinely new to + the project, or use `continue-on-error: true` to tolerate the duplicate-add gracefully. +fix_code: + - language: yaml + label: 'Restrict trigger to newly-opened issues only' + code: | + name: Add to project + on: + issues: + types: [opened] # Omit "reopened" and "labeled" to avoid duplicate-add errors + + jobs: + add-to-project: + runs-on: ubuntu-latest + steps: + - uses: actions/add-to-project@v1 + with: + project-url: https://github.com/orgs/my-org/projects/1 + github-token: ${{ secrets.ADD_TO_PROJECT_PAT }} + - language: yaml + label: 'Use continue-on-error to tolerate duplicates' + code: | + - uses: actions/add-to-project@v1 + continue-on-error: true + with: + project-url: https://github.com/orgs/my-org/projects/1 + github-token: ${{ secrets.ADD_TO_PROJECT_PAT }} +prevention: + - 'Only trigger add-to-project on `issues: [opened]`, not on `reopened` or `labeled`' + - 'Use `continue-on-error: true` on the step for resilience against duplicate-add scenarios' + - "For label-triggered workflows, filter with `if: github.event.action == 'opened'`" +docs: + - url: https://github.com/actions/add-to-project + label: 'actions/add-to-project — GitHub Action' + - url: https://github.com/actions/add-to-project/issues/389 + label: 'GitHub Issue #389 — Workflow fails if issue is already added to project' + - url: https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects + label: 'GitHub Projects v2 API documentation' \ No newline at end of file diff --git a/errors/runner-environment/first-interaction-v3-issue-message-required.yml b/errors/runner-environment/first-interaction-v3-issue-message-required.yml new file mode 100644 index 0000000..35ba263 --- /dev/null +++ b/errors/runner-environment/first-interaction-v3-issue-message-required.yml @@ -0,0 +1,75 @@ +id: runner-environment-496 +title: 'actions/first-interaction v3 Breaks With "Input required and not supplied: issue_message" After Minor Version Bump' +category: runner-environment +severity: error +tags: + - first-interaction + - breaking-change + - minor-version-bump + - required-input + - issue-message + - pr-only-workflow +patterns: + - regex: 'Input required and not supplied: issue_message' + flags: 'i' + - regex: 'first-interaction.*issue_message.*required|issue_message.*not supplied' + flags: 'i' +error_messages: + - "Error: Input required and not supplied: issue_message" + - "Input required and not supplied: issue_message" +root_cause: | + The `actions/first-interaction` action was converted to TypeScript in v3.1.0. As part + of this conversion, the `issue-message` input was inadvertently changed from optional + to required, even though the action can legitimately be used with only `pr-message` + (to greet first-time pull request contributors without commenting on issues). + + This is a breaking change introduced in a minor version bump (v3.0.0 to v3.1.0), + violating semantic versioning expectations. Users who auto-update via Dependabot or + Renovate to `actions/first-interaction@v3` have their existing workflows that only + set `pr-message` begin failing with: + + Error: Input required and not supplied: issue_message + + The error is thrown by the TypeScript input validation before any greeting logic runs. + The full error trace shows it originates from `getInput()` in the actions toolkit. +fix: | + Provide the `issue-message` input explicitly. If you only want to greet PR contributors, + pass an empty string to satisfy the v3.1.0+ validation requirement: + + ```yaml + - uses: actions/first-interaction@v3 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + pr-message: 'Thanks for your first PR!' + issue-message: '' # Required in v3.1.0+ — pass empty string if not needed + ``` +fix_code: + - language: yaml + label: 'Provide issue-message as empty string to satisfy v3.1.0+ requirement' + code: | + - name: First interaction greeting + uses: actions/first-interaction@v3 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + pr-message: 'Thanks for submitting your first pull request!' + issue-message: '' # Required in v3.1.0+; use empty string if only greeting PR authors + - language: yaml + label: 'Provide both messages (recommended)' + code: | + - name: First interaction greeting + uses: actions/first-interaction@v3 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + issue-message: 'Thanks for opening your first issue!' + pr-message: 'Thanks for submitting your first pull request!' +prevention: + - 'Always provide both `issue-message` and `pr-message` when using actions/first-interaction@v3+' + - 'Review changelogs before accepting automated minor version updates for GitHub Actions' + - 'Use version pinning (e.g., @v3.0.0) until confirmed compatible with your workflow' +docs: + - url: https://github.com/actions/first-interaction + label: 'actions/first-interaction — GitHub Action' + - url: https://github.com/actions/first-interaction/issues/365 + label: 'GitHub Issue #365 — issue_message is now a required parameter' + - url: https://github.com/actions/first-interaction/issues/364 + label: 'GitHub Issue #364 — Breaking change even though only minor version was bumped' \ No newline at end of file