GitHub & Bitbucket
Link a code repository to a project so that branches, commits and pull requests show up against the work items they belong to — and push a work item into the repo as an issue without leaving Coco Kanban.
Plan: Business and above
What you can do
- Connect one GitHub account and one Bitbucket account per workspace.
- Link a repository to a project (Project settings → Integrations).
- Push a work item to the linked repo — it becomes a real GitHub or Bitbucket issue, and the link back is stored on the work item.
- Have commits, branches and pull requests automatically associated with a work item when they mention its ID (for example
ENG-42).
Getting started
Step 1 — Connect GitHub
- Go to Workspace settings → Integrations.
- On the GitHub card, click Connect.
- Paste a Personal Access Token (it starts with
ghp_). Generate one at GitHub → Settings → Developer settings → Personal access tokens. It needs repository access — enough to read repos and create issues. - Click Connect.
Coco Kanban validates the token against GitHub immediately. If it's wrong you get "Invalid GitHub token" and nothing is saved. On success, the card shows Connected plus the GitHub login the token belongs to.
Step 1 (alternative) — Connect Bitbucket
Bitbucket needs three values, and each one trips people up. Get them exactly right:
| Field | What to enter | Where to find it |
|---|---|---|
| Bitbucket Username | Your Bitbucket handle — not your email address. | Go to bitbucket.org → avatar → View profile. The username is the last part of the profile URL: bitbucket.org/johndoe → enter johndoe. |
| App Password | An App Password — not your Bitbucket/Atlassian login password. | bitbucket.org → Settings → App passwords → Create app password. Tick Repositories: Read and Issues: Write. Copy it immediately; Bitbucket shows it once. |
| Workspace Slug | The workspace slug, lowercase, no spaces. | It's the segment after bitbucket.org/ when you're inside your workspace: bitbucket.org/mycompany/ → enter mycompany. |
Then click Connect.
Coco Kanban checks the credentials against Bitbucket before saving, and the error messages tell you which of the three is wrong:
- "Bitbucket rejected the credentials (HTTP 401)" — the username/password pairing is wrong. Almost always: you used your email instead of your username, or your login password instead of an App Password.
- "Workspace 'x' not found" — the workspace slug is wrong. Copy it from the URL.
- "The token authenticates but cannot access workspace 'x'" — the App Password is missing Repositories: Read, or the account isn't a member of that workspace.
- "contains a non-standard character" — you pasted from a document that auto-formatted a dash or quote. Re-copy the raw value from Bitbucket.
📷 Screenshot: The "Connect Bitbucket" dialog showing the three fields — Bitbucket Username, App Password, and Workspace Slug — with their hint text.
Step 2 — Link a repo to a project
- Open the project, then Project settings → Integrations.
- Pick the integration (GitHub or Bitbucket) from the buttons at the top. The connected account name is shown next to it.
- Choose a repository from the Link a Repository to this Project dropdown. Private repos are marked
(private). - Click Link.
The linked repo is shown in a green panel with an Unlink button if you need to change it.
If the dropdown is empty, your token can't see any repos — check the token's repository scope (and, for Bitbucket, that the workspace slug matches the workspace the repos live in).
📷 Screenshot: Project settings → Integrations with a repository linked, showing the green "Linked repository" panel.
Pushing a work item to the repo
Once a repo is linked, you can push work items into it.
From the work item: open the work item and click Push to repo in its action bar. A small panel lists the linked repos — click one and the work item is created in that repo. Anything already pushed is listed under Already pushed, with a link straight to the GitHub/Bitbucket issue.
From project settings: the Integrations page also lists the project's work items with a Push to repo button on each row, so you can push several in a sitting. Once a work item has been pushed the button becomes Push again.
The pushed issue gets the work item's title and description. The link back (provider, issue number and URL) is stored on the work item, so you always know where it landed.
📷 Screenshot: A work item detail page with the "Push to repo" dropdown open, listing the linked repository.
For Bitbucket, pushing requires the repo's issue tracker to be enabled and the App Password to have Issues: Write. If either is missing you'll see a clear error rather than a silent failure.
What syncs from the repo
Coco Kanban listens for repository events and attaches development activity to the right work item:
- Commits — every commit whose message contains a work-item reference (
ENG-42,PROJ-7) is recorded against that work item, with author, message, timestamp and a link to the commit. - Branches — a branch that carries a work-item reference is recorded and linked. Commits landing on it are grouped under it.
- Pull requests — a PR whose title or source branch name contains a work-item reference is linked, with its state (open / merged / closed), author, reviewers, files changed, and source/target branches. State changes update the link when the PR is merged or declined.
The matching rule is simple: put the work-item ID in the commit message, branch name or PR title. ENG-42 is the project identifier plus the work item's number, exactly as it appears in the app.
Repository webhooks are signed and verified — an unsigned or badly signed delivery is rejected outright.
Tips
- Name branches like
feature/ENG-42-add-oauth. That single convention gets your branch, every commit on it, and the eventual PR attached to the work item automatically. - Use a shared service account for the token. Personal tokens die when the person leaves.
- The connected account name appears on the card. If it isn't the account you expected, disconnect and reconnect with the right token.
Limits & good to know
- One GitHub and one Bitbucket connection per workspace. A second connect attempt is rejected with "Workspace is already connected".
- Repository event delivery is set up through the integration service, not the UI. Linking a repo enables pushing work items straight away; wiring the repo's webhook so commits, branches and PRs flow back is done by whoever administers the deployment. Ask your admin if development activity isn't appearing.
- Push is one-way. Closing the GitHub/Bitbucket issue does not close the work item, and edits made on the provider's side aren't pulled back.
- Only public GitHub and Bitbucket Cloud. GitHub Enterprise Server, self-hosted Bitbucket (Data Center), GitLab and Azure DevOps are not supported.
- Disconnecting keeps the data. Linked repos and pushed-issue links remain visible; they just stop updating.