docs(api): document what the ci application key scope actually grants

[sileht]

The ci scope was one line about uploading test results and CI Insights
data. A ci key also quarantines and unquarantines tests, which decides
whether a failing test blocks a merge, and it works on every repository of
the account with no GitHub repository role attached. A customer handing
that key to their pipeline had no way to know.

Audited the engine routes that accept a ci key and rewrote both scope
bullets from that set. The admin bullet was wrong too: it claimed full
access to all API endpoints, but the results upload and the Merge Queue
Scopes call accept a ci key only.

Two other errors on the page, found while checking the above:

• The GET /v1/application response example was stale: the API returns a
  UUID id, a scope field and account_scope, not an integer id and
  a github_account object.
• The GitHub PAT example called GET /v1/application, the one endpoint on
  the page that rejects PATs.

merge-queue/scopes.mdx showed its curl with a generic application key,
where only a ci key works.

Fixes MRGFY-8645

[mergify]

Merge Protections

🟢 All 6 merge protections satisfied — ready to merge.

Show 6 satisfied protections

🟢 🤖 Continuous Integration

• all of:
  • check-success = build
  • check-success = lint
  • check-success = test
  • any of:
    • check-success = test-broken-links
    • label = ignore-broken-links
  • any of:
    • check-success=Cloudflare Pages
    • -head-repo-full-name~=^Mergifyio/

🟢 👀 Review Requirements

• any of:
  • #approved-reviews-by >= 2
  • author = dependabot[bot]
  • all of:
    • author = mergify-ci-bot
    • -head ~= ^docs-agent/

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 🔎 Reviews

• #changes-requested-reviews-by = 0
• #review-requested = 0
• #review-threads-unresolved = 0

🟢 📕 PR description

• body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

[Copilot]

Pull request overview

Updates the documentation to accurately describe what Mergify application key scopes (especially ci) allow, and clarifies how application keys relate to GitHub roles and owner requirements across the docs site.

Changes:

• Expands /api/usage to document ci vs admin scope behavior and refreshes the GET /v1/application example.
• Clarifies in /security that application keys are not governed by GitHub repository roles (and tightens the “Owner” requirement wording).
• Notes on Merge Queue scopes that the relevant REST endpoint requires a ci application key.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/content/docs/security.mdx	Clarifies access-control model for users vs application keys, and refines Owner-role wording for creating admin keys.
src/content/docs/merge-queue/scopes.mdx	Documents that setting merge queue scopes via API requires a ci application key (and that admin is rejected).
src/content/docs/api/usage.mdx	Expands application key scope documentation and updates API response / PAT examples to match current behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sileht]

Revision history

#	Type	Changes	Reason	Date
1	initial	a416d9d		2026-08-12 17:59 UTC
2	content	a416d9d → 122cf92		2026-08-12 17:59 UTC
3	content	122cf92 → 73135b3		2026-08-12 18:27 UTC
4	content	73135b3 → 2d72d85		2026-08-12 18:32 UTC
5	content	2d72d85 → a3fbbfe		2026-08-12 18:42 UTC
6	content	a3fbbfe → b730ae2		2026-08-12 19:02 UTC
7	content	b730ae2 → 0e98404		2026-08-12 19:03 UTC
8	content	0e98404 → fe6c15b (raw)		2026-08-12 19:06 UTC

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-08-13 07:03 UTC · Rule: default · triggered by merge protections
• ✅ Checks passed · on draft merge queue: checking main (9126fe8), #12367 and #12366 together #12374
• ✅ Merged — 2026-08-13 07:07 UTC · at fe6c15b729865c576c98718e5de9f0fc1943f5ea · squash

This pull request spent 3 minutes 35 seconds in the queue, including 2 minutes 2 seconds running CI.

Required conditions to merge

• github-review-approved [🛡 GitHub repository ruleset rule Require pull request for default branch]
  • docs(api): document what the ci application key scope actually grants #12366
• schedule=Mon-Fri 09:00-17:30[Europe/Paris]
• all of [🛡 Merge Protections rule Enforce conventional commit]:
  • title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:
    • docs(api): document what the ci application key scope actually grants #12366
• all of [🛡 Merge Protections rule 👀 Review Requirements]:
  • any of:
    • #approved-reviews-by >= 2
      • docs(api): document what the ci application key scope actually grants #12366
    • author = dependabot[bot]
      • docs(api): document what the ci application key scope actually grants #12366
    • all of:
      • author = mergify-ci-bot
        • docs(api): document what the ci application key scope actually grants #12366
      • -head ~= ^docs-agent/
        • docs(api): document what the ci application key scope actually grants #12366
• all of [🛡 Merge Protections rule 📕 PR description]:
  • body ~= (?ms:.{48,})
    • docs(api): document what the ci application key scope actually grants #12366
• all of [🛡 Merge Protections rule 🔎 Reviews]:
  • #changes-requested-reviews-by = 0
    • docs(api): document what the ci application key scope actually grants #12366
  • #review-requested = 0
    • docs(api): document what the ci application key scope actually grants #12366
  • #review-threads-unresolved = 0
    • docs(api): document what the ci application key scope actually grants #12366
• all of [🛡 Merge Protections rule 🤖 Continuous Integration]:
  • all of:
    • check-success = build
    • check-success = lint
    • check-success = test
    • any of:
      • check-success = test-broken-links
      • label = ignore-broken-links
        • docs(api): document what the ci application key scope actually grants #12366
    • any of:
      • check-success=Cloudflare Pages
      • -head-repo-full-name~=^Mergifyio/
        • docs(api): document what the ci application key scope actually grants #12366