Skip to content

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,
  "noTemplateBehavior": "default",
  "publicBadges": false,
  "icons": {
    "pending": "⬜",
    "done": "✅",
    "na": "✖️",
    "exception_pending": "⚠️",
    "exception_approved": "☑️"
  },
  "repoOverrides": {
    "default": "allow",
    "exceptions": [
      "production-*",
      "infra-*"
    ]
  }
}

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": "🔓"
  }
}

publicBadges
Type boolean
Default false

Controls whether the SVG badge endpoint is accessible for private repositories.

Value Behaviour
false Badge returns a neutral "private" placeholder for private repos — no checklist data is exposed
true Badge is served publicly, even for private repos

Public repositories always serve the badge regardless of this setting.

{ "publicBadges": true }

repoOverrides
Type object
Default { "default": "allow", "exceptions": [] }

Controls whether individual repositories are permitted to override org-level templates by placing their own template files in .github/CHECKLIST/. This is useful for enforcing org-wide templates in critical repositories (e.g. production, infrastructure) while still allowing teams to customise templates in their own repos.

Sub-field Type Description
default "allow" | "disallow" The baseline policy applied to any repo not matched by an exception
exceptions string array Glob patterns matched against the repo name (not owner/repo). Repos matching any pattern flip to the opposite of default.

Patterns support * as a wildcard (e.g. production-* matches production-api, production-web).

Example — allow overrides everywhere except production and infra repos:

{
  "repoOverrides": {
    "default": "allow",
    "exceptions": [
      "production-*",
      "infra-*"
    ]
  }
}

Example — lock down overrides org-wide, permit only sandbox repos:

{
  "repoOverrides": {
    "default": "disallow",
    "exceptions": [
      "sandbox-*"
    ]
  }
}

When a repo is disallowed, its .github/CHECKLIST/ files are ignored entirely — template resolution falls through directly to the org-level templates (.github-private then .github).