How to use github token

The GITHUB_TOKEN in GitHub Actions: How it Works, Change Permissions, Customizations

Today I’m gonna tell you everything about the GITHUB_TOKEN in GitHub Actions. You will learn what it is, how it works, how to customize its behavior, and how to limit or change its permissions.

Video

As usual, if you are a visual learner, or simply prefer to watch and listen instead of reading, here you have the video with the whole explanation and demo, which to be fair is much more complete than this post.

If you rather prefer reading, well. let’s just continue 🙂

What is GITHUB_TOKEN

Let’s start with what the GITHUB_TOKEN is in GitHub Actions and how it works.

The GITHUB_TOKEN is a special access token that you can use to authenticate on behalf of GitHub Actions. GitHub automatically creates a GITHUB_TOKEN secret for you to use in your workflow, and you can use it to authenticate in a workflow run.

The way this works is that when you enable GitHub Actions in a repository, GitHub installs a GitHub App on that. The GITHUB_TOKEN secret is basically a GitHub App installation access token.

Before each job begins, GitHub fetches an installation access token for the job from that GitHub App. Since the App has access to a single repo, the token’s permissions are limited to the repository that contains your workflow. And to make it even more secure, the token expires when the job is finished.

Hope the mechanism is now clearer. Let’s quickly see how to use a GITHUB_TOKEN

Use GitHub Token

There are 2 ways to use the token: from secrets and from the context.

Exit fullscreen mode

In this first example we use the secrets.GITHUB_TOKEN to consume it. As mentioned, the secret is automatically generated so you can just use it straight away.

Exit fullscreen mode

Here instead we use the GitHub context, which contains the token. Note that the two are equivalent.

Personal Access Token vs GITHUB_TOKEN

If you are thinking _»why should I use the GITHUB_TOKEN instead of my normal PAT?», remember that a Personal Access Token is always available, so if someone is able to steal that PAT they can potentially do some harm.

The GITHUB_TOKEN instead expires just right after the job is over. So even if someone is able to steal it (which is almost impossible), they basically can’t do anything wrong.

Default Permissions

By Default, the GITHUB_TOKEN has a quite comprehensive list of permissions assigned to it.

This table shows the permissions granted to the GITHUB_TOKEN by default. Good thing is that people with admin permissions to an enterprise, organization, or repository can set the default permissions to be either permissive or restricted.

The Permissions UI

So, let’s see how we can change the permissions of the GITHUB_TOKEN to make it even more secure.

Just go to your repository or organization Settings, then click on Actions.

That is super quick to do, but on the other hand pretty limited. What if I want to assign permissions in a more granular way?

Granular permissions via YAML

You can use the permissions key in the YAML workflow file to modify permissions for the GITHUB_TOKEN for an entire workflow or for individual jobs.

Exit fullscreen mode

And you can use all the permissions that are listed in the table above. Additionally, as you can see below, it supports intellisense if you do it in the GitHub interface directly:

When the permissions key is used, all unspecified permissions are set to no access, with the exception of the metadata scope, which always gets read access.

You can personalize the token permissions either at Job level, or at whole workflow level (or actually both):

Exit fullscreen mode

Conclusions

Hope you have now a better understanding about the GITHUB_TOKEN, what it does and how we can set its permissions properly. Let me know in the comment section below if you have any other questions about it.

Also, check out this video where I talk about creating Personal Access Tokens in GitHub.

Like, share and follow me 🚀 for more content:

How to Set Up HTTPS Personal Access Tokens for Github Authentication

Anthony Heddings is the resident cloud engineer for LifeSavvy Media, a technical writer, programmer, and an expert at Amazon’s AWS platform. He’s written hundreds of articles for How-To Geek and CloudSavvy IT that have been read millions of times. Read more.

As of August 2021, Github has removed support for using your account password from the Git command line. You can still use HTTPS, but you will need to set up a Personal Access Token to use instead of your password.

What Are Personal Access Tokens?

Github still chooses to recommend easier-to-use HTTPS endpoints for accessing repos, but their password based security is a major downside. This is why, if you’ve tried to push or pull code using your account password recently, you may have received the following error:

Git’s command line is a bit misleading here, because it does ask for your “password,” but Git wants you to use something called a Personal Access Token (PAT). This works a lot like a secondary password, except it’s unique, more secure, and can be given more specific permissions that let you grant access to your account safely.

You can also switch to SSH based authentication, which works pretty similarly to access tokens, except they’re tied to your machine and not transmitted anywhere. Still, PATs are easy to set up and use, and do have more flexible permissions than SSH keys.

Making a New Personal Access Token

Setting up a PAT will require you to make a new one from Github’s settings, and swap your local repositories over to using them. Head over to your personal account settings to generate a new token. Scroll down to “Developer Settings.” Select “Personal Access Tokens,” and generate a new one:

