Skip to content
Unblockd
Start free
Menu
Help topics · GitHub

Connect GitHub to Unblockd

Install the Unblockd app on your repositories and link one to a project. Merged pull requests and releases that name a task become its proof.

Updated · About the GitHub integration

On this page

What Unblockd reads

Unblockd reads the GitHub repositories you install it on. When a pull request merges, or a release is published, and it names a task by its key (like SUP-12), Unblockd attaches it to that task as proof.

It doesn’t bring in issues as tasks, and it never changes anything in GitHub: no comments, labels, or commits.

Unblockd stores only the app installation, never a GitHub token; it makes short-lived tokens as it reads. How Unblockd handles your data.

Before you start

  • In Unblockd, a workspace admin connects GitHub, once for the whole workspace. Members see it in Settings but can’t connect or disconnect it. Anyone on the team can then link it to a project.
  • In GitHub: Someone who can install GitHub Apps on the account or organization that owns your repositories.

Connect GitHub

  1. Open Connected toolsSign in to Unblockd and open Settings, then Connected tools.
  2. Press Connect beside GitHubFind GitHub under Most used, or press Show all 33 tools, or type its name in the search box. Then press Connect on its row.
  3. Install the app on GitHubGitHub shows the Unblockd app, the access it asks for, and lets you choose all repositories or only the ones you select.
  4. Back in UnblockdYou come back to Connected tools, which says “GitHub is connected. Next, link it to a project from the project’s Sources tab.” Its row shows the GitHub account and Connected.

Link it to a project

  1. Open the project’s Sources tabOpen the project from Projects, then its Sources tab.
  2. Press Link a sourceIt’s under the list of linked sources. If more than one tool is connected, choose GitHub under Tool.
  3. Pick the GitHub repositoryUnder GitHub repository, pick the one this Unblockd project runs on. Only repositories the connection can see are listed, and ones already linked here are left out.
  4. Press LinkThe GitHub repository appears in the Sources list.

Starting a new project? On New project, open “Bring work in from a tool”, choose GitHub and the repository. It’s linked as the project is created.

How merged work becomes proof

  1. Find the task’s keyEach task has a key built from the project’s task prefix and its number, like SUP-12. You see it beside every task.
  2. Name it in the pull requestPut the key in the pull request’s title, description, or branch name. Several keys attach the pull request to each of those tasks.
  3. Merge itWhen the pull request merges, Unblockd attaches it to each task it names as proof. A published release that names a task is attached the same way. Each is attached once per task.

Only repositories linked to a project count, and only for that project’s keys. GitHub tells Unblockd as soon as a pull request merges or a release is published.

Proof doesn’t change a task’s status on its own. Someone on your team still moves the task to Done, and with the pull request attached, it can be.

Disconnect and revoke access

  1. Press DisconnectIn Settings, then Connected tools, press Disconnect on GitHub’s row.
  2. ConfirmIf it’s linked to projects, Unblockd first says how many repositories it will unlink. Press Disconnect GitHub to confirm, or Keep.
  • Deleted: the connection, its stored access, and every GitHub repository linked through it, across all your Unblockd projects.
  • Kept: pull requests and releases already attached as proof stay attached.
  • Disconnecting also uninstalls the Unblockd app from your GitHub account, unless another Unblockd workspace uses the same installation.

To stop one project following GitHub without disconnecting it for everyone, open the linked GitHub repository’s ⋯ menu on the Sources tab and choose Unlink.

Troubleshooting

Needs reconnecting
What to do: GitHub turned down Unblockd’s access, for example because it was revoked or the person who connected it left. The row says “Reconnect to keep it in sync.” An admin presses Reconnect and approves access again; linked repositories and their tasks carry on.
Retrying
What to do: The row says “Couldn’t reach it on the last try. It will try again.” GitHub didn’t answer the last time Unblockd tried. Nothing is lost; the next sync picks up where it stopped.
A repository is missing
What to do: Only repositories the app is installed on, and that you can see, are listed. If you gave the app more repositories since connecting, reconnect GitHub in Settings.
Only an admin can connect
What to do: “Only a workspace admin can connect or disconnect tools.” Ask an admin, or have one change your role in Settings, then Members.
The connection link expired
What to do: “That connection link expired or was started by someone else. Try again from here.” Start again from Connected tools and finish within 10 minutes.
A different account
What to do: “This workspace is linked to a different account for that tool. Disconnect it first.” Each workspace connects one GitHub account. Disconnect the old one first.
Coming soon
What to do: A tool that shows Coming soon instead of Connect can’t be connected yet.

Still stuck? Press Report a problem on GitHub’s row in Connected tools, or choose Report a problem with GitHub from a linked repository’s ⋯ menu. One tap sends the tool and what the row shows about the connection (never a key or token) to the Unblockd team, and someone replies by email. You can send 5 reports every hour, or write to hello@unblockd.ai any time.

Connect GitHub now

Open Connected tools in Unblockd and press Connect beside GitHub. You’ll need to be a workspace admin.

Open Connected tools