amirbena / amirbena/code-review-skill

Research GitHub status/check integration

Open
#91 0 comments 0 reactions 1 assignee Claimed by @amirbena View on GitHub
area:github-integration maintainer-led priority:P2 type:research
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.