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
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.

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.

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.