docs(api): label the per-scope application key auth schemes - #12368
Merged
Conversation
Contributor
Merge Protections🟢 All 6 merge protections satisfied — ready to merge. Show 6 satisfied protections🟢 🤖 Continuous Integration
🟢 👀 Review Requirements
🟢 Enforce conventional commitMake sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
🟢 🔎 Reviews
🟢 📕 PR description
🟢 🚦 Auto-queueWhen all merge protections are satisfied, this pull request will be queued automatically. |
There was a problem hiding this comment.
Pull request overview
Updates the API reference’s authentication badge labeling to handle the engine’s upcoming split of the scope-blind ApplicationAuth scheme into scope-specific application key schemes, while keeping compatibility with the currently shipped schema.
Changes:
- Extend the auth scheme label map to include
AdminApplicationKeyandCIApplicationKey(while retainingApplicationAuthfor backward compatibility). - Add unit tests covering the new labels and the existing “fallback to raw scheme name” behavior.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| src/components/ApiReference/openapi.ts | Adds labels for the new per-scope application key security scheme names so endpoint auth badges remain human-readable. |
| src/components/ApiReference/openapi.test.ts | Adds targeted tests for the new auth scheme labels and the unmapped-scheme fallback behavior. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The /api reference renders each endpoint's accepted credentials from a hardcoded map of security scheme name to prose, falling back to the raw scheme name on a miss. The engine is splitting the scope-blind `ApplicationAuth` scheme into `AdminApplicationKey` and `CIApplicationKey`, so every endpoint on the page would read as a camel-case identifier once that schema syncs here. Add both labels. `ApplicationAuth` stays: `public/api-schemas.json` is synced from the engine by a bot on its own schedule, so the shipped schema still names it until that lands. Verified against the regenerated schema rather than assumed: building the site with it renders 61 "Admin Application Key", 14 "CI Application Key" and 60 "GitHub Token" badges, and no raw scheme names. Related to MRGFY-8646 Change-Id: Ibeb5562dd6ac00add93d7ad201e112de95351ce7
Member
Author
Revision history
|
sileht
force-pushed
the
devs/sileht/mrgfy-8646-api-reference-auth-scheme-labels/label-per-scope-app-key-auth-schemes--beb5562d
branch
from
August 12, 2026 20:24
5961578 to
45c1a98
Compare
sileht
marked this pull request as ready for review
August 12, 2026 20:58
jd
approved these changes
Aug 13, 2026
kozlek
approved these changes
Aug 13, 2026
Contributor
Merge Queue Status
This pull request spent 3 minutes 58 seconds in the queue, including 2 minutes 39 seconds running CI. Required conditions to merge
|
60 tasks
mergify
Bot
deleted the
devs/sileht/mrgfy-8646-api-reference-auth-scheme-labels/label-per-scope-app-key-auth-schemes--beb5562d
branch
August 13, 2026 07:07
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The /api reference renders each endpoint's accepted credentials from a
hardcoded map of security scheme name to prose, falling back to the raw
scheme name on a miss.
The engine is splitting the scope-blind
ApplicationAuthscheme intoAdminApplicationKeyandCIApplicationKey, so every endpoint on thepage would read as a camel-case identifier once that schema syncs here.
Add both labels.
ApplicationAuthstays:public/api-schemas.jsonissynced from the engine by a bot on its own schedule, so the shipped
schema still names it until that lands.
Verified against the regenerated schema rather than assumed: building
the site with it renders 61 "Admin Application Key", 14 "CI Application
Key" and 60 "GitHub Token" badges, and no raw scheme names.
Related to MRGFY-8646
Left out on purpose
Four things surfaced while verifying this. None are regressions from these
lines. Flagging rather than widening the diff.
Open, but a copy decision —
src/pages/api/index.astro:47hardcodes"All endpoints require a Bearer token. Two authentication methods are
supported: Application Key, GitHub Token". Once the schema syncs, the badges
read
Admin Application Key/CI Application Key, so the intro introducesa name the badges never use. Worth being precise: unlike Bump loader-utils from 1.4.0 to 1.4.2 #2 this is not
factually wrong — there really are two auth methods, one of which has two
scopes — it is a naming mismatch, which makes it lower priority. The right
rewording depends on the same scope answer as Bump loader-utils from 1.4.0 to 1.4.2 #2, so it is deliberately not
in this PR.
Separately, the "All endpoints require a Bearer token" half of that sentence
is already false on
main, independent of any of this:GET /badges/{owner}/{repository},.pngand.svgpublish nosecurityatall. Pre-existing, belongs in the same rewrite whenever someone takes it.
Not a docs fix —
src/content/docs/api/usage.mdx:42says theadminscope grants "Full access to all API endpoints", which the new schema
contradicts:
PUTandPOST /repos/{owner}/{repository}/pulls/{number}/scopesdeclare
CIApplicationKeyonly, andget_by_key_and_scopesfilters onstrict scope membership with no superset, so an admin key really is refused.
Deliberately not touched here: whether
adminought to subsumeciis aproduct question. If the intent is "admin can do everything" then the engine
is wrong and this line is right. Being raised with Mehdi on the monorepo side.
Fixed at the source, no action here. Badge order was not deterministic:
45 operations emitted
(AdminApplicationKey, GitHubTokenBearerAuth)and 4the reverse, for the same OR-set. Now canonical for every operation in
Mergifyio/monorepo#38586, plus the future and internal specs. My first guess
at the cause was wrong — it is not set iteration in the new rewrite and it
predates it: FastAPI emits requirements in dependency-resolution order, and
the 4 outliers carry a delegation role whose injected guard takes the logged
user before the application dependency. Fixed there rather than sorted here,
so the live
openapi.jsonand generated clients get it too.Noted, no action wanted. The engine ships a
descriptionper scheme("
adminscope, reaches every endpoint" / "ciscope, reaches CI Insightsendpoints only", both linking to the usage page).
Endpoint.astrorendersonly the badge label, so it does not surface on this page — correcting my
earlier phrasing, that copy is not dead: it reaches
api.mergify.com/v1/openapi.json, generated clients, and Scalar/Swagger-stylerenderers. Not rendering it here is the intended state.
I also skipped a test asserting every scheme in the shipped schema has a label.
It would turn the schemas-sync bot PR red for a cosmetic label and block the
config and CLI schema syncs riding along in it, in exchange for replacing a
graceful fallback with a hard failure.