Configuration Reference

Org-wide settings are stored in .github/checklist-app.json in your organization's .github repository. All fields are optional — omitting a field uses the default value.

{
  "exceptionApproversTeam": "exception-approvers",
  "cacheTtlSeconds": 300,
  "icons": {
    "pending": "⬜",
    "done": "✅",
    "na": "✖️",
    "exception_pending": "⚠️",
    "exception_approved": "☑️"
  }
}

---

Fields

exceptionApproversTeam

Type	string
Default	"exception-approvers"

The slug of the GitHub team whose members are permitted to approve exception items. The approver must be both a member of this team and a different person than the issue opener.

{ "exceptionApproversTeam": "security-leads" }

---

noTemplateBehavior

Type	"default" | "comment"
Default	"default"

Controls what happens when no checklist template is found for the issue's type in any of the three lookup locations.

Value	Behavior
"default"	Posts a checklist using the built-in General template (description clear, acceptance criteria defined, stakeholders notified)
"comment"	Posts a comment saying "No checklist template is configured for this issue type" and does nothing else

Use "comment" when you want strict template governance — issues without a configured type should be explicit about it rather than silently getting a generic checklist.

{ "noTemplateBehavior": "comment" }

---

cacheTtlSeconds

Type	number (seconds)
Default	300
Maximum	1800 (30 minutes)

How long resolved templates and this config file are cached in Cloudflare KV before being re-fetched from GitHub. Values above 1800 are silently clamped to 1800.

Set a low value (e.g. 60) while actively developing templates so changes are picked up quickly. Use a higher value in production to reduce GitHub API usage.

{ "cacheTtlSeconds": 60 }

Note: Because the config itself is cached, a change to cacheTtlSeconds won't take effect until the previously cached config expires.

---

icons

Type	object
Default	See table below

Emoji used to represent each checklist item state in the managed bot comment. Each icon is rendered as a clickable link to the checklist editor.

Key	Default	State
pending	⬜	Item not yet addressed
done	✅	Item completed
na	✖️	Item marked not applicable
exception_pending	⚠️	Exception requested, awaiting approval
exception_approved	☑️	Exception approved

You can override individual keys — omitted keys fall back to their defaults:

{
  "icons": {
    "exception_pending": "🔐",
    "exception_approved": "🔓"
  }
}