Skip to content

Getting Started

1. Install the GitHub App

Install Signed Off on your organization: github.com/apps/signed-off

When prompted, grant access to All repositories. This is required so the app can read templates from your org's .github and .github-private repos alongside the repos where issues are opened.

2. Create your first template

Templates are Markdown files stored in your repositories. To create a shared default that applies across all repos, add a file to your org's .github repository. For example, for a Bug issue type:

.github/CHECKLIST/bug.md

## Pre-triage

- [ ] Steps to reproduce confirmed
- [ ] Affected version(s) noted

## Review

- [ ] [Security implications checked](https://wiki.example.com/security-review)
- [ ] Linked to a milestone

Tip

Wrap a label in [text](url) to attach a doc link. It appears as a small icon next to the item and opens in a new tab — it's never required to save state.

The app searches for templates in this order when an issue is opened, stopping at the first file found:

Priority Location Use case
1 {issue-repo}/.github/CHECKLIST/{type}.md Repo-specific override
2 {org}/.github-private/.github/CHECKLIST/{type}.md Org-wide private default
3 {org}/.github/.github/CHECKLIST/{type}.md Org-wide public default

See the Templates guide for the full format, including enforcement levels and per-template exception approver teams.

3. Open an issue

Open a new issue in any repo where the app is installed. Set the Issue type to Bug (GitHub's native issue type field — not a label).

Within a few seconds, the bot posts a managed comment with the rendered checklist.

4. Update checklist items

Click the Open checklist link in the bot comment. GitHub OAuth verifies you're a repo collaborator, then shows the full checklist editor.

Mark items as:

  • Done — work is complete
  • N/A — not applicable to this issue
  • Need Exception — requires approval from a second party (see Exceptions)

5. Embed the status badge

Copy the badge URL from the bot comment and paste it into any Markdown — a PR description, wiki page, or dashboard:

![Checklist](https://app.signed-off.dev/api/badge/owner/repo/123)

The badge updates live as checklist state changes.

6. (Optional) Configure org-wide settings

To customise behaviour — approver team, cache TTL, icon set, or which repos can override templates — create .github/checklist-app.json in your org's .github repository. All fields are optional.

{
  "exceptionApproversTeam": "security-leads",
  "noTemplateBehavior": "comment",
  "repoOverrides": {
    "default": "allow",
    "exceptions": ["production-*"]
  }
}

See the Configuration reference for all available fields.