# Bitbucket

Connect Bitbucket Cloud to link your repositories to iKanban projects, so agents work in them.

Everything happens on **Agent settings → Connections**, in the **Git providers** card.

## Connect and link (2 minutes)

1. Click **Bitbucket → Connect**, then **approve access for iKanban** on Bitbucket. iKanban asks only to read your account and your repositories; it never writes to Bitbucket. The row then shows **Connected** and your Bitbucket name.
2. Click **Bitbucket → Configure**. Every project of your teams is listed. Click **Link** next to a project and pick a repository: the list covers every Bitbucket workspace you belong to.
3. The project row now shows `workspace/repository` with **Unlink**.

Each person connects their own Bitbucket account. Connecting doesn't give anyone else access to your repositories.

## Let this laptop reach the repository

Agents run on your laptop and clone the linked repository with **this laptop's own git sign-in**. Check it once:

```text
git ls-remote https://bitbucket.org/<workspace>/<repository>.git HEAD
```

A commit hash means you're ready. If git asks for a password or fails, pick one:

- **API token (HTTPS):** Bitbucket profile → **Account settings → Security → Create and manage API tokens → Create API token with scopes** → app **Bitbucket** → scopes **read:repository:bitbucket** and **write:repository:bitbucket** → **Create token** (shown once). Run the command again: the username is `x-bitbucket-api-token-auth` and the password is the token. Your system keychain remembers it.
- **SSH key already on Bitbucket:** `git config --global url."git@bitbucket.org:".insteadOf "https://bitbucket.org/"` makes git use SSH for these repositories.

Prefer an agent to check it all? Use the [Bitbucket setup prompt](/docs/settings/bitbucket-prompt), or `/ikanban-bitbucket-setup` in Claude Code once This laptop is set up.

## Good to know

- **Pull requests:** agents can push a branch (they ask you first). iKanban doesn't open Bitbucket pull requests for you yet; open one from the branch on bitbucket.org.
- **Needs reconnecting:** Bitbucket refused iKanban's access, for example after you revoked it. Click the row and approve again.
- **Empty repository list:** that Bitbucket account has no repositories you can read, or you approved with a different account.
- **"Not set up on this server yet":** your iKanban server can't connect Bitbucket; ask your iKanban administrator.