No more passwords! No more personal access tokens! No more SSH keys!
git-credential-oauth is a Git credential helper that securely authenticates to GitHub, GitLab, BitBucket and Gerrit using OAuth.
The first time you authenticate, the helper opens a browser window to the host. Subsequent authentication within storage lifetime is non interactive.
Git assumes users can type a password from memory, but hosts such as GitHub no longer accept passwords without two-factor authentication. Personal access tokens are easy enough to copy and paste but awkward to store securely. git-credential-cache works well for passwords but not personal access tokens because the token is lost when the cache expires. All in all, the usability is so poor that the most popular advice on StackOverflow is to insecurely save credentials in plaintext!
OAuth has multiple advantages over personal access tokens or SSH:
Advantage | OAuth | Personal access token | SSH |
---|---|---|---|
Clone public repo without setup | β | β | π |
Authenticate to popular hosts without setup | β | π | π |
Server authenticity verified automatically | β | β | π |
Protections against token theft[^1] | β | π | only if key has passphrase |
[^1]: Scenario: an old disk backup is leaked.
Download binary from https://github.com/hickford/git-credential-oauth/releases.
Then test that Git can find the application:
git credential-oauth
If you have problems, make sure that the binary is located in the path and is executable.
Several Linux distributions include a git-credential-oauth package including Fedora, Debian and Ubuntu. Ubuntu users can also use PPA hickford/git-credential-oauth to install the latest release.
macOS users can install from Homebrew:
brew install git-credential-oauth
macOS users can alternatively install via MacPorts:
sudo port install git-credential-oauth
Install with winget:
winget install hickford.git-credential-oauth
Go users can install the latest release to ~/go/bin
with:
go install github.com/hickford/git-credential-oauth@latest
As a convenience, you can run:
git credential-oauth configure
This uses the recommended config below.
Git is cleverly designed to support multiple credential helpers. To fill credentials, Git calls each helper in turn until it has the information it needs. git-credential-oauth is a read-only credential-generating helper, designed to be configured in combination with a storage helper.
To configure together with git-credential-cache:
git config --global --unset-all credential.helper
git config --global --add credential.helper "cache --timeout 21600" # six hours
git config --global --add credential.helper oauth
You may choose a different storage helper such as osxkeychain
, wincred
or libsecret
, but git-credential-oauth must be configured last. This ensures Git checks for stored credentials before generating new credentials.
Windows users are recommended to use storage helper wincred
.
Edit your global git config ~/.gitconfig
to include the following lines:
[credential]
helper = cache --timeout 21600 # six hours
helper = oauth
On systems without a web browser, set the -device
flag to authenticate on another device using OAuth device flow.
[credential]
helper = cache --timeout 21600 # six hours
helper = oauth -device
Currently only GitHub and GitLab support this flow. See Gitea feature request #27309.
Edit ~/.gitconfig
manually, or run:
git config --global --unset-all credential.helper oauth
To use with a custom host, eg. gitlab.example.com
:
git-credential-oauth
http://127.0.0.1
.git config --global credential.https://gitlab.example.com.oauthClientId <CLIENTID>
git config --global credential.https://gitlab.example.com.oauthScopes read_repository write_repository
git config --global credential.https://gitlab.example.com.oauthAuthURL /oauth/authorize
git config --global credential.https://gitlab.example.com.oauthTokenURL /oauth/token
git config --global credential.https://gitlab.example.com.oauthDeviceAuthURL /oauth/authorize_device
Would you like to see universal GitLab support? Vote for GitLab issue #374172.
Git Credential Manager (GCM) is an excellent credential helper with broader functionality. However because it's developed in .NET, GCM is prohibitively difficult for Linux distributions to package.
Git Credential Manager | git-credential-oauth | |
---|---|---|
Cross platform | β | β |
Linux arm64 support | π | β |
Packaged in Linux distributions | π | β (many) |
Installation size (Linux) | 82 MB | 5 MB |
Installation size (Windows) | 4 MB | 5 MB |
Ships with Git for Windows | β | π |
Credential storage | In built | Used together with any storage helper |
Development | .NET | Go |
Lines of code | 40,000 | 400 |
Minimum HTTP requests | 1 | 0 |
Authentication to Azure DevOps | β | π (try git-credential-azure) |
Hosts with default config | 4 | 12 |
The maintainer personally uses GCM on Windows and git-credential-oauth on Linux.
Install locally with go install .
.
Use the -verbose
flag to print more details:
git config --global --unset-all credential.helper oauth
git config --global --add credential.helper "oauth -verbose"
You can also test git-credential-oauth in isolation:
echo host=gitlab.com\nprotocol=https | git-credential-oauth -verbose get
You can test configured helpers in combination with git credential fill
, eg.
echo url=https://gitlab.com | git credential fill
To see which helpers Git calls, set export GIT_TRACE=1
.