Skip to content

Improve documentation for requisite API token permissions #353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lelia wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Improve documentation for requisite API token permissions #353

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
468ea97
Document the API token permissions a run actually needs
lelia Sep 11, 2026
1e99f3c
Name the token scopes and flag the two the setup guide omits
lelia Sep 11, 2026
69f8871
Correct which runs compare, after the 2.9.0 flow change
lelia Sep 23, 2026
c7b9938
Bump to 2.9.8
lelia Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Correct which runs compare, after the 2.9.0 flow change 
#302 moved SCM-integrated non-PR/MR pipelines onto a full scan: create_scm_scan
now sends only a "diff" event type to create_new_diff and everything else,
default-branch pushes included, to create_full_scan_with_report_url.

The permission docs asserted the opposite -- that plain pushes also reach the
diff-scans path -- which was true when they were written against 2.8.1 and is
not true now. Replace the claim with a table of which runs compare, and keep
the old behavior as a note, since the warning still shows up in logs from
pre-2.9.0 runs with no pull request in sight.

Re-verified the rest against 2.9.7: SDK call surface, the four sys.exit(2)
sites, the temporary empty baseline, and the reachability scan ID are all
unchanged.
  • Loading branch information
@lelia
lelia committed Sep 23, 2026
commit 69f88719ac2f0161723a617410f0b75cee1da05b
9 changes: 5 additions & 4 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,11 @@
Recorded the converse too: `socketcli` makes no triage or security-policy calls, so
three of the nine scopes that guide lists are not exercised by this CLI.
- Corrected the scan-comparison guidance. The `APIAccessDenied` fallback was documented
as a PR/MR-only condition, but it applies to any run that produces a diff, including
plain pushes on the default branch. The guidance also listed `full-scans:list`
alongside the two `diff-scans:*` scopes, which points readers at a permission the
fallback path demonstrably already has.
as a PR/MR-only condition; it applies to any run that produces a diff, which since
2.9.0 means PR/MR events and runs without an SCM integration. Added a table of which
runs compare, and a note that before 2.9.0 SCM-integrated branch pushes compared too.
The guidance also listed `full-scans:list` alongside the two `diff-scans:*` scopes,
which points readers at a permission the fallback path demonstrably already has.
- Documented three outcomes that are expected but read as failures: the temporary empty
baseline created on a repository's first scan, which does not appear in the dashboard;
the reachability scan ID being a `tier1ReachabilityScanId` rather than a full scan ID,
Expand Down
20 changes: 14 additions & 6 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,19 +76,27 @@ identifiers for them are not published.

## `APIAccessDenied` on the scan comparison

Any run that produces a diff — PR/MR events, **plain pushes on the default branch**,
and `--enable-diff` / `--ignore-commit-files` runs without an SCM integration — first
tries the diff-scans endpoints. A token without the `diff-scans:*` permissions logs a
warning and silently continues on the older path:
Any run that produces a diff first tries the diff-scans endpoints. A token without the
`diff-scans:*` permissions logs a warning and silently continues on the older path:

```
Diff scan comparison failed with APIAccessDenied(Insufficient permissions), falling back to the streaming scan comparison
```

The scan still succeeds and the diff results are the same, so this is easy to miss.

Note that this is *not* limited to PR/MR runs. A pipeline that only ever scans pushes
(`--pr-number 0 --default-branch`) still hits it.
**Which runs produce a diff.** As of 2.9.0:

| Run | Compares? |
|:---|:---|
| PR/MR event with `--scm github` / `--scm gitlab` | Yes |
| Any other event with `--scm github` / `--scm gitlab` (branch and default-branch pushes) | No — creates a full scan |
| No SCM integration (`--scm api`, the default), including `--enable-diff` and `--ignore-commit-files` | Yes |
| No supported manifest in the changed-file set | No — falls back to a full scan |

Before 2.9.0 an SCM-integrated branch push also compared, so a pipeline scanning only
pushes (`--pr-number 0 --default-branch`) hit this too. If you are diagnosing an older
run, that is why the warning can appear in a log with no pull request in sight.

**Which permission is missing.** The fallback path is `GET orgs/{org}/full-scans/diff`,
a full-scans read. If you see the fallback produce results, your token already has
Expand Down
Loading