Generate fine grained personal access token in GitHub

What is a Personal Access Token

GitHub is a tool used by many projects to store and version control their code. So, as an initial step during code integration, it is required to fetch the code from version control i.e. GitHub in our case. This can be done by using APIs shared by GitHub. To access these APIs, we cannot just use the GitHub credentials that we use during signing in to GitHub UI. To access GitHub APIs, we need to personal access tokens or SSH keys. This is needed to ensure that API transactions are made more secure by using either personal access tokens or SSH keys.

Why do we need personal access tokens

We require Personal Access Tokens in order to authenticate any transaction in GitHub from integrated applications. In this post, we will discuss how to generate the token in GitHub and use it to access GitHub from another application e.g. from an orchestration tool like Jenkins.

Github Credentials

For repository integration with GitHub to work, we will require a personal access token from GitHub with the required permissions. If our aim is just to clone and checkout a specific repository, then we can provide only read access for that specific repository. However, if we want to write back changes to the repository, then we will also need need write access to that repository.

How to generate github personal access token

GitHub allows for 2 different kinds of personal access tokens (PATs) to be generated. The first one is the classic personal access token which is more generic. Then we have the fine grained token which is more specific than the classic tokens. With fine grained tokens, we can provide specific access to specific repositories for a specific period  of time as compared to classic tokens.

For our purpose, we will generate fine grained token. We will use this token to achieve connectivity over http between GitHub and Jenkins to access github repository. To create a fine grained PAT (personal access token), we will follow the following steps. First of all, we will click the top left hand user icon. We need to select Settings from the menu that appears.

Then on the Settings page we need to select Developer settings. On Developer settings page, we need to access Personal access tokens –>  Fine-grained token. 

Now let us generate the token by clicking on the link Generate new token.

Details for Fine-grained personal access token

This displays a form for filling required details to generate the token.

Let us understand the details to be filled in the form. 

Token name

Provide any unique name for the token

Expiration

The default duration is for 30 days and max duration allowed is one year. The expiration cannot be extended beyond one year, however the token can be regenerated with a new expiration date. If the token has been regenerated, then it has be updated where ever it is being used. This is to ensure higher level of security for the integration.

Description

Here you can describe the purpose, usage, location, etc for which the token has been generated.

Resource owner

As there is just one owner for my repository, I’m shown just one option that is selected by default. More options will be available to select, if there is more than one owner.

Repository access

Public Repositories (read-only)

All repositories

This applies to all current and future repositories owned by the resource owner. Also includes public repositories (read-only).

Only select repositories

Select at least one repository. Max 50 repositories. Also includes public repositories (read-only)

Select repositories

If you have selected Only Select Repositories in the Repository permissions section, then the Select Repositories section will be enabled where you can select those repositories for which you want to provide access.

Permissions

Repository permissions

If you have selected either All Repositories or Only select repositories in Repository permissions section, you can select the type of access that you want to grant to the resource owner in this section. 

For our purpose i.e. a simple integration with Jenkins, we will just provide read/write access to the Contents section which includes repository contents, commits, branches, downloads, releases and merges. This will be sufficient for this requirement. However, we can select other  permissions as and when required.

Account permissions

Manage account level permissions for the access token. As of now we’ll leave it as default.

Once we have filled the above sections, we will be able to see the Overview in the next section as shown below.

Overview

2 permissions for all of your repositories

0 Account permissions

This token will expire <token expiration date>.

Generate token  Cancel

This token will be ready for use immediately.

Final steps

Once you click on Generate token, a new token will be created for you.

You will also be informed to copy the token and note it at a safe location as you will not be able to see the token again.

You are now ready to use the fine grained personal access token for personal API use and for using Git over HTTPS.

Summary

In this post, we have gone through the steps required to generate fine grained personal access token from Github. Once generated, we can use this token to access personal API and for using Git via HTTPS.