GitHub

Link tasks to GitHub pull requests and issues, see their status on the task, merge from ProjectBrain, and keep issues and tasks in step.

BetaOwnerExecutiveTeam leadIndividual contributorLast updated 5 October 2026

This feature is in beta. If you do not see it, ask your admin to turn it on for your organization.

SetupAn admin turns on GitHub integration for your organizationWhoOwners and executives connect GitHub accounts. Leads choose repositories. Everyone else links and reads.Roles

Connect GitHub to see a task’s pull requests and issues on the task itself: open or merged, checks passing, review state, and what is stopping a merge. People with the right permission can merge a pull request without leaving ProjectBrain.

This is for teams whose work ends in code. Clients never see any of it.

Before you start

GitHub integration must be turned on for your organization. While it is off, the GitHub screens do not exist and tasks show no GitHub links.
Someone who can connect GitHub installs the ProjectBrain GitHub App into your GitHub account or organization. They need to be able to install apps there, too.
Each repository you want to use must be mapped to a project.

Connect a GitHub account

Go to Settings > Integrations > GitHub.
Choose Add a GitHub account.
On GitHub, pick the account or organization and the repositories ProjectBrain may see, then confirm.
You come back to ProjectBrain. The account appears under GitHub accounts with its repositories.

Each installation covers one GitHub account or organization. If your code lives in several, choose Add another GitHub account for each.

If you add or remove repositories on GitHub later, choose Refresh repositories to pick up the change.

Disconnect an account

Choose Disconnect next to the account. Linked tasks stay, but their GitHub links stop updating. A repository removed on GitHub is handled the same way: its links stay on the task.

Link your own GitHub account

To merge from ProjectBrain, each person links their own GitHub account once. In Settings > Integrations > GitHub, under Your GitHub account, choose Link my GitHub account.

The merge is then sent as you, so GitHub’s own history shows who merged it. Choose Unlink to remove the link. If GitHub stops accepting the link, ProjectBrain asks you to link it again.

Map repositories to projects

A project only sees the repositories mapped to it. You can map from two places, and both do the same thing:

Settings > Integrations > GitHub: open an account and pick a project for each repository. A repository with no project shows Not mapped yet.
The project’s Code repositories screen: open the project’s settings, choose Code, then Add a repository.

The project header shows a GitHub chip with the mapped repositories. A project with none shows that, so you know why links are not updating.

Mapping a repository also reconnects links that people pasted before it was mapped.

To stop using a repository on a project, choose Remove on the Code repositories screen. Existing task links keep working, but new ones cannot point to it. To stop all traffic with GitHub for a while instead, choose Pause syncing, then Resume syncing when you are ready.

Link a pull request or issue to a task

Open the task and find Linked items.
Choose Link a PR or issue.
Paste the GitHub URL. You can also type just the number, such as 414, if the project has one repository mapped.
Choose Link.

To remove a link, choose Unlink. The pull request or issue on GitHub is untouched. Only the link goes.

To open a GitHub issue from a task that does not have one yet, choose Create on GitHub, then Create the issue. It is created in the project’s repository.

AI assistants and agents connected to ProjectBrain can link pull requests too.

Read a link’s status

Each linked item shows its state, how many checks pass (for example “4/5 checks passing”), and when ProjectBrain last checked it. ProjectBrain keeps this current three ways: GitHub tells it about changes as they happen, a link is re-checked when you open a task and it has not been checked in the last couple of minutes, and every link is checked again once a night.

Two labels mean different things:

Label	What it means	What to do
Status not checked yet	ProjectBrain can read this link and has not fetched it yet.	Nothing. It fills in shortly, or when someone opens the task.
Not connected to GitHub	ProjectBrain cannot read this link and never will as things stand. The repository is not mapped to a project, was removed from the GitHub account, the account was disconnected, or GitHub integration is off.	Map the repository, or reconnect the account.

Checking with GitHub… means GitHub is still working out whether the pull request can merge. It is not a problem, and the task updates on its own.

Merge a pull request

When a pull request can merge, the task shows a Merge button.

Choose Merge.
Pick the Merge method your repository allows.
Confirm Merge pull request.

Before it merges, ProjectBrain asks GitHub again whether the merge is allowed, because a check or a branch rule can change after the page loaded. If GitHub refuses, you see GitHub’s own reason word for word, such as a required check that has not passed.

To merge you need code.merge and a linked personal GitHub account. Without the account, the task says Link your GitHub account to merge from here. Every merge attempt is recorded, whether it worked or not.

When the button is disabled, the task lists what is blocking the merge by name, such as failing checks or a required review.

Bring GitHub issues in as tasks

On the Code repositories screen, each mapped repository has a Bring issues in: rule:

By hand only: nothing is imported. You link issues one at a time. This is the default.
With a label: issues with the GitHub label you name become tasks.
All open issues: every open issue becomes a task.

Changing the rule imports nothing by itself. ProjectBrain counts what the rule would bring in and asks you to confirm with Import issues, so a busy repository does not fill your board by surprise.

What happens when an issue changes on GitHub

When someone closes, reopens, renames or relabels a linked issue on GitHub, the task gets a short timeline note saying so, posted by the GitHub bot.

The task’s status does not change by default. Someone closing an issue on GitHub does not know what your board’s columns mean.
A new title on GitHub replaces the task’s title once the issue exists.
Labels are noted, not applied to the task.
Assignees and the issue description are not read back from GitHub.

Optional status rules

On the Code repositories screen, Let GitHub move a task: sets two rules per repository, both off unless you choose a status:

When its issue is closed
When its pull request is merged

Each offers Do not change the status first, or Move it to a status you pick. When a rule moves a task, the timeline note names the rule rather than the person on GitHub.

Comments between GitHub and ProjectBrain

Comments cross in both directions, with two safety rules.

Only comments marked “Share externally” go to GitHub. When a task has a linked issue, the checkbox also names the issue the comment will be posted to. Internal comments never leave ProjectBrain.
Comments from GitHub arrive as internal comments. A GitHub comment can hold a stack trace or a frank opinion, so clients do not see it until someone shares it.

Comments are added, never changed or removed, on the other side. Editing or deleting a comment does not reach GitHub, and an edit on GitHub does not reach ProjectBrain. Ticking Share externally after posting does not send an older comment.

A comment you post goes to GitHub under your own GitHub account if you linked one. Otherwise it is posted by the ProjectBrain app with your name at the start. A comment from GitHub is shown as the matching ProjectBrain person when ProjectBrain knows their GitHub account, and as the GitHub bot otherwise. It never guesses from a display name.

Who can see what

People see GitHub links only on tasks they can already see.
Clients and external guests see no GitHub links, statuses or buttons.
Settings screens you do not have permission for are not shown to you.

Limits

A repository must be mapped to a project before its links update.
Changes made on GitHub while syncing is paused are not caught up later as notes.
GitHub integration is in beta. Screens and wording may change.