Exception Approvals

Some checklist items can't simply be marked done — they require a second set of eyes. The Need Exception state captures this.

Who can approve

An exception approval is valid when either condition is met:

1. Different user: The approver is not the person who opened the issue.
2. Team member: The approver is a member of the exception-approvers GitHub team in your org.

Condition 2 is an alternative to condition 1 — a team member can approve their own issue's exceptions if the org grants that trust level.

Warning

Self-approval (opening an issue and approving your own exceptions) is only permitted for members of the exception-approvers team.

Setting up the approvers team

1. Go to your GitHub org → Teams → New team
2. Name it exactly exception-approvers
3. Add members who are trusted to approve exceptions without a second reviewer

The app reads team membership in real time via the GitHub API, so changes to the team take effect immediately.

Approval flow

1. A collaborator opens the checklist editor and marks an item as Need Exception
2. They enter a brief reason (optional)
3. Another team member (or an exception-approvers member) opens the editor and clicks Approve
4. The app verifies the approver's identity against the rules above via the GitHub API
5. If valid, the item transitions to exception with approvedBy set to the approver's GitHub login
6. The managed comment is updated to reflect the approval

State after approval

{
  "id": "s2",
  "label": "PII audit",
  "status": "exception",
  "approvedBy": "alice"
}

The approver's login is stored in the state blob and displayed in the checklist UI.

Revoking an exception

An approved exception can be revoked by any collaborator. Revoking resets the item to pending, clearing the approvedBy field.