how connect bitbucket?

[dux-roman]

I’m having trouble configuring Orca with a Bitbucket repository.

Can someone help me?

I already have the token configured, but I can’t seem to get it working.

Am I missing any configuration step?

I already have the repository checked out locally, but maybe I need to set it up from scratch?

Is there any guide or documentation I can follow?

[nwparker]

Thanks for raising this — and you're right that the current Bitbucket setup is clunkier than it should be.

What works today: Orca supports Bitbucket Cloud for viewing pull requests and build/CI statuses. Authentication is currently via environment variables only. Set either:

• ORCA_BITBUCKET_ACCESS_TOKEN (sent as a Bearer token), or
• both ORCA_BITBUCKET_EMAIL and ORCA_BITBUCKET_API_TOKEN (an Atlassian API token, used for Basic auth)

Common gotchas that usually explain "I set the token but it won't connect":

1. On the API-token route you must set both the email and the token — the token alone won't authenticate.
2. Restart Orca after setting the env vars so it picks them up.
3. Your repo's origin remote must point at bitbucket.org (self-hosted Bitbucket Server/Data Center isn't supported yet).
4. Generate an API token here: https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/

Then check Settings → integrations; the Bitbucket card should show "Connected" with your account.

What's coming: we agree the env-var + restart flow isn't a good experience. Unlike GitHub/GitLab — where we delegate auth to the gh/glab CLIs — Bitbucket has no equivalent CLI for us to lean on, so we're going to add an in-app credentials section in Settings where you can enter and securely store your Bitbucket credentials directly (no env vars, no restart). Existing env-var support will keep working for headless/SSH setups.

I'll follow up on this thread when that ships. Thanks for your patience!

[VectorPeak]

You shouldn’t need to set the repo up from scratch. Orca uses the local git checkout, so the important parts are: the repo’s origin points at Bitbucket, and the Orca process can see the Bitbucket auth env vars.

git remote -v

Make sure the remote is a Bitbucket Cloud URL, for example:

origin https://bitbucket.org/<workspace>/<repo>.git
# or
origin git@bitbucket.org:<workspace>/<repo>.git

A common gotcha is setting the token in one shell/session but starting Orca from another place where that env var isn’t present. After exporting the Bitbucket env vars, restart Orca from the same environment. Also check that the token/app password has permission to read the repository and pull requests.

If it still doesn’t connect, the useful bits to share are: the git remote -v output with private parts redacted, whether this is Bitbucket Cloud or Bitbucket Server/Data Center, and the exact error Orca shows.