Skip to content

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 both conditions are 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.

Both are required — being in the approvers team does not allow self-approval.

Warning

The issue opener cannot approve their own exceptions, even if they are a member of the exception-approvers team.

Setting up the approvers team

  1. Go to your GitHub org → Teams → New team
  2. Name it whatever you like — the default the app looks for is exception-approvers
  3. Add members who are trusted to approve exceptions

To use a different team name, set exceptionApproversTeam in .github/checklist-app.json:

{ "exceptionApproversTeam": "security-leads" }

Individual templates can also override this with exceptionApproversTeam in their frontmatter, routing exceptions for that checklist type to a specific team. See the Templates guide for details.

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

Approval flow

Tip

There is no reason field in the editor yet. Use a regular GitHub issue comment to document why an exception is being requested — the comment thread serves as the audit trail.

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

Once approved, the item shows ✅ Approved by @alice in the checklist editor and the bot comment is updated to reflect the new state.

Revoking an exception

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