Docs

Connecting Bitbucket

Clone Bitbucket repos with flydocs init: the two credentials, a scoped Atlassian API token, the right git username, SSH, and how pull requests are opened.

flydocs init clones your workspace's repos using your own git credentials — the same ones you would use for git clone in a terminal. FlyDocs never holds them and never supplies them for you.

On Bitbucket that has a sharp edge. Atlassian retired app passwords on 2026-06-09, so a credential that worked last year now fails, and the replacement — a scoped Atlassian API token — rejects the thing most people try first: their account email as the git username. This guide is the working recipe.

Two different credentials

These get confused constantly, so start here.

Credential Set up by Used for
The org's Bitbucket connection A workspace admin, once, in the FlyDocs portal REST API features — listing repos, scanning PRs
Your git credential, on your laptop You, on each machine git clone, git fetch, git push, flydocs init

The org connection never authenticates git on a developer machine. It lives on the server and speaks to Bitbucket's REST API. Every developer still needs their own git credential locally, even when the portal shows the Bitbucket connection as healthy.

HTTPS: an Atlassian API token

Four steps. The second one is the one that trips people.

1. Create a scoped API token

Go to id.atlassian.com/manage-profile/security/api-tokens and choose Create API token with scopes — not the plain "Create API token" button next to it, which produces a token git cannot use.

  • App: Bitbucket
  • Scopes: read:repository:bitbucket and write:repository:bitbucket

Copy the token when it is shown. Atlassian will not show it again.

2. Use the right username

Git needs a username as well as the token, and the Atlassian account email does not work here. It authenticates against Bitbucket's REST API, which is why it looks correct in half the documentation you will find, and it fails against git.

Use either of these:

  • x-bitbucket-api-token-auth — a literal string, the same for everyone
  • your account's Bitbucket username (Personal settings → Account settings)

The literal is the safer habit: it is the same in every runbook, every teammate's machine, and every copy-pasted command.

3. Store the token in your credential helper

Run one command against any repo in the workspace and paste the token at the password prompt: 

git ls-remote https://x-bitbucket-api-token-auth@bitbucket.org/<workspace>/<repo>.git HEAD

A list of refs means it worked, and the helper has kept the token for every later clone.

macOS git ships with credential.helper=osxkeychain already set, so there is nothing to configure. If the prompt comes back a second time, no helper is storing anything: 

git config --global credential.helper osxkeychain   # macOS
git config --global credential.helper manager       # Windows Credential Manager

On Linux, use libsecret or whichever helper your distribution packages.

4. Re-run flydocs init

flydocs init

Repos that were already cloned are picked up as-is, so a partial run costs you nothing — init clones what is missing and initializes the rest.

Tokens are per-app, and they expire

Two properties of scoped tokens worth knowing before you hit them:

  • A Jira token cannot clone a repo. Scopes are bound to one app. If your team already issues Atlassian tokens for Jira, that token is not reusable here — same Atlassian account, separate token, Bitbucket scopes.
  • Maximum expiry is 365 days. There is no non-expiring option. Every token you create needs a rotation date, so put it on the calendar when you create it rather than discovering it a year later in a failing clone.

SSH instead

If your workspace prefers SSH, the credential lives in your SSH agent and none of the above applies.

  1. Add your public key at bitbucket.org → Personal settings → SSH keys.
  2. Verify it: ssh -T git@bitbucket.org.
  3. Ask a workspace admin to switch the clone protocol to SSH on the Version Control page in the FlyDocs portal.
  4. Run flydocs init (or pull config again). It will now emit git@bitbucket.org: clone URLs.

Step 3 is workspace-wide, not per-developer: the protocol is a property of the workspace's config, so everyone gets SSH URLs once it is switched.

When flydocs init cannot get in

init checks git access before it clones anything. On Bitbucket, a failed check does not surface a git prompt: init asks for the API token directly, stores it in your OS credential helper under the right username, and continues — so in practice the whole HTTPS recipe above collapses to "create the token, paste it when init asks". The manual steps remain the path for seeding a machine ahead of time or outside init.

For other hosts, a failed check prints Git could not access … followed by host-tailored guidance — so a fresh developer gets the fix in the terminal rather than having to find this page.

Failure signatures and what each one means are in Troubleshooting → Bitbucket authentication.

Pull requests

issues.py pr (and flydocs run issue.pr) opens the review PR at the Implement → Review hand-off. On GitHub and GitLab it shells out to your own gh or glab, so the PR is yours. Bitbucket has no maintained CLI, so on a Bitbucket workspace the script asks the FlyDocs relay to open the PR with the organization's Bitbucket connection — the one an admin set up in Settings → Connections, which already carries the write:pullrequest:bitbucket scope.

What that means in practice:

  • Nothing to set up per developer, and no token ever reaches the workflow scripts. Your git credential is only used for clone, fetch and push.
  • The PR is authored by the connection owner, not by you. The PR body carries the issue reference and your attribution, and the review comment on the issue links the PR as usual.
  • It needs the cloud tier (the relay does the work). On the local tier the command tells you so and stops.
  • If the relay answers SCM_RECONNECT_REQUIRED, the connection still uses a retired app password — an admin needs to reconnect with an API token.

Next