Updates the permissions block to be minimal by aeisenberg · Pull Request #689 · github/codeql-action (original) (raw)

And adds a permissions block to the README.

Fixes #464.

Merge / deployment checklist

• Confirm this change is backwards compatible with existing workflows.
• Confirm the readme has been updated if necessary.
• Confirm the changelog has been updated if necessary.

From our last internal discussion about this, I believe that actions: read is (only) needed if you are analyzing a private repository, and security-events: write is (only) needed if you are not analyzing a pull request. And I think we need at least contents: read (or pull-requests: read for PRs). The overlapping scopes for PRs make this a bit confusing.

So perhaps let's go with the recommendation of actions: read, contents: read, security-events: write? If it turns out that's not entirely minimal, we can refine it again later.

Sure, and I can add some comments on when different scopes may not be needed.

Here are the API calls we are making (just doing a code search for .request:

• GET /repos/:owner/:repo/actions/runs/:run_id (actions: read)
• GET /repos/:owner/:repo/actions/workflows (actions: read)
• PUT /repos/:owner/:repo/code-scanning/analysis/status (security-events: write)
• GET /enterprise/code-scanning/codeql-bundle/find/{tag} (security-events: read)
• GET /enterprise/code-scanning/codeql-bundle/download/{asset_id} (security-events: read)
• GET /repos/:owner/:repo/code-scanning/codeql/databases (security-events: read)
• PUT /repos/:owner/:repo/code-scanning/codeql/databases/:language (security-events: write)
• PUT /repos/:owner/:repo/code-scanning/analysis (security-events: write)

Unless I've missed something, we only need security-events: write and actions: read. And the latter is only for private repos.

Plus you need enough permission to check out the repo itself in the workflow (but not in the Action), which I believe is either contents: read or pull_requests: read.

Ah..yes. Again, only for private repos, it seems. So, contents: read guards the GET /repos/:owner/:repo/contents/:path endpoint. I don't see anything about pull requests, though. This would only be for things like editing the PR itself, or adding comments, etc.

And adds a permissions block to the README.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM once you resolve the changelog conflict. Thanks!

aeisenberg deleted the aeisenberg/update-permissions branch

August 9, 2021 22:12

Here are the API calls we are making (just doing a code search for .request:

• GET /repos/:owner/:repo/actions/runs/:run_id (actions: read)
• GET /repos/:owner/:repo/actions/workflows (actions: read)
• PUT /repos/:owner/:repo/code-scanning/analysis/status (security-events: write)
• GET /enterprise/code-scanning/codeql-bundle/find/{tag} (security-events: read)
• GET /enterprise/code-scanning/codeql-bundle/download/{asset_id} (security-events: read)
• GET /repos/:owner/:repo/code-scanning/codeql/databases (security-events: read)
• PUT /repos/:owner/:repo/code-scanning/codeql/databases/:language (security-events: write)
• PUT /repos/:owner/:repo/code-scanning/analysis (security-events: write)

Unless I've missed something, we only need security-events: write and actions: read. And the latter is only for private repos.

@aeisenberg I am trying to figure out the required permissions for any GitHub Action. What is the process to get all the necessary permission? Thanks

There's no principled way of doing this that I can think of. An action can make any arbitrary request to the github api. And it can make requests in many ways (since they are just fundamentally REST requests): curl, gh, octokit, etc.

You could try setting very restrictive permissions, and slowly loosen them until you get your workflow passing. Alternatively, you can try to eyeball the code, which could be tricky if the action is doing non-standard things.

There's no principled way of doing this that I can think of. An action can make any arbitrary request to the github api. And it can make requests in many ways (since they are just fundamentally REST requests): curl, gh, octokit, etc.

You could try setting very restrictive permissions, and slowly loosen them until you get your workflow passing. Alternatively, you can try to eyeball the code, which could be tricky if the action is doing non-standard things.

Thank you!

This was referenced

Mar 18, 2026

This was referenced

Apr 15, 2026

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})