GitHub - Understanding Workflow Permissions

Overview - Managing Permissions in GitHub Actions Workflows

In this GitHub Pro Tips post we will look at how to manage permissions in GitHub Actions workflows.

GitHub Actions is a powerful tool for automating your CI/CD pipelines/workflows. It allows you to create workflows that can be triggered by events such as a push to a repository, a pull request, or a new release. Workflows are defined in YAML files that live in the .github/workflows directory of your repository.

In terms of Continuous Integration/Continuous Deployment (CI/CD), GitHub Actions provides a robust feature set for automating, customising, and executing your software development workflows right in your repository. Today we will look at the the permissions parameter as a groundbreaking feature for constraining the permissions provided to the GitHub token.

We will also look at a few practical examples of how and when you would use this feature.

A Dive Into GitHub Workflow's 'Permissions'

Let's discuss the 'permissions' key in detail, which was officially released by GitHub in April 2021. This new feature enables more fine-grained control over the permissions given to the GITHUB_TOKEN in workflows.

This is particularly useful to maintain 'principle of least privilege' - an important security concept stating that a user should have just enough rights necessary to perform their job and nothing more. By minimising the access to resources, you can reduce the damage that could result from accidents or exploits.

The permissions key allows you to set read, write, or none to different scopes. You define permissions at the top level or per job level, giving you flexibility and granularity in terms of access control.

Here is an example of defining permissions at the root level of a workflow:

name: 'My workflow'

on: [push]

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

jobs: ...

You can also define permissions at the job level:

jobs:
  stale:
    runs-on: ubuntu-latest

    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

    steps:
      - uses: actions/stale@v5

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

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the following syntax to disable permissions for all of the available scopes:

permissions: {}

Practical Use Cases

Now that we understand how the permissions key is structured, let's move on to a few practical use cases.

Example 1: Workflows That Need Custom Permissions

In workflows where you need to increase or restrict permissions for a particular job, you can set permissions on the job level:

jobs:
  job1:
    permissions:
      contents: write
    runs-on: ubuntu-latest
    steps:
      - name: Push commit
        run: |
          echo "Hello, GitHub!" > hello.txt
          git add hello.txt
          git commit -m "Add hello.txt"
          git push

In this example, job1 has write access to the repository contents which allows it to create a commit.

Example 2: Cases Where You Want to Limit Potential Damage

Perhaps your workflow only needs read access to the contents of your repository and should never be able to write. By setting the contents key to read or none, you can prevent potential malicious scripts or configuration errors from altering your repo:

permissions: read

Example 3: Third-Party Action Usage

When using third-party actions in your workflow, it's a wise security practice to limit the permissions of the GITHUB_TOKEN, especially if you're not entirely sure about what the third-party action is doing.

permissions:
  actions: none
  checks: read
  contents: read

The example above restricts the third-party actions from initiating further GitHub actions, while allowing read access to checks and contents.

Conclusion

In conclusion, the permissions parameter provides refined control over the GITHUB_TOKEN scope within GitHub Actions, introducing a new level of security and allowing developers to adhere to the principle of least privilege. With this feature, you can avoid accidental write operations, limit the potential harm from vulnerabilities, and securely use third-party actions.

I hope you have enjoyed this post and have learned something new. ❤️

Author

Like, share, follow me on: 🐙 GitHub | 🐧 X/Twitter | 👾 LinkedIn

Marcel.LFollow

Dual Microsoft MVP DevOps + Azure | DevOps Architect | Technical speaker focused on Microsoft technologies, IaC and automation in Azure. Find me on GitHub: https://github.com/Pwd9000-ML