Understanding Repository Context

Most commands need a workspace and a repository. If you don’t pass -w/-r, the CLI works them out from your git remote, then BB_WORKSPACE, then your config file, in that order.

Context resolution order

1. -w/--workspace and -r/--repo on the command line
2. A Bitbucket git remote of the current repository (see Which remote is used)
3. The BB_WORKSPACE environment variable
4. defaultWorkspace in the config file

Sources 3 and 4 only supply a workspace. A repository still has to come from -r or the git remote.

Typical local layout

Run bb from the clone or one of its subdirectories. It reads that repository’s git remotes to resolve the workspace and repository.

Examples

Scenario 1: inside a git repository

# /projects/myrepo has a Bitbucket remote
cd /projects/myrepo
bb pr list  # workspace and repository come from the remote

The CLI reads your .git/config and extracts the workspace and repository from the remote URL.

Scenario 2: using command-line flags

bb pr list -w myworkspace -r myrepo

Flags always win. With both flags supplied, no git repository is required.

Scenario 3: using a default workspace

# Environment variable, useful in CI
export BB_WORKSPACE=myworkspace

# Or persist it in the config file
bb config set defaultWorkspace myworkspace

bb repo list  # workspace-only command, no repository needed

BB_WORKSPACE wins over defaultWorkspace, so a pipeline can override a developer’s persisted default without rewriting the config file.

Scenario 4: mixed sources

# Inside a clone of gitworkspace/gitrepo
cd /projects/myrepo

# Override just the workspace
bb pr list -w anotherworkspace  # anotherworkspace/gitrepo

# Override just the repository
bb pr list -r anotherrepo  # gitworkspace/anotherrepo

Workspace-only vs repository-scoped commands

The two classes fail differently when context is missing.

Class	Commands	Error when unresolved
Workspace-only	bb repo list, bb repo create, bb repo clone, bb project *, bb snippet *, bb workspace view, bb search code, bb webhook * --scope workspace	6002 CONTEXT_WORKSPACE_NOT_FOUND
Repository-scoped	bb pr *, bb pipeline *, bb commit *, bb status *, bb browse, bb repo view, bb repo delete, bb repo default-reviewers *, bb webhook *, bb branch-restriction *, bb deployment *	6001 CONTEXT_REPO_NOT_FOUND

bb ssh-key * and bb gpg-key * act on your own account and ignore -w/-r.

bb api falls in either class depending on the endpoint: it resolves a workspace only if the endpoint contains {workspace}, and a repository only if it contains {repo}.

# Placeholders are filled from the same resolution chain
bb api /repositories/{workspace}/{repo}/pullrequests

If a placeholder can’t be resolved you get Endpoint uses {repo} but no repository could be resolved. Pass --repo or run inside a Bitbucket repo.

Repository argument formats

Commands that accept a repository argument support two formats.

Full format: workspace/repo

bb repo view myworkspace/myrepo
bb repo delete myworkspace/myrepo --yes

Short format: repo only

bb repo view myrepo

The workspace is resolved in the usual order:

1. -w/--workspace, if you passed it
2. Otherwise the workspace from the current git remote
3. Otherwise BB_WORKSPACE
4. Otherwise defaultWorkspace from the config file
5. Otherwise error

The git remote wins over your config. Running bb repo view myrepo inside a clone of otherws/otherrepo resolves to otherws/myrepo, even if defaultWorkspace is set to something else.

Supported remote URL formats

SSH format

[email protected]:workspace/repo.git
[email protected]:workspace/repo
ssh://[email protected]/workspace/repo.git
ssh://[email protected]:443/workspace/repo.git

HTTPS format

https://bitbucket.org/workspace/repo.git
https://bitbucket.org/workspace/repo
https://bitbucket.org/workspace/repo/
https://[email protected]/workspace/repo.git

Repository names may contain dots (my.repo, docs.example.com). Only a trailing .git is stripped.

SSH host aliases

A remote like git@bitbucket-work:workspace/repo.git works when bitbucket-work is a Host entry in your SSH config whose HostName is bitbucket.org. The CLI asks ssh -G for the real hostname, the same lookup git does when it connects.

URL rewrites

url.<base>.insteadOf rules in your git config are applied before the URL is parsed, so a remote such as bb:workspace/repo works if it rewrites to a Bitbucket URL.

Which remote is used

1. origin, if it points to Bitbucket
2. Otherwise the Bitbucket remote, if all Bitbucket remotes point to the same repository
3. Otherwise upstream, if it is one of them
4. Otherwise the CLI stops with an error and asks for -w/-r

A fork clone with origin (your fork) and upstream (the parent) both on Bitbucket resolves to your fork.

Error messages

Repository could not be resolved

Four distinct reasons, all error code 6001 CONTEXT_REPO_NOT_FOUND. Under --json each sets a different context.reason.

The working directory is not a git repository, reason: not_a_git_repo:

✗ Not in a git repository. Use --workspace and --repo options, or run this command from within a Bitbucket repository.

The repository has no remotes, reason: no_remote:

✗ Git repository has no remote configured. Add a Bitbucket remote with `git remote add origin <url>`, or use --workspace and --repo options, or run this command from within a Bitbucket repository.

No remote points to Bitbucket, or origin does but its path isn’t workspace/repo, reason: remote_not_bitbucket. With a single remote the message shows its URL (a password in it is shown as ***), with several it lists their names:

✗ Remote '[email protected]:acme/tool.git' is not a Bitbucket URL. Use --workspace and --repo options, or run this command from within a Bitbucket repository.
✗ None of the git remotes (origin, gitlab) is a Bitbucket URL. Use --workspace and --repo options, or run this command from within a Bitbucket repository.

Several remotes point to different Bitbucket repositories and neither origin nor upstream is one of them, reason: ambiguous_remote:

✗ Git remotes fork, mirror point to different Bitbucket repositories and neither origin nor upstream is one of them. Use --workspace and --repo options to pick one.

Fix any of them with explicit flags: bb pr list -w myworkspace -r myrepo.

No workspace specified

✗ No workspace specified. Use --workspace option or set a default workspace with `bb config set defaultWorkspace <name>`.

Error code 6002 CONTEXT_WORKSPACE_NOT_FOUND, thrown by workspace-only commands. Pass -w, export BB_WORKSPACE, or set defaultWorkspace.

“Repository not found”

The workspace and repository resolved, but the pair doesn’t exist or your token can’t see it. Check the spelling, your access, and that the repository lives in that workspace.

See Error Codes for the full list.

Which approach to use

Situation	Use
Interactive work in a clone	Nothing, the git remote resolves it
Scripts and automation	Explicit -w/-r on every command
CI pipelines	BB_WORKSPACE plus -r, or explicit flags
You live in one workspace	bb config set defaultWorkspace <name>

Don’t set defaultWorkspace if you work across several workspaces. A stale default silently sends commands to the wrong place when you’re outside a clone.

Checking what got resolved

bb repo view       # the resolved workspace/repository
bb workspace view  # the resolved workspace

Both accept --json. See JSON Output for their response shapes. For the full list of global flags including -w/-r, see Global Flags.