You’ll need to verify your actual account password. Give the token a name, and select an expiration date. You probably want to change it from the default of 30 days, though Github will show a warning if you select “No Expiration.” It’s not terrible to have a permanent token, but you should likely be changing passwords and tokens at least every 6 months.

Finally, you can choose which scopes this token has. This allows you to allow or disallow certain actions. If you just want to use git from the command line with your repositories, you probably only care about the “repo” scope, which gives control over your repositories.

You’ll get a token like the following, that can be used in place of your password:

Switching To Personal Access Tokens

If your account password isn’t cached, you can simply enter in the new token, and it should work. If your cache is stale though, you will need to reset it.

On macOS, it’s accessible through the Keychain Access app. Search for “github.com,” find the “internet password” entry for your Git account, and change the key.

For Linux or WSL, you’ll need to unset the cache, either locally (for a single repo), or globally:

Then, you can push or pull from your repo normally, and it will have you enter the new PAT if it’s not yet cached. You can cache this token for longer, either by editing the cache timeout in the credential helper:

Or by configuring it to store the credentials permanently in

Note that if you previously had this cache turned on, you may need to delete the line with the old cached credentials in the

jonjack / add-update-refresh-github-access-token-on-mac.md

Using an Access Token for the first time

Follow the instructions on Github to Create an Access Token in Github

Configure Git to use the osxkeychain

By default, git credentials are not cached so you need to tell Git if you want to avoid having to provide them each time Github requires you to authenticate. On Mac, Git comes with an “osxkeychain” mode, which caches credentials in the secure keychain that’s attached to your system account.

You can tell Git you want to store credentials in the osxkeychain by running the following:-

Add your access token to the osxkeychain

Updating an existing Access Token

Regenerate token on Github

Remove an existing token from your Mac keychain

You can check if you have an existing password or token stored in the osxkeychain using the following command.

If this returns a result you can then delete it using the following.

If authentication fails and you are not prompted to enter your credentials, like in the above example, or you are repeatedly challenged by Github for your credentials, then check if you have the credential.helper set.

Then try again and you should now be prompted for your credentials.

Ensure you provide your access token rather than password when prompted.

neilsy commented Dec 9, 2019

I had to change access method, from login/password to token access. But trying to delete the existing credential, I found that ‘git credential-osxkeychain erase’ seemed to hang for me (on OS X 10.14.6). I was able to delete the credential in the Keychain Access app without any problem. After that, running ‘git pull’ prompted me for new credentials

mickod commented Dec 27, 2020

maximivanov commented Jan 15, 2021

Fresh Big Sur 11.1 install. I want to remove a Github token from the keychain.

git credential-osxkeychain erase hangs.

I can see a github.com entry in the Keychain Access UI, but I cannot remove it.
If I filter for that entry with search box, right-click and Delete «github.com» does nothing.
If I clear the filter and find the entry in the list, Delete option is not available in the context menu.

I ended up using a command line tool to remove the token from the keychain:

colvint commented Feb 3, 2021

Also fresh Big Sur 11.1 install here.

Did the trick for me.

SimonGolms commented Feb 21, 2021

After typing git credential-osxkeychain erase the display does not hang/load, instead it expects another input, see: https://stackoverflow.com/a/28007050

jondhill333 commented Mar 11, 2021

Yep, the above works, it just appears like its done nothing. However just go to push to Github again and you will see it asks for authorisation and it should be all working.

frisbiesa commented Mar 15, 2021

I deleted the token from the keychain but I’m still not being prompted for my new api password. Super frustrating.

startakovsky commented Apr 21, 2021

Same. This string of comments didn’t help / weren’t intuitive to me. Going to manually manipulate git config.

benslack19 commented May 19, 2021 •

This was much more frustrating than I expected as well but got it to eventually work. I’m on MacOS Catalina. Here were my steps:

Archaeo-Programmer commented May 24, 2021

My solution ended up being much simpler than the suggestions above (at least for macOS Mojave version 10.14.6). After following the instructions above to generate/re-generate (I had to regenerate a token due to the new authentication token formats), I tried the following:

How To: Clone GIT Repo Using Personal Access Token

Overview

In this post I’ll show you how you can clone a Git repository using a Personal Access Token instead of a regular password.

Personal Access Tokens are useful in a variety of situations. I recently opted to use an access token on a work laptop rather than using my ‘god mode’ credentials. That way, if I needed to hand the laptop back to my employer I could easily revoke the access.

Enough talk … lets get to it!

Create a Token

First thing we need to do is create a Personal Access Token through the Github online portal.

2. Click your profile picture in the right hand menu and then navigate to SETTINGS > DEVELOPER SETTINGS within GitHub (or click this link to go straight there).

