GitHub

Connect a GitHub repository to a workspace to link records to branches and pull requests, automate status changes, and sync records with GitHub Issues.

The native GitHub integration connects a GitHub repository to a Blue workspace. Once connected, you can link records to branches and pull requests, watch live status chips update as work progresses, drive automations from GitHub events, and keep records in sync with GitHub Issues.

Connecting GitHub happens at three levels: an organization owner or administrator installs the Blue GitHub App once, each workspace links a single repository, and each person optionally links their own GitHub account so their comments and actions are attributed to them.

Connect GitHub to your organization

Installing the Blue GitHub App is an organization-level action that requires the Owner or Administrator role.

  1. Open Settings > Integrations.
  2. On the GitHub card, select Connect GitHub.
  3. Choose the GitHub organization and the repositories to grant access to, then approve the installation on GitHub.
  4. GitHub returns you to Settings > Integrations, where the card shows the connected account.

A GitHub organization can be connected to only one Blue organization at a time. If the account is already connected elsewhere, the installation is rejected.

Each workspace links one repository. This is where branches, pull requests, and issues from that repository connect to the workspace’s records.

  1. Open the workspace’s Settings > GitHub page.
  2. Under Repository, select a repository from the connected account.
  3. Under Record ID field, select the field that identifies records in commit, branch, and pull request text.
  4. Select Link repository.

Workspace Settings > GitHub page with Repository and Record ID field selectors

The Record ID field must be an auto-numbered Unique ID field that uses a sequence and has a prefix (for example, BLUE-). If the workspace has no such field, create one in the workspace’s Fields settings first, then return to the GitHub page.

Unlinking a repository is non-destructive. Existing chips remain on records as read-only history, but they stop updating and new branches and pull requests no longer link. Link a repository again to resume.

Linking your personal GitHub account lets Blue attribute your synced comments and actions to you rather than to the Blue bot.

  1. Open Account > Security.
  2. In Connected Accounts, find the GitHub row and select Connect.
  3. Authorize Blue on GitHub.

Until you link your account, comments you sync to GitHub post through the Blue bot with your name attached. After linking, they post as your GitHub account. You can disconnect at any time from the same row.

Blue links a record to GitHub work when it finds the record’s ID (the prefix and number from the workspace’s Record ID field, such as BLUE-482) in GitHub. Where the ID appears determines how it is matched:

  • Branch name: a record ID anywhere in the name links the branch to the record.
  • Pull request title: a record ID anywhere in the title links the pull request.
  • Pull request description and commit message: linking requires a keyword before the ID. Reference keywords such as refs or related to link the record. Closing keywords such as close, fixes, or resolves link the record and mark it complete when the pull request merges. A bare ID with no keyword does not link.

Record IDs are matched case-insensitively and tolerate zero-padding. To stop a mention from linking, prefix it with skip or ignore (for example, skip BLUE-482). Comments on a pull request are not scanned for record IDs.

A record's GitHub field showing a linked pull request chip with state, checks, reviews, and diff stats

You can also link a pull request by hand from the record’s GitHub field: select Attach pull request and enter the pull request number or URL from the linked repository.

Status chips

Linked pull requests appear as chips in the record’s GitHub field and update live as their state changes:

  • State: Open, Draft, Merged, or Closed.
  • Checks: whether CI checks are passing, failing, or still running.
  • Reviews: approvals or requested changes.
  • Diff: lines added and removed.

Branches and commits contribute to linking and automations but are not shown as chips in the field. When a record moves to another workspace or its repository is unlinked, its chips remain as history and stop updating.

Automate with GitHub events

When a workspace has a linked repository, the automation builder shows a GitHub trigger group. See Triggers for the full list of GitHub triggers and Actions for the Create GitHub issue action.

The workspace’s Settings > GitHub page also offers one-click preset automations for common flows, such as moving a record to a list when a pull request opens or marking a record complete when its pull request merges. Presets create ordinary automations that you can edit afterward.

Sync records with GitHub Issues

Issue sync keeps records and GitHub Issues mirrored in both directions. Configure it per workspace on the Settings > GitHub page:

  • Off — linking and automations only: no issue sync. Records still link to branches and pull requests, and automations still run.
  • All records: every record in the workspace syncs to a GitHub Issue.
  • Filtered: only records that carry a chosen tag or select-field option sync.

Under New GitHub issues create records in, choose the list that receives records created from new GitHub Issues.

Synced records and issues mirror their title, description, complete state, labels and tags, and comments. Creating an issue in GitHub creates a record in the target list; closing or reopening the issue toggles the record’s complete state, and the reverse applies when you change the record in Blue. Deleting an issue in GitHub does not delete the Blue record.

Comments and the Internal toggle

On a synced record, comments sync to the paired GitHub Issue by default. To keep a comment in Blue only, turn on the Internal toggle in the comment box before posting. Internal comments never leave Blue.

Comment sync covers GitHub Issue comments only. Comments on pull request discussions are not synced.

Disconnect

Disconnecting removes the integration and its links:

  • Unlink a repository from a workspace’s Settings > GitHub page to stop that workspace from linking and syncing while keeping existing chips as history.
  • Disconnect GitHub from Settings > Integrations to uninstall the Blue app from your GitHub organization and remove every repository link. Linked records keep their data, but chips stop updating and issue sync ends.