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. The origin git remote of the current repository
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

• Directoryprojects/

  • Directorymyworkspace-tools/

    • Directory.git/

      • …
    • Directorysrc/

      • Directorycommands/

        • …
      • Directoryservices/

        • …
    • README.md

When you run bb from myworkspace-tools/, the CLI reads the Bitbucket remote from .git/ and uses that workspace and repository as context.

Examples

Scenario 1: inside a git repository

# /projects/myrepo has a Bitbucket origin 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, and they work from anywhere — no git repository 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	6002 CONTEXT_WORKSPACE_NOT_FOUND
Repository-scoped	bb pr *, bb pipeline *, bb issue *, bb commit *, bb status *, bb browse, bb repo view, bb repo delete, bb repo default-reviewers *	6001 CONTEXT_REPO_NOT_FOUND

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

git@bitbucket.org:workspace/repo.git
git@bitbucket.org:workspace/repo

HTTPS format

https://bitbucket.org/workspace/repo.git
https://bitbucket.org/workspace/repo
https://username@bitbucket.org/workspace/repo.git

Limitations

• Only the remote named origin is inspected. If your Bitbucket remote has another name, pass -w/-r.
• Repository names containing a dot (docs.example.com, my.repo) are not parsed.
• ssh://git@bitbucket.org/workspace/repo.git is not recognised — use the git@bitbucket.org:workspace/repo form.

A dotted repository name or an ssh:// URL fails with Remote '<url>' is not a Bitbucket URL. A differently-named remote fails with Git repository has no remote configured.

Error messages

Repository could not be resolved

Three distinct messages, 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.

There is no origin remote — 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.

origin points somewhere other than Bitbucket, or the repository name contains a dot — reason: remote_not_bitbucket:

✗ Remote 'git@github.com:acme/tool.git' is not a Bitbucket URL. Use --workspace and --repo options, or run this command from within a Bitbucket repository.

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, which every command in the CLI supports — see JSON Output. For the full list of global flags including -w/-r, see Global Flags.