Templates¶

Templates define which checklist items appear when an issue is opened. They are plain Markdown files stored in your repositories.

File location¶

When an issue is opened, the app searches for a template in this priority order, stopping at the first file found:

Priority	Location	Use case
1	`{issue-repo}/.github/CHECKLIST/{type}.md`	Repo-specific overrides (can be restricted — see below)
2	`{org}/.github-private/.github/CHECKLIST/{type}.md`	Org-wide private defaults
3	`{org}/.github/.github/CHECKLIST/{type}.md`	Org-wide public defaults

{type} is the slugified value of the issue's native type name:

Issue type name	File name
`Bug`	`bug.md`
`Feature`	`feature.md`
`Bug Report`	`bug-report.md`

If no template is found in any location, a built-in minimal default is used.

Restricting repo-level overrides¶

By default any repo can place its own template at priority 1. You can restrict this per-repo using the repoOverrides setting in .github/checklist-app.json. When a repo is restricted, its .github/CHECKLIST/ files are skipped and resolution starts at priority 2.

See Configuration reference → repoOverrides for details.

Caching¶

Resolved templates are cached in Cloudflare KV to avoid repeated GitHub API calls. By default templates are cached for 5 minutes (300 seconds). You can adjust this per-org in .github/checklist-app.json:

{ "cacheTtlSeconds": 60 }

Value	When to use
`60`	Actively developing templates — changes appear quickly
`300`	Default — good balance for most teams
`1800`	High-volume orgs — maximizes cache hits (hard ceiling)

Bulk imports: Each cache miss makes up to 3 GitHub API calls. If you're migrating issues in bulk (bug bash, tracker migration, scripts), a warm cache after the first issue means subsequent issues are free. Stagger scripts to allow the first event to populate the cache before the rest follow.

Enforcement level¶

Templates can declare per-checklist behaviour using a YAML frontmatter block at the top of the file:

---
enforcementLevel: Block
exceptionApproversTeam: security-leads
---

## Security

- [ ] Security review completed

Both fields are optional and independent — use one, both, or neither.

`enforcementLevel`¶

Controls what happens when the issue is closed while items are still incomplete.

Value	Behavior
`Advise`	Does nothing — the checklist is informational only
`Warn`	Posts a comment listing incomplete items but lets the close proceed
`Block`	Reopens the issue and posts a comment listing incomplete items

Defaults to Warn when omitted. Use Block for compliance-critical templates (security audits, legal sign-offs). Use Advise for optional checklists where the team should see the items but not be gated.

`exceptionApproversTeam`¶

The GitHub team slug whose members are permitted to approve exception items on this checklist. When omitted, falls back to the exceptionApproversTeam value in checklist-app.json.

---
exceptionApproversTeam: legal-approvers
---

This lets different checklists route exceptions to different teams — a security template to security-leads, a legal template to legal-approvers — while keeping a sensible org-wide default in config.

Template format¶

Templates are standard Markdown with GFM task-list items. Sections are ## headings; items are - [ ] lines.

## Security

- [ ] [Security review completed](https://wiki.example.com/security-review)
- [ ] PII audit done

## Release

- [ ] Changelog entry added
- [ ] Linked to milestone

Items with doc links¶

Wrap the label in a Markdown link to attach a documentation URL:

- [ ] [Label text](https://link-to-docs)

The link is informational only — clicking it opens the URL in a new tab. It is never required to save an item's state.

Items without doc links¶

- [ ] Plain label text

Sections¶

Group related items under ## headings. Each heading becomes a collapsible section in the checklist UI.

## Pre-merge

- [ ] Tests passing
- [ ] Code review approved

## Post-merge

- [ ] Deployed to staging
- [ ] QA sign-off

Sections are optional. Items at the top of the file before any heading are placed in an implicit "General" section.

When the issue type changes¶

If the issue type is changed after the checklist has been posted, the app:

Re-resolves the template for the new type
Runs the merge algorithm:
Items whose label text matches an existing item carry forward their status and approver
New items (not in the old template) are added as pending
Removed items (not in the new template) are dropped
Updates the managed comment
Posts a bot reply: "Checklist updated — N items added, M items removed, K items carried over."

When an issue is transferred¶

Same merge behavior as a type change, but the template is resolved from the destination repo's context. The app must be installed on the destination org/repo to receive the transfer event.