GitHub

GitHub is one of SprintBee's three work item providers. It connects to organization-owned Projects on GitHub.com and GitHub Enterprise Cloud — GitHub Enterprise Server is not supported.

A GitHub connection lets a Planning Room estimate real issues, pull requests and Project drafts instead of typed titles. Moderators pull items into the queue, accepted estimates go back onto Project fields you choose, and splitting an oversized item creates new work in GitHub. Work item integrations are a paid feature, included on Pro.

Where the connection lives#

There are two levels, and confusing them is the usual source of trouble.

The connection belongs to your SprintBee organization. An owner starts from Dashboard → Integrations → Add connection → GitHub and chooses the SprintBee organization that will own it. A GitHub organization administrator then installs the SprintBee GitHub App, and the SprintBee owner reviews the GitHub organization that came back and approves the pairing. One App installation belongs to exactly one SprintBee organization.

The App asks for organization Projects read and write, Issue Types read, and repository Metadata read plus Issues and Pull requests write. An administrator may grant all repositories or only selected ones. Project drafts and items from granted repositories are available; items from repositories outside the grant are omitted without revealing their details.

The source belongs to a Workspace, and is chosen under Integrations & notifications. One connection can feed many Workspaces; each Workspace uses one source at a time, shared between its Planning and Retro Rooms.

Installation access tokens are short-lived and minted only when SprintBee calls GitHub. They are never stored.

Choosing a Project and mapping status#

Pick exactly one GitHub Project. A Project can contain work from several repositories, but the Project — not a repository — is the source boundary.

Before the source can be activated, choose the Project's single-select status field and map every one of its options to one of SprintBee's five categories: To do, In progress, Review, Blocked, and Done. SprintBee suggests mappings but never silently confirms them, because a status it guessed wrong changes what a room treats as finished. Options added in GitHub later stay visible with neutral semantics until someone confirms where they belong.

Two more mappings are optional. A priority field (any single-select) shows priority on imported items. An iteration field makes the Project's iterations available as a Retro Room's period, the same way Jira sprints and Linear cycles are.

What can be imported#

Project issues, pull requests, and draft issues are all importable. Labels, assignees, author, the native Issue Type, and mapped Project fields come across when GitHub has them.

Drafts have no issue number, so SprintBee does not fabricate a key for them. Every item is identified by its stable Project Item ID instead, which is the one identifier issues, pull requests and drafts all have.

Issue and draft descriptions can be edited from SprintBee. Pull request descriptions are read-only. Comments posted from a room are written by the SprintBee App with the participant's display name in a footer — a draft has to be converted to an issue in GitHub before it can take a comment.

Bringing items into a room#

Moderators work from the Add work items panel's GitHub tab. Paste an issue or pull request reference, or its URL, and it imports directly; type anything else and it filters the Project's items by text.

GitHub's API cannot run a Project view's saved filter, so SprintBee stores its own presets: one optional default query plus up to four named ones, configured on the source. They are plain text filters that narrow discovery — they are not a query language, and they never widen what the source can reach.

Only items already on the configured Project can be imported. Pasting a reference to an issue that is not on it, or that sits in a repository outside the App's grant, asks you to add it to the Project or widen repository access rather than importing something the rest of the team cannot see.

Writing estimates back#

GitHub has no native estimate field shared by issues, pull requests and drafts, so write-back targets Project fields. Team, Dev, QA and Sum estimates are mapped independently onto number, text or single-select fields on the Project. The write fires once, when a moderator accepts an estimate for a linked round.

The accepted value is preserved as-is. A number field takes only a numeric value, a single-select field only a value matching one of its options, and non-estimate cards are omitted. Anything incompatible is skipped with a recorded reason rather than rounded or substituted.

Splitting work#

A split follows the kind of the parent. Splitting an issue creates real sub-issues in the same repository and adds them to the configured Project. Splitting a pull request or draft creates Project draft issues, and the parent relationship is recorded in SprintBee, because GitHub has no equivalent relationship for those parents.

Staying current, and when something goes wrong#

Imported items that are not yet finished refresh from GitHub webhooks, with scheduled reconciliation repairing anything a missed delivery dropped. New Project items are never imported automatically — the queue is a moderator's decision. Completed SprintBee history never changes.

An item that is archived, deleted, removed from the Project, or made inaccessible by a change in repository access stays in the queue marked unavailable rather than vanishing. Restoring access makes it usable again.

Suspending the App marks the connection as needing reconnection; uninstalling it disables the connection without deleting the history SprintBee already has.