gabby

So while working on this GitHub action I stumbled upon a cool trick I wanted to share that I couldn't find a good existing resource for.

Specifically, I wanted a way for my GitHub action to obtain a GitHub access token but without the user having to explicitly supply one when invoking the action. In other words, I wanted to avoid the user having to write this:

jobs:
  delete-cancelled-runs:
    runs-on: 'ubuntu-latest'
    steps:
    - uses: 'MercuryTechnologies/delete-cancelled-runs@latest'
      with:
        workflow-file: 'main.yml'
    env:
      GITHUB_TOKEN: '${{ github.token }}'  # BAD!!!

That last line (explicitly threading the GitHub token to the action) felt like needless boilerplate that I should in principle be able to get rid of. If I could get rid of it then the user could drop the last two lines and would only have to write:

jobs:
  delete-cancelled-runs:
    runs-on: 'ubuntu-latest'
    steps:
    - uses: 'MercuryTechnologies/delete-cancelled-runs@latest'
      with:
        workflow-file: 'main.yml'

However, I couldn't find any good resources on how to do this. In fact, most GitHub actions I've run across that require a GitHub access token seemed to just give up and require the user to explicitly pass in the token (via an input or environment variable). For example, this GitHub action requires you to pass in the GitHub token explicitly.

Moreover, it seemed like GitHub intended GitHub action authors to be able to freely access this token. When researching this I stumbled across this tidbit from the GitHub documentation on automatic authentication:

Important: An action can access the GITHUB_TOKEN through the github.token context even if the workflow does not explicitly pass the GITHUB_TOKEN to the action. As a good security practice, you should always make sure that actions only have the minimum access they require by limiting the permissions granted to the GITHUB_TOKEN. For more information, see "Permissions for the GITHUB_TOKEN."

But there's a catch! This token NOT available via the GITHUB_TOKEN environment variable (believe me, I checked) for third-party GitHub actions. GitHub only supplies the GITHUB_TOKEN environment variable for GitHub actions defined within the same repository as the workflow that invokes the action.

However, the action.yml file can reference the GitHub token using ${{ github.token }} (just like the documentation says), so we just need some way to thread the GitHub token from the action.yml configuration to the GitHub action's script. It turns out that the best way to do this is to add the following logic to the action.yml file:

inputs:
  github-token:
    description: 'GitHub access token'

    required: false

    default: '${{ github.token }}'

This will make the GitHub access token available to the script as an INPUT_GITHUB-TOKEN environment variable. In fact, this appears to be the only way to pass in the GitHub access token for JavaScript actions (since adding new inputs is the only way to extend their environment). As an added bonus, this lets the user override the token if they want to use one with more permissions or a higher rate limit.

And, yeah, that's the entire trick, so (to all GitHub actions out there): please, oh please, stop asking me to give you a GitHub access token. You can fetch the token yourself.