Use GitHub Issues

GitHub Issues can be your work tracker instead of Jira, or sit beside Jira as the pieces of its cards. It's read through the same GitHub App, and a few habits make the numbers good.

Turn it on

1. Connect GitHub first. See Connect GitHub.
2. An owner of your GitHub organization accepts the app's updated permissions, which add Issues: read (and Projects: read, for GitHub Projects): Settings → GitHub Apps → Truly Shipped → Review request.
3. On Connections, press Turn on GitHub Issues. Under Change details you can pick the repositories to read (all of them by default) and the GitHub Projects to use.

History syncs right away, and changes arrive as they happen. Issues opened by bots, like deploy approvals from GitHub Actions, are never counted.

What counts as what

• An epic is a tracking issue: one with sub-issues, one whose issue type you've named as an epic type, or one whose description is a task list of issues (- [ ] #12). Epics aren't work themselves; the issues in them are.
• A work item is any other issue. Closed means done. Closed as not planned or duplicate means it was dropped, so it's never counted as delivered.
• In progress means someone's assigned, or a pull request to close it is open. With a GitHub Project, its Status says so instead.
• Who did it is the assignee, or, when nobody was assigned, whoever wrote the pull request that closed it.

Habits that make the numbers good

• Make epics with sub-issues. GitHub's own parent link is the clearest. A task list in the tracking issue works too.
• Link pull requests to issues. Write Closes #123 in the pull request, or make the branch from the issue (GitHub names it 123-short-title). Pull requests with no issue show up as unlinked work.
• Close as "not planned" rather than deleting. Deleted issues vanish from the history.
• Set issue types (Bug, Task, Feature) so bugs and features can be told apart.
• Releases aren't work. A pull request that merges one long-lived branch into another, like dev into main, is left out of the pull request numbers automatically.

GitHub Projects (optional)

Plain issues already give throughput, lead time, priority alignment and unlinked work. A Project adds what's in progress, sprints and points. Add its number under Change details (it's in the Project's address: …/orgs/acme/projects/3).

• Status: options like In progress and In review mean in progress, and Done means done. If yours are named differently, list them under Change details.
• Iteration: each iteration becomes a sprint. Set each sprint's team under Admin → Sprints so it shows on that team's dashboard.
• Estimate: a number field, or sizes (XS, S, M, L, XL), become points.

We read each issue's Status history back to when it joined the Project, so a team's flow numbers start with real history rather than from the day you connect. Iteration and Estimate changes have no history at GitHub, so those start from the day you connect.

Beside Jira

Connect both and Jira stays your work tracker. A GitHub issue that names a Jira card (CC-123), or sits in a tracking issue that does, or is closed by a pull request that does, is a piece of that card. It's never counted twice, and its pull requests count on the card. GitHub issues no Jira card names show up as work outside Jira, a separate count that's never added to Jira's.

Initiatives

If your top-level tracking issues are really company priorities, open the epic under Admin → Epics and choose Make this an initiative. The trackers its task list names join the same initiative.