Skip to content
Categories:

How to set up a token to clone a private repository on GitHub

Post date:
Author:
Tags: , 

It’s super easy to clone a repository from GitHub, you just clone the HTTP URL for the repository and you’re done.

If you want to clone your private repository it gets a little more tricky, because you have to mess around with SSH. This can be fun, for a certain definition of fun. But typically, if you have your SSH key set up and your SSH agent running, this is painless.

There are scenarios however where you want to be able to clone a private repository in a situation where there is no SSH agent running, such as in an automated fashion, from a cron job or such. GitHub has a nice solution for that: Fine Grained Access Tokens. I set it up but found the process not clearly documented, so I decided to write it down here.

Generate the token

  • Go to GitHub > Settings > Developer Settings – a rather curious name! GitHub is all about software development. So all settings should be “Developer Settings”. What am I missing there? The direct URL is https://github.com/settings/apps
  • Go to Personal access tokens > Fine-grained personal access tokens
  • Click Generate new token
  • Enter the details. Select Only select repositories and choose your private repository.
  • Under Permissions > Repository Permissions, choose Contents and set this to read-only
  • Click Generate token
  • You now see the token in the UI. Copy it for use later on

Cloning the repository using your token

With your new token, we can now clone the repository on the target system.

Create a directory where you want to clone the repository in.

Now you need to initialize this directory as a git repository, change some configuration settings and add the HTTP URL of your repository as the remote. The git configuration settings make sure that the token is saved on your system, so you can keep ‘pull’ling from your repository without having to provide the token again.

$ git init
$ git config credential.helper store
$ git config credential.useHttpPath true
$ git remote add origin https://github.com/mbeijen/private

With these settings in place, you’ll be asked for your username and password. Your username is just your GitHub name. For the password, you use the token you generated earlier:

$ git fetch origin
Username for 'https://github.com/mbeijen/private': mbeijen
Password for 'https://mbeijen@github.com/mbeijen/private': <my newly generated token>
$ git clone # profit!

Benefits and limitations

One of the benefits of using an access token is that it has only limited access, to just this one repository. If you would somehow lose your SSH private key the result can be very bad. Also it’s easy to just revoke this one token.

One of the limitations is that while SSH keys can be set to never expire, at the moment the maximum expiration date for a fine-grained access token seems to be 12 months in the future. So you’ll have to make note of this and refresh your token in time.

One of the other limitations is that it’s not possible to create a token with access to someone else’s private repository, even if you were granted access to this repository. You can only generate a token for your own repository.

These limitations are purely ‘artificial’, they are not inherent to the technology. GitHub marked the ‘finegrained tokens’ as beta, so it’s possible that these limitations might change in the future.