Github: Pushing to protected branches with fine-grained token

Question

I'm using semantic release in a Github repository to create automatic releases on push. The release needs to commit package.json and CHANGELOG.md to my protected branch.

I used to provide a personal token from my admin account to allow semantic-release to push to protected branch. In order to improve security, I wanted to replace the PT through a new fine-grained token. So I created a fine-grained PT from the same admin account as the old PT and gave it write permission to content. Unfortunately, that doesn't seem to be enough to push to the protected branch.

Any idea which permission might be needed?

UPDATE: Not sure this is even supported yet. I posted the question in the fine-grained personal token feedback discussion

Answer 1

@semantic-release/git needs the Contents permission set to Read and write in order to be able to push to a protected branch.

Do not allow bypassing the above settings MUST be unchecked in the branch protection settings in order for this to work. Allow force pushes is not required.

Note: I find it more convenient to name your Personal Access Token secret CI_GITHUB_TOKEN, or anything differing from the default GITHUB_TOKEN secret provided by GitHub Actions, to differentiate them easily in your workflows (since you should probably use the PAC only for semantic-release).

You will also need to update your action workflow file with the following in order for this to work (otherwise git will keep using the default generated GITHUB_TOKEN):

- name: Checkout
  uses: actions/checkout@v3
  with:
    persist-credentials: false # <--- this

Additionally, if you are using the @semantic-release/github plugin, you may also want to grant Read and write on Issues and Pull requests to allow the bot to comment on issues and PRs when a release mentions it.

If you're looking for a functional implementation (with a manual configuration checklist) of semantic-release in a CI pipeline, you check the PR I made for the cron library.

Important security mention from the documentation

Note: Automatically populated GITHUB_TOKEN cannot be used if branch protection is enabled for the target branch. It is not advised to mitigate this limitation by overriding an automatically populated GITHUB_TOKEN variable with a Personal Access Tokens, as it poses a security risk. Since Secret Variables are available for Workflows triggered by any branch, it becomes a potential vector of attack, where a Workflow triggered from a non-protected branch can expose and use a token with elevated permissions, yielding branch protection insignificant.

This risk is greatly mitigated by using a fine-grained token, and when using the pull_request workflow trigger, which "prevents write permissions and secrets access to the target repository".
But a user with write access to the repository might still push a branch with a workflow exploit that would expose your Personal Access Token.

Further reading:

• Using semantic-release with GitHub Actions
• Security hardening for GitHub Actions
• Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests