Easier builds and deployments using Git over HTTPS and OAuth

We first introduced OAuth2 tokens in the GitHub API starting in v3. Unlike usernames and passwords, OAuth tokens provide additional benefits:

• Revocable access. Tokens can be revoked at any time from a user’s settings screen in GitHub.
• Limited access. When requesting access, applications declare the level of permissions they need, and tokens are created with the appropriate scope as granted by the user.

Deployment scripts and continuous integration services that need to clone and fetch private repositories haven’t seen the full benefit of HTTP transport because it requires a GitHub username and password for private repositories. Deploy keys have been the preferred way to delegate access for these types of services, and unfortunately they do not work with HTTP transport.

Today, we’re bringing the benefits of OAuth to our HTTP transport stack for Git operations.

Using OAuth with Git

When using Git over HTTPS for private repositories, you use your GitHub username and password which are passed to the server using Basic Authentication. To use OAuth instead, you’ll need an OAuth token. You can create a token via the Authorizations API or web flow. Remember, you’ll need repo scope to access private repositories.

Next, you can simply use an OAuth token for the username and either a blank password or the string x-oauth-basic when cloning a repository.

git clone https://github.com/username/repo.git
Username: <token>
Password:

If you’re cloning inside a script and need to avoid the prompts, you can add the token to the clone URL:

git clone https://<token>@github.com/owner/repo.git

or

git clone https://<token>:x-oauth-basic@github.com/owner/repo.git

Note: Tokens should be treated as passwords. Putting the token in the clone URL will result in Git writing it to the .git/config file in plain text. Unfortunately, this happens for HTTP passwords, too. We decided to use the token as the HTTP username to avoid colliding with credential helpers available for OS X, Windows, and Linux.

To avoid writing tokens to disk, don’t clone. Instead, just use the full git URL in your push/pull operations:

mkdir foo
cd foo
git init
git pull https://<token>@github.com/username/bar.git

Go forth and pull

We’re excited to expand our support of HTTP transport using OAuth. While Git over HTTP with OAuth reduces friction for some types of applications, keep in mind that unlike deploy keys, OAuth tokens work for any repository for which the user has access.

Written by

Wynn Netherland

@pengwynn