Tracking Down Over-Permissioned GitHub Actions Tokens

GitHub has released a public beta of actions-permissions, a toolset designed to help developers identify and apply the minimum required permissions for their GitHub Actions workflows. The tools are available from the GitHubSecurityLab repository.

Every GitHub workflow receives a temporary access token (GITHUB_TOKEN) scoped to the repository. Historically, these tokens were created with broad read/write access, although GitHub introduced a more granular permission model in 2021 and changed the default for new repositories and organizations to read-only in 2023. Despite this, many existing workflows still run with a write-all token because their repository or organization settings have never been updated.

You can check your current configuration by navigating to Settings → Actions and reviewing the “Workflow permissions” section:

A screenshot of the menu for setting your repository's "Workflow permissions." This is found under repository settings--actions. Changing this to read-only (the second radio button in the screenshot) is a security best practice.

Switching to read-only is a recommended security practice, but it can break workflows that unintentionally depend on broad token privileges. Similarly, manually assigning the least privilege set to each workflow can be error-prone: complex workflows often chain multiple actions together, and it is easy to overlook a permission that a step requires. The full scope of privileges needed can also emerge only under specific execution paths, such as when a step fails and a cleanup action runs.

Monitoring and Advising on Workflow Permissions

The actions-permissions project provides two GitHub Actions to assist with this transition. The Monitor action installs a local proxy inside your workflow runner to capture any GitHub API calls made by the workflow, without sending data to any third party. At the end of the run, it publishes its recommended permissions in the workflow summary:

Screenshot of the output from the Monitor action displaying the minimal required permissions for the given repository.

The Advisor action aggregates these results across multiple workflow runs and condenses them into a single recommendation. You can also run it as a standalone local tool:

After you have applied the recommended permissions to your workflow, the monitor and advisor actions can be removed. If you later extend your workflow, you only need to add the permissions that the new steps require. Feedback on the beta can be shared in the project's GitHub Discussions.