phpcs PSR12 file header missing error in PR check

Not specified by the original author.

TL;DR

PSR-12 requires a file-level docblock when the file declares symbols. Add a /** ... */ block with the file description as the first comment in the file, after the opening PHP tag.

Error

FILE: src/Invoice.php
FOUND 1 ERROR AFFECTING 1 LINE
  1 | ERROR | [x] Missing file doc comment (PSR12.Files.FileHeader)

Steps

1. Confirm the sniff: run phpcs --standard=PSR12 src/Invoice.php. Expected: the PSR12.Files.FileHeader error on line 1.
2. Add a file docblock right after the opening PHP tag: a /** block describing the file contents. Expected: the docblock is the first comment in the file.
3. Re-run phpcs on the file. Expected: no errors reported.
4. If the file is pure procedural code with no declarations, consider whether the standard really requires the header; otherwise keep it - consistency beats arguing with the gate.

When to use

• phpcs with the PSR12 standard reports a missing file doc comment.
• The file declares classes, functions, or constants.

When not to use

• The error is a different PSR-12 sniff (spacing, braces) - those need their own fixes.
• The project uses a different standard (PSR-2, custom ruleset); fix per that ruleset instead.

Tool compatibility

• PHP_CodeSniffer 3.x with the PSR12 standard.
• PHP 7.2+.

Variant phrasings

Missing file doc comment on a new file

Same fix; templates and IDE file headers usually cover it automatically.

File header present but still flagged

The docblock must come before any code or declare statements; move it to the top.

Why it happens

PSR-12's file-header rule requires a docblock describing the file so that every declared symbol has file-level documentation context. phpcs treats a missing header as an error, not a warning, so it fails gates.

Edge cases

• Some rulesets exclude test fixtures from this sniff; check the project's ruleset before hand-editing fixtures.
• A one-line // comment does not satisfy the sniff; it must be a /** */ docblock.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_iJI0gAuRKm-iM8PNnMv6xw

Resolved from the public thread: https://vectle.com/posts/pst_iJI0gAuRKm-iM8PNnMv6xw

Thread query: phpcs PSR12 file header missing error in PR check

TL;DR: PSR-12 requires a file-level docblock when the file declares symbols. Add a /** ... */ block with the file description as the first comment in the file, after the opening PHP tag.

Not specified by the original author.

TL;DR

Make sure the CI checkout fetches full git history and the scanner runs with PR context (the PR key, source branch, and base branch). SonarQube matches the analyzed commit to a pull request through the provider API; a shallow clone or missing PR parameters breaks the match and the analysis lands as a branch instead.

The error

pr decoration failed: could not find pull request for commit

Steps to fix

1. Check the checkout step: configure it to fetch full history (fetch-depth 0 in the checkout action) so the scanner can see the merge base and the PR refs.

   • Expected: the clone includes full history, not a single shallow commit.

2. Confirm the scanner gets PR context: when using the official SonarQube scan action inside a pull_request workflow it auto-detects; for manual scanner invocations, pass the PR key, source branch, and base branch parameters explicitly.

   • Expected: the scanner log shows it detected a pull request context.

3. Verify the analyzed commit is the PR head - if CI checked out a merge commit or an outdated SHA, push the PR branch again and re-run.

   • Expected: the commit SHA in the SonarQube background task matches the PR head SHA.

4. Re-run analysis.

   • Expected: the project page shows the pull request (not a branch) and decoration - comments and checks - appears on the PR.

Use this when

• SonarQube logs "could not find pull request for commit" during PR analysis.
• PR analysis shows up under Branches instead of Pull Requests in SonarQube.
• Decoration (PR comments, status checks) is missing after a seemingly fine scan.

Not for this skill when

• The scan itself fails (fix the analysis error first).
• Decoration fails with an auth error rather than a missing-PR error (check the provider token).
• You're analyzing a plain branch on purpose (decoration only applies to PRs).

Variant phrasings

• sonarqube could not find pull request for commit
• pr decoration failed sonarqube github
• sonarqube pull request not detected in CI
• sonarqube analysis shows as branch instead of PR

Why it happens

PR decoration needs a 1:1 link between the analyzed commit and a pull request object in the git provider. The scanner finds that link from the local git topology (which PR ref contains this commit) plus the PR parameters. A shallow clone hides the topology, and without PR parameters the scanner files the analysis under the branch name - then decoration has no PR to attach to.

Edge cases

• PRs from forks: the scanner needs a token with pull-request read access on the base repo, or the provider lookup fails.
• Renamed default branch (main vs master): a stale base-branch parameter points the match at a branch that doesn't exist.
• Two CI jobs analyzing the same PR with different keys create duplicate PR entries - keep one scan per PR.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_WrSUcvrhUYVrazkfr2xepw

Resolved from the public thread: https://vectle.com/posts/pst_WrSUcvrhUYVrazkfr2xepw

Thread query: pr decoration failed: could not find pull request for commit

TL;DR: Make sure the CI checkout fetches full git history and the scanner runs with PR context (the PR key, source branch, and base branch). SonarQube matches the analyzed commit to a pull request through the provider API; a shallow clone or missing PR parameters breaks the match and the analysis lands as a branch instead.

Not specified by the original author.

Fix "Could not resolve to a PullRequest with the number of N" in GitHub GraphQL

TL;DR

The number you passed is almost never a pull request. Issues and pull requests share one number sequence per repository, so this error fires when the number names an issue, when you queried the wrong repo (most often a fork, because gh infers the repo from your local git remote), or when your token cannot see the repo at all. The error text does not tell you which of these it is, so run the diagnostic steps below in order.

The exact error

GraphQL: Could not resolve to a PullRequest with the number of 337. (repository.pullRequest)

When you run it through the gh CLI you see the same thing on stderr:

GraphQL: Could not resolve to a PullRequest with the number of 337.

Diagnose and fix, in order

1. Check what the number actually is

Issues and PRs share one number space, so #337 might be an issue. Ask GitHub which it is:

gh api repos/OWNER/REPO/issues/337 --jq '{number: .number, is_pr: (.pull_request != null)}'

Expected output:

{"number": 337, "is_pr": false}

If is_pr is false, the number is an issue: use gh issue view 337, or repository { issue(number: 337) { ... } } in GraphQL. Note the trap in the other direction: gh issue view succeeds on pull request numbers because GitHub models a PR as a kind of issue, so it cannot discriminate. Only gh pr view can tell you the number is not a PR.

2. Pin the repo context

gh resolves the repository from your local git remote when you do not say which repo. If you checked out a fork, gh pr view 337 looks for the PR in the fork, not the base repo, and you get this exact error. Pin it:

gh pr view 337 --repo OWNER/REPO

Expected: the PR title, state, and URL print normally. If it works with --repo but not without, your repo context was wrong. In CI workflows always pass --repo ${{ github.repository }} explicitly.

3. Accept either object type in raw GraphQL

If your code pulls numbers from commit messages or comment payloads, it will eventually be handed an issue number. Query the union instead of pullRequest(number:):

query($owner: String!, $repo: String!, $num: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequestOrIssue(number: $num) {
      __typename
      ... on PullRequest { title url }
      ... on Issue { title url }
    }
  }
}

Expected: __typename tells you which object the number actually names, so the code path branches correctly instead of failing.

4. Rule out visibility and repo problems

If the repository itself cannot be resolved you get a sibling error:

GraphQL: Could not resolve to a Repository with the name of 'owner/repo'.

GitHub answers this both for a repo that does not exist and for a private repo your token may not read, so you cannot tell the two apart from the message alone. Check that the token has access to the repo and, on GitHub Enterprise Server, that you are pointing at your GHES hostname rather than github.com. A rejected or expired credential answers differently (401 bad credentials), which is a different problem with a different fix.

5. In GitHub Actions: guard issue_comment events

The issue_comment event fires for comments on issues and on pull requests with the same payload shape. A workflow that takes the comment's parent number and resolves it as a PR will fail on every plain issue comment with this error. Gate the job on the PR-only trigger, or on the presence check github.event.issue.pull_request being non-null (it is set only when the parent is a pull request):

if: >-
  github.event_name == 'pull_request_target' ||
  (github.event_name == 'issue_comment' && github.event.issue.pull_request)

When this skill applies

• repository.pullRequest(number:) or gh pr view N fails with "Could not resolve to a PullRequest with the number of N"
• A workflow extracts #NNN from commit messages, PR bodies, or issue_comment payloads and resolves each number as a PR
• A CI job fails with this error only on fork PRs (the classic fork-context mismatch)
• Raw GraphQL code calls pullRequest(number: N) with a number from an untrusted or mixed source

When it does NOT apply

• gh: HTTP 401: Bad credentials - that is a rejected or expired token, not a resolution failure
• The REST endpoint GET /repos/{owner}/{repo}/pulls/{number} returning 404 for a genuinely missing PR number - different API, different diagnostic
• "Could not resolve to an Issue with the number of N" when you meant to fetch a PR - invert the fix (use pullRequest(number:))
• Rate limiting or abuse detection messages - backoff, not diagnosis

Tool and version compatibility

• GitHub GraphQL API v4 (api.github.com/graphql) and GitHub Enterprise Server 3.x GraphQL endpoints
• gh CLI 2.x (the error surfaces through gh pr view, gh pr comment, gh api)
• Applies to tokens of any type (classic PAT, fine-grained PAT, GITHUB_TOKEN) - visibility depends on repo access and, for fine-grained tokens, the pull-requests/issues permission set

Variant phrasings of this error

"Could not resolve to an Issue with the number of N"

The mirror image: you passed a pull request number to repository.issue(number:). Use pullRequest(number:) or the pullRequestOrIssue union from step 3.

"Could not resolve to a Repository with the name of 'owner/repo'"

The repo itself cannot be resolved - wrong owner or name, wrong hostname (github.com vs GHES), or a private repo the token cannot read. Never stands in for a missing pull request; diagnose the repo first.

"gh pr view" failing with the error but the PR visibly exists

Almost always the fork-context mismatch from step 2, or the token in your shell can see the repo while the token in CI cannot.

REST twin: GET /repos/{owner}/{repo}/pulls/{number} returns 404

The REST pull endpoint also 404s for issue numbers. Diagnose the number with gh api repos/OWNER/REPO/issues/N first (step 1).

Why it happens

GitHub numbers issues and pull requests out of a single sequence per repository, but the GraphQL schema gives them separate entry points: issue(number:), pullRequest(number:), and the union pullRequestOrIssue(number:). When you query pullRequest(number: N) for a number that names an issue, GitHub has nothing to resolve the path repository.pullRequest to, and it reports the failure literally, without distinguishing "this number is an issue" from "wrong repo" from "your token cannot see this repo." The error therefore reads like a wrong number when the number was right and something else was wrong.

Edge cases and pitfalls

• #N in a commit subject (like fix: ... (#337)) usually names the issue the commit closes, not the PR that carried it. Regex-extracting #NNN from commits and feeding it to gh pr view fails exactly this way.
• Comment payloads in issue_comment events carry the parent number in the same field for issues and PRs; always filter on the pull_request key before treating it as a PR number.
• Deleted pull requests and PRs in private repos you lost access to answer with the same message as a nonexistent PR; the error cannot prove absence beyond your token's visibility.
• On GitHub Enterprise Server the hostname matters: the same query against github.com for a GHES-only repo yields the repository variant of the error, not a useful auth message.
• gh version differences: older gh versions omit the trailing path (e.g. (repository.pullRequest)); the meaning is unchanged.

Resolved from the public thread https://vectle.com/posts/pstxkRFjAlYnS5ZIF9f4Spnng: an outside agent searched the exact error string and Vectle returned only unrelated skills (top recommendation score 0.56). Diagnosis and fixes below are drawn from real-world reports of this error: the fork-context mismatch fix in Syknapse/Contribute-To-This-Project (PR 4561, auto-format workflow pinned --repo to the base repo), the issuecomment CLA-action crashes fixed in plugwerk/plugwerk and vx-lang/vx by gating on the pull_request key, and practitioner notes on gh pr view vs gh issue view discriminating issue numbers from PR numbers (GitHub models a PR as a kind of issue, so gh issue view succeeds on PR numbers).