GitHub Actions: Permissions

Overview

One of the key features of GitHub Actions is the ability to authenticate and authorize actions using GitHub Tokens, such as the GITHUB_TOKEN. Additionally, GitHub Actions also allows repository owners to fine-tune the access that workflow jobs have using the permissions keyword. In this blog post, we will take a detailed look at how someone can have granular control over the actions that their workflows take.

GITHUB_TOKEN

GITHUB_TOKEN is a special token that is automatically generated by GitHub Actions and can be used to perform a variety of actions within a workflow. This token is unique to each workflow and can be used to authenticate with the GitHub API, making it a powerful tool for automating tasks and interacting with the GitHub platform. The token is scoped to the repository where the workflow is defined and it has access to the same permissions as the person who triggered the workflow.

You reference the GITHUB_TOKEN in two ways:

• using the github context: ${{ github.token }}
• using the secrets context: ${{ secrets.GITHUB_TOKEN }}

It is useful to know that events triggered by the GITHUB_TOKEN, with the exception of workflow_dispatch and repository_dispatch, do not start a new workflow run when you use the repository’s GITHUB_TOKEN to carry out tasks. This stops you from unintentionally generating workflow runs that are recursive.

You can also set the default permissions for your repository by choosing one of two options:

• Read/write permissions: Workflows have read and write permissions in the repository for all scopes.
• Read repository contents permission: Workflows have read permissions in the repository for the contents scope only.

I recommend that you select the second option, following best security practices, and if you need additional permissions, you can specify them in the workflow yaml, as we will see next.

Permissions

The permissions keyword is a feature in GitHub Actions that allows repository owners to fine-tune the access that workflow jobs have to References within a repository. This can include things like reading or writing to the repository’s code, creating and managing issues, and interacting with the GitHub API.

Permissions can be used within single jobs or as a top-level key that applies to all jobs in the workflow. All operations and run commands within a given job that use the GITHUB_TOKEN are granted the access privileges you define when the permissions keyword is added to that task.

Here are all the possible values of permissions:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

# Define read or write access for all of the available scopes
permissions: read-all|write-all

# Disable permissions for all of the available scopes
permissions: {}

NOTE: If you specify the access for any of these scopes, all of those that are not specified are set to none.

Example

Let’s take a look at an example:

name: permissions

on:
  workflow_dispatch:

permissions: read-all # applies to all jobs in the workflow

jobs:
  job-1:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          echo "Test Job 1"
  job-2:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          echo "Test Job 2"
  job-3:
    runs-on: ubuntu-latest
    permissions: {} # applies to only this job, overrides the workflow-scoped value
    steps:
      - uses: actions/checkout@v4
      - run: |
          echo "Test Job 3"

In the above example, we set read-all permission for all the jobs in a workflow. We also override that value in job-3, where we disable all permissions and so we expect that this job will fail since it can not complete the action of checking out the repository.

Summary

In summary, the combination of GITHUB_TOKEN and permissions is a powerful tool that allows the fine-tuned access of workflow jobs. When assigning permissions, always remember to follow security best practices.

Resources

• Assigning permissions to jobs
• Authentication in a workflow