3. Click ‘Generate New Token’ to create a new token.

Name the token appropriately so you can identify it later on (if needed) and select the appropriate scope. I’d suggest you select the Repo – Full Control scope.

IMPORTANT: Make note of the token because once you close the window you won’t be able to view the token again!

4. Name the token appropriately so you can identify it later on (if needed) and finally, select the appropriate scope. Note: At a minimum for cloning a repo I suggest you select the Repo – Full Control scope.

Clone Repo With Your Token

Now lets clone a repo using your newly generated Personal Access Token. You’ll notice that I’m using the token instead of the ordinary account password.

Common Issues

While Cloning a Private Repo using a Personal Access Token I encountered the below error:

The cause of the issue is lack of privileges. Make sure you have granted ‘full control’ access rights to your Personal Access Token, anything less did not work for me.

Final Thoughts

I hope you’ve found this post useful. If you have any other tips to share, please post them below to help others out there.

This blog is my place to share my thoughts, helpful solutions and just random nerdy stuff.

Managing Git(Hub) Credentials

usethis can help you with many of the Git and GitHub tasks that arise when managing R projects and packages. Under the hood, two lower-level packages are critical to this:

Both packages need access to credentials in order to act on your behalf:

This article describes our recommendations for how to set up your Git and GitHub credentials. Our goal is a setup that works well for usethis and for other tools you may be using, such as command line Git and Git clients (including, but not limited to, RStudio).

This is a good time to check that you have up-to-date versions of the packages we’re talking about here. In particular, you want gh >= v1.2.1, which knows about the new token format GitHub announced and adopted in March 2021.

TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token

Our main recommendations are:

Next we provide some context and a rationale for these recommendations. In the following section, we explain how to actually implement this.

HTTPS vs SSH

Instead of HTTPS, you could use SSH. Many people have valid reasons for preferring SSH and they should carry on. Our recommendation for HTTPS is because it’s easier than SSH for newcomers to set up correctly, especially on Windows. GitHub has also long recommended HTTPS to new users. Finally, using HTTPS with a PAT kills two birds with one stone: this single credential can be used to authenticate to GitHub as a regular Git server and for its REST API. If you authenticate via SSH for “regular” Git work, you still have to set up a PAT for work that uses the REST API.

Two-factor authentication

Turning on two-factor authentication for important online accounts is just a good idea, in general. For example, we make 2FA a hard requirement for all members of the tidyverse and r-lib GitHub organizations.

More background on the deprecation of “username + password” can be found in GitHub’s blog post Token authentication requirements for Git operations.

Git credential helpers and the credential store

It’s awkward to provide your credentials for every single Git transaction, so it’s customary to let your system remember your credentials. Git uses so-called credential helpers for this and, happily, they tend to “just work” these days (especially, on macOS and Windows) If you’re trying to follow the advice in this article and things don’t work the way we say they do, consider that you may need to update Git. Credential helpers are absolutely an area of Git that has improved rapidly in recent years and the gitcreds and credentials package work best with recent versions of Git.

Practical instructions

How do you actually implement these recommendations? The diagnostic functions usethis::gh_token_help() and usethis::git_sitrep() will offer some of the advice you see here, but directly in your R session.

Adopt HTTPS

Make sure to use HTTPS URLs, not SSH, when cloning repos or adding new remotes:

It’s fine to adopt HTTPS for new work, even if some of your pre-existing repos use SSH.
It’s fine to use HTTPS for one remote in a repo and SSH for another.
It’s fine to use HTTPS remotes for one repo and SSH remotes for another.
It’s fine to interact with a GitHub repo via HTTPS from one computer and via SSH from another.
This is not an all-or-nothing or irreversible decision.
As long as the relevant tools can obtain the necessary credentials from a cache or you, you are good to go.

Turn on two-factor authentication

See GitHub’s most current instructions here:

If you don’t already use a password manager such as 1Password or LastPass, this is a great time to start! Among other benefits, these apps can serve as an authenticator for 2FA.

Turning on 2FA is recommended, but optional.

Get a personal access token (PAT)

Assuming you’re signed into GitHub, create_github_token() takes you to a pre-filled form to create a new PAT. You can get to the same page in the browser by clicking on “Generate new token” from https://github.com/settings/tokens. The advantage of create_github_token() is that we have pre-selected some recommended scopes, which you can look over and adjust before clicking “Generate token”.

It is a very good idea to describe the token’s purpose in the Note field, because one day you might have multiple PATs. We recommend naming each token after its use case, such as the computer or project you are using it for, e.g. “personal-macbook-air” or “vm-for-project-xyz”. In the future, you will find yourself staring at this list of tokens, because inevitably you’ll need to re-generate or delete one of them. Make it easy to figure out which token you need to fiddle with.

