amirbena / amirbena/code-review-skill
Research GitHub status/check integration
- Dominant language
- Python
- Stars
- 7
- Forks
- 2
- Avg merge
- 27m
- Merged PRs (30d)
- 188
Description
## Type
Research
## Area
GitHub Integration
## Priority
P2 — Medium
## Problem
`skills/github-pr-review/policies/review-status-enforcement.md` (shipped via
#34 / PR #112) deliberately declines to pick a mechanism: "A concrete
mechanism (the Commit Status API or the Checks API) is an implementation
of this contract, not a canonical requirement; pick the smallest one the
available integration supports." Permission/auth requirements for either
mechanism (`gh`/`gh api` token scopes vs GitHub App installation) are not
documented anywhere in the repo, and no official GitHub documentation is
cited.
## Goal
Pick one mechanism (Commit Status API or Checks API) for publishing the
aggregated review status, with rationale, and document what permissions
it needs under `gh`/`gh api` auth vs a GitHub App.
## Scope
- Compare the Commit Status API and the Checks API against this policy's
actual needs (one stable aggregated context, SHA-bound, upsert
semantics, read-back for enforcement-state detection) and recommend one.
- Document the permission/auth requirements for the recommended mechanism
under ordinary `gh`/`gh api` token auth, and note whether/when a GitHub
App installation would be required instead.
- Cite official GitHub documentation (docs.github.com) for the API(s)
compared and the permission model described.
## Non-Goals
- Re-deriving anything already decided in
`review-status-enforcement.md` (context identity, SHA binding, verdict
mapping, authorization split, enforcement-state detection, idempotency)
— this issue is scoped to the mechanism pick and its permissions only.
- Implementing publication.
## Acceptance Criteria
- [ ] Commit Status API vs Checks API compared against this policy's
stated needs.
- [ ] A recommended mechanism with rationale is recorded.
- [ ] Permission and auth requirements (`gh`/`gh api` token scopes vs
GitHub App) are documented.
- [ ] Artifact cites official GitHub docs (docs.github.com).
## Dependencies
Depends on: none
Relates: #34
Blocks: #95
Parent: #49
## Validation
- Research artifact cites official GitHub docs.
Contributor guide
Assessment
This issue has not been assessed yet.