## TL;DR
SonarCloud analyzed the code as a plain branch, not as pull request 1234, so it has no PR to decorate. The analysis needs pull-request context: the PR number, head branch, and base branch, passed as analysis parameters. Run the scan on the pull_request event with a full checkout and the decoration posts. The scanner ran fine - it just did not know it was looking at a PR.

## The error
```text
sonarcloud: could not find the pullrequest with key '1234': PR decoration failed
```

## Steps

### 1. Check whether SonarCloud knows about the PR
Open the SonarCloud project, go to the branches and pull requests list, and look for PR 1234.
Expected output: the PR is missing or shows only as a branch. That confirms the analysis lacked PR context.

### 2. Confirm the workflow runs on the pull_request event
Open the workflow file and check the `on:` trigger. Scans triggered by `push` have no PR number to attach.
Expected output: you can see whether the scan runs on `pull_request`, `pull_request_target`, or only on `push`.

### 3. Give the scanner a full checkout
PR analysis needs the merge base to compute new code. Set `fetch-depth: 0` on the checkout step.
Expected output: the scanner can diff against the base branch.

### 4. Pass the pull-request analysis parameters
If you invoke the scanner directly, set the pull request key, branch, and base parameters (the sonar.pullrequest key, branch, and base properties) to the PR number, the head branch, and the base branch from the event payload. The official SonarCloud GitHub Action picks these up from the event automatically on pull_request triggers.
Expected output: the next analysis appears under the pull request entry in SonarCloud instead of the branch list.

### 5. Bind the SonarCloud project to the repo
In SonarCloud, open project settings and confirm the GitHub repository binding, and that pull request decoration is enabled for the project.
Expected output: the binding shows the right repo and decoration is switched on.

### 6. Re-run the analysis and check the PR
Re-run the workflow, then open the PR on GitHub.
Expected output: the SonarCloud check appears on the PR and the decoration posts.

## When to use
- SonarCloud check runs but the PR shows no decoration
- The error names a PR key SonarCloud cannot find
- Analysis appears under branches instead of pull requests in SonarCloud

## When not to use
- Quality gate failures (coverage, duplications, ratings)
- The SonarCloud check never runs at all (workflow trigger problem)
- Authentication failures against SonarCloud

## Tool compatibility
- SonarCloud (cloud product behavior as of 2026)
- sonarsource SonarQube scan action and the standalone scanner CLI
- GitHub Actions pull_request and pull_request_target events

## Variant phrasings
### SonarCloud PR decoration not working
Same root cause in most cases. Decoration needs PR-context analysis plus a repo binding.

### could not find the pullrequest with key on GitHub Actions
Check the event first. A scan on push to the PR branch never carries the PR key.

### SonarCloud analysis shows as branch instead of PR
The scanner fell back to branch analysis. Steps 2 and 4 fix the context.

## Why it happens
PR decoration is a lookup: SonarCloud takes the PR key from the analysis parameters and attaches results to that PR. Without the parameters, the analysis is stored as branch results, the lookup finds nothing, and decoration fails with the missing-key error.

## Edge cases
- PRs from forks: the scan needs the PR event context, which forks have, but secret handling differs. Keep the scan on pull_request, not push.
- Renamed or transferred repos: the SonarCloud binding points at the old repo path. Rebind after a transfer.
- Monorepos with multiple SonarCloud projects: each project key needs its own PR-context analysis or decoration lands on the wrong project.
- Deleted and recreated PRs: the key is the PR number, so a recreated PR reuses it, but stale branch analyses can linger.

## Provenance

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