GitHub encourages the use of perishable tokens, with a default Expiration period of 30 days. Unless you have a specific reason to fight this, I recommend accepting this default. I assume that GitHub’s security folks have good reasons for their recommendation. But, of course, you can adjust the Expiration behaviour as you see fit, including “No expiration”.

Once you’re happy with the token’s Note, Expiration, and Scopes, click “Generate token”.

You won’t be able to see this token again, so don’t close or navigate away from this browser window until you store the PAT locally. Copy the PAT to the clipboard, anticipating what we’ll do next: trigger a prompt that lets us store the PAT in the Git credential store.

Sidebar about storing your PAT: If you use a password management app, such as 1Password or LastPass (highly recommended!), you might want to add this PAT (and its Note) to the entry for GitHub. Storing your PAT in the Git credential store is a semi-persistent convenience, sort of like a browser cache or “remember me” on a website, but it’s quite possible you will need to re-enter your PAT in the future. You could decide to embrace the impermanence of your PAT and, if it is somehow removed from the store, you’ll just re-generate a new PAT and re-enter it. If you accept the default 30-day expiration period, this is a workflow you’ll be using often anyway. But if you create long-lasting tokens or want to play around with the functions for setting or clearing your Git credentials, it can be handy to have your own record of your PAT in a secure place, like 1Password or LastPass.

Put your PAT into the local Git credential store

We assume you’ve created a PAT and have it available on your clipboard.

How to insert your PAT in the Git credential store? Do this in R:

You will have the gitcreds package installed, as of usethis v2.0.0, because usethis uses gh, and gh uses gitcreds.

If you don’t have a PAT stored already, it will prompt you to enter your PAT. Paste!

If you already have a stored credential, gitcreds::gitcreds_set() reveals this and will even let you inspect it. This helps you decide whether to keep the existing credential or replace it. When in doubt, embrace a new, known-to-be-good credential over an old one, of uncertain origins.

You can check that your PAT has been successfully stored with usethis::gh_token_help() executed in a fresh R session:

The more general function usethis::git_sitrep() will also report on your PAT, along with other aspects of your Git/GitHub setup.

Ongoing PAT maintenance

You are going to be (re-)generating and (re-)storing your PAT on a schedule dictated by its expiration period. By default, once per month.

Hopefully it’s becoming clear why each token’s Note is so important. The actual token may be changing, e.g., once a month, but its use case (and scopes) are much more persistent and stable.

Additional resources

Most users should be ready to work with Git and GitHub from R now, specifically with gert, gh, and usethis. In this section, we cover more specialized topics that only apply to certain users.

GitHub Enterprise

As of v2.0.0, usethis should fully support GitHub Enterprise deployments. If you find this is not true, please open an issue.

In general, usethis, gh, and gitcreds should all work with GitHub Enterprise, as long as the intended GitHub host is discoverable or specified. For example, you can store a PAT for a GitHub Enterprise deployment like so:

You can also troubleshoot PATs with GHE with the usual functions:

At the time of writing, credentials::set_github_pat() is hard-wired to “github.com”, but this may be generalized in the future.

Why do gitcreds+gh and credentials+gert even check environment variables? Once they retrieve a PAT from the store, they temporarily cache it in an environment variable, which persists for the duration of the current R session. This allows a discovered PAT to be reused, potentially by multiple packages, repeatedly over the course of an R session.

Add a line like this, but substitute your PAT:

Make sure this file ends in a newline! Lack of a newline can lead to silent failure to load startup files, which can be tricky to debug. Take care that this file is not accidentally pushed to the cloud, e.g. Google Drive or GitHub.

What about the remotes and pak packages?

The remotes and pak packages both help us to install R packages from GitHub:

Lifecycle-wise, remotes is being replaced by pak, but we are still in the transition period, where both are maintained.

Both of these packages potentially need a GitHub PAT. A PAT is necessary, for example, to install from a private GitHub repo. Even when accessing public resources, a PAT is helpful because it implies a much higher rate limit for requests to the GitHub API.

pak uses the same PAT-finding approach as usethis/gh/gitcreds. Once you’ve done the setup described above, pak should “just work”, with the same PAT as everything else.

remotes does NOT use the new PAT-finding approach and, instead, only consults the GITHUB_PAT environment variable, falling back to a built-in generic credential.

What should you do re: installing packages from GitHub?

If you want to keep using remotes, instead of pak, you could just rely on the built-in credential. This will suffice if rate-limiting is the only concern, but obviously will not provide access to private repositories.

If you use remotes, make sure to update to the latest version, to guarantee that the built-in credential is valid.

Continuous integration

If this automatic token doesn’t have sufficient permissions, you’ll need to create a suitable token and store it as a repository secret.

This is also the general approach for CI/CD platforms other than GitHub Actions: