# `checklist`

The `checklist` setting allows you to require reviewers to complete a verification checklist before their review counts toward scope satisfaction. This is designed for compliance sign-off where reviewers need to verify specific criteria before approving.

## Overview

When a scope has a `checklist` defined, reviewers must complete the checklist through PullApprove. Submitting the checklist automatically creates an approval on GitHub with the checklist responses included in the review body.

### Workflow

The checklist is only for the final approval - regular code review still happens through GitHub:

1. Reviewer examines the code on GitHub and leaves comments or requests changes as usual
2. Once the reviewer is ready to approve, they click the checklist link in the PullApprove status comment
3. Reviewer completes the checklist on PullApprove
4. PullApprove submits an **approval** to GitHub with the checklist responses in the review body
5. The review counts toward scope satisfaction

Approving directly on GitHub (without the checklist) will not satisfy the scope. The reviewer must submit their approval through PullApprove to complete the checklist requirements.

## Configuration

The `checklist.items` array defines the checklist items.

```toml
[[scopes]]
name = "security-review"
reviewers = ["security-team"]
checklist.items = [
  { label = "Code does not introduce security vulnerabilities" },
  { label = "No secrets or credentials are hardcoded" },
  { label = "Input validation is properly implemented", required = false, notes = "required_if_unchecked" },
  { label = "I reviewed the OWASP Top 10 checklist", required = false },
]
```

## Item Settings

Each checklist item supports three settings: `required`, `notes`, and `help`.

### `required` (default: `true`)

Controls whether the item must be checked to submit the checklist.

```toml
# Must be checked (default)
{ label = "I reviewed all changes" }

# Optional - can be skipped
{ label = "I tested the changes locally", required = false }
```

### `notes`

Controls when/if notes are shown and required for an item. Available options:

| Value | Description |
|-------|-------------|
| `"disabled"` | No notes field |
| `"optional"` | Notes field available but not required (default) |
| `"required"` | Notes always required |
| `"required_if_checked"` | Notes required when item is checked |
| `"required_if_unchecked"` | Notes required when item is not checked |

#### Examples

**Optional item with required explanation when skipped:**

```toml
{ label = "I verified API contract changes", required = false, notes = "required_if_unchecked" }
```

If the reviewer leaves this item unchecked, they must provide notes explaining why it doesn't apply.

**Always require notes:**

```toml
{ label = "I tested the changes", notes = "required" }
```

The reviewer must provide notes explaining how they tested, regardless of whether the item is checked.

**Notes required when checked:**

```toml
{ label = "I made additional changes", notes = "required_if_checked" }
```

If the reviewer checks this item, they must explain what changes they made.

### `help`

Optional help text displayed below the checklist item label. Use this to provide additional context or instructions for the reviewer.

```toml
{ label = "This PR does not require compliance changes", help = "If it does, add the compliance tracker ticket number in the notes.", required = false, notes = "required_if_unchecked" }
```

The help text appears in a smaller, muted style below the main label, giving reviewers context before they interact with the checkbox or notes field.

## Reviewers Assigned to Multiple Scopes

When a reviewer is assigned to multiple scopes with checklists, PullApprove shows all their pending checklists on a single form. Submitting the form creates one GitHub approval containing all checklist responses.

This follows from how GitHub reviews work: each user has one "current" review on a PR, and submitting a new review supersedes any previous one. Since checklist responses are embedded in the approval's body, all checklists must be included in that single approval.

**Identical checklists:** If multiple scopes define the same `checklist.items`, they produce the same checklist hash. The reviewer sees it once on the form, and that one response satisfies all matching scopes.

```toml
# These two scopes have identical checklists - reviewer completes it once
[[scopes]]
name = "frontend"
paths = ["frontend/**/*"]
checklist.items = [
  { label = "I reviewed the changes" },
]

[[scopes]]
name = "backend"
paths = ["backend/**/*"]
checklist.items = [
  { label = "I reviewed the changes" },
]
```

**Different checklists:** If scopes have different checklists, the reviewer sees each one on the form and must complete all of them before submitting.

## Checklist Versioning

Checklist submissions are tied to a hash of the checklist's semantic content. Changes to the following invalidate existing submissions:

- Item `label`, `required`, `notes`, or `help`
- Adding or removing items
- Reordering items

## Tamper Detection

Checklist submissions include a checksum (SHA-256 hash) of the review body content. This provides tamper detection - if someone edits the review body on GitHub after submitting through PullApprove, the checksum will no longer match and the review will not count toward scope satisfaction.

The checksum is:
- Displayed in the review footer on GitHub (first 8 characters)
- Shown on the checklist submission verification page in PullApprove
- Automatically verified during PR processing

If a review's body is modified after submission, the reviewer will need to resubmit the checklist to create a new valid approval.

## Limitations

### Reviewed-for

The `checklist` setting cannot be used with [`reviewed_for = "required"`](/docs/config/scopes/reviewed-for/) on the same scope. Both features serve the same purpose - requiring explicit scope acknowledgment before an approval counts. Use one or the other.

### Author Value

The [`author-value`](/docs/config/scopes/author-value/) setting awards points automatically when the PR author is in the scope's reviewers list. These points do not require a checklist - checklists only apply to actual reviews submitted by other team members.

### Large Scale Changes

Checklists are defined per-scope and only apply to reviews that match scopes. [Large scale changes](/docs/config/large-scale-change/) bypass scope processing entirely, so checklists cannot be used with them.

If you need verification requirements for large scale changes, consider using a separate review process or workflow outside of PullApprove.