Git authentication¶
bb talks to Bitbucket's REST API using the credentials you stored with
bb auth login. Plain git — git push, git pull, git fetch in a cloned
repository — does not go through bb at all, so it needs credentials of its own.
This page explains how to give git those credentials without writing a token into a repository.
Set it up¶
bb auth setup-git
That is the whole setup. It configures git to ask bb for a credential whenever
it contacts your Bitbucket host, using the credentials already in your keyring.
bb auth setup-git --host https://bitbucket.example.com # a specific host
bb auth setup-git --global=false # this repository only
bb auth setup-git --force # replace an existing helper
By default the configuration is written to your global git config, so a single
setup covers every clone of that host. Pass --global=false from inside a
repository to scope it to that repository instead.
How it works¶
Git supports credential helpers: when it needs a username and password it runs a program, asks it, and uses the answer. Nothing is written to disk.
bb auth setup-git writes one line of git configuration:
credential.https://bitbucket.example.com.helper = !"/usr/local/bin/bb" auth git-credential --config "/home/alice/.config/bb/config.yaml"
When git contacts that host it runs bb auth git-credential, which looks the
host up in the configuration file the line names, where bb auth login stored
it, and hands the credential back for that one request. The file is the one
bb auth setup-git read, so git authenticates as that login whatever
BB_CONFIG_PATH says when git runs it; see
Two identities on one host.
You never run bb auth git-credential yourself. Git runs it.
Two properties are worth knowing:
The configuration is scoped to your Bitbucket host. It is not a bare
credential.helper, which git consults for every remote. Git only ever asks
bb about the host the credentials belong to, and bb answers only for hosts
you have configured — so these credentials are never offered to GitHub, GitLab,
or anywhere else.
Nothing is stored. Rotating or revoking a token takes effect immediately, because git asks again every time. There is no copy to go stale.
Credentials are never written into a repository¶
bb repo clone supplies credentials to git for the duration of the clone only.
The resulting repository contains no credential:
bb repo clone PROJECT/repo
grep -i 'extraheader\|password' repo/.git/config # no matches
A clone's configuration can hold an http.extraHeader entry with a live token
in it. Check with:
git config --local --get http.extraHeader
If that prints anything, remove it and set up the helper instead:
git config --local --unset-all http.extraHeader
bb auth setup-git
That entry is worth removing even if authentication is working. It is a token in plaintext in a file that gets copied and archived with the working tree, and because it is not scoped to a host, git sends it to any HTTP remote in that repository — so adding an unrelated remote would transmit your Bitbucket token to that host.
Tokens and SSH¶
The token you logged in with is what git uses over HTTPS. You do not need a separate credential for git.
Git 2.46 and later take the token from the helper as a Bearer token, which needs no username. Older git takes only a username and password, and Bitbucket accepts a token in the password only beside the right username:
| Token | Username the helper sends |
|---|---|
| Personal access token | Its owner's login name, which bb auth login looks up and stores |
| Project or repository token | x-token-auth |
If bb auth login could not reach Bitbucket, it stored no name, and older git
sends a personal token as x-token-auth, which Bitbucket refuses. Run
bb auth login again, or tell git your login name:
git config --global credential.https://bitbucket.example.com.username alice
If you clone over SSH instead, none of this applies: SSH authenticates with your
SSH key, and git never asks for a username or password. Manage those keys with
bb ssh-key.
Troubleshooting¶
When git still prompts, Troubleshooting checks the host the helper is set up for, asks the helper what it would answer, and deals with another credential manager answering first.