Set up release-please permissions for automatic pull requests and/or GitHub Actions testing on release-please pull requests.

release_please_permissions_setup.md

I find the release-please manual for setting up GitHub Actions a bit unclear, even though it describes how to configure your repository so it can open and approve pull requests. It also mentions, that you will need a personal access token with the correct permissions, if you want your regular GitHub Actions CI tests to run on the resulting pull requests. However, it doesn't specify which exact permissions you need to set for your personal access token and how to get the workflow to see the token as a repository secret. So I am documenting two basic options for setting up release-please with GitHub Actions here, because I am sure to forget this quickly (and it took me a lot of attempts and then some systematic testing to to figure this out).

Option 1: release-please with GITHUB_TOKEN (automatic pull requests, no CI tests on these pull requests)

This approach has the advantage of only needing the standard (always existing) GITHUB_TOKEN. You can enable it via the Settings of the repository and the permissions of the release-please GitHub Actions workflow. So this is quick and easy to set up and maintain. The downside is, that you cannot have your standard GitHub Actions continuous integration testing workflows run automatically on the release-please pull requests, as the GITHUB_TOKEN lacks the needed permissions. And even if you don't care for tests to run on your release-please branches, you will always have to bypass any branch protections that require certain tests to pass, as these cannot be configured to exclude certain types of pull requests. But having to override the checks in the user interface is very counter-intuitive, expecially for anyone not regularly contributing to your project.

TL;DR: here's how to actually do it:

1. Allow GitHub Actions to open and approve pull requests via Settings -> Actions -> General -> Workflow permissions -> [] Allow GitHub Actions to create and approve pull requests: https://github.com/googleapis/release-please-action?tab=readme-ov-file#workflow-permissions
2. Specifically give the release-please Action permission to read and write contents: and pull-requests::

   permissions:
     contents: write
     pull-requests: write
   

Note: I tried also setting actions: write under permissions:, but apparently we cannot give the GITHUB_TOKEN this permission (with this syntax).

Note: I also looked into a number of workarounds. For example, it is possible to have conditional execution of workflow steps, and steps that are skipped by such a conditional expression will report success. This would pass checks, but the lack of the actions: write permission means that even the skipping isn't reached in this scenario.

Option 2: release-please with fine-grained personal access token (automatic pull requests WITH CI tests on these pull requests)

This option has the clear advantage that you can have your standard GitHub Actions continuous integration workflows run on the release-please generated pull requests, which also means that your standard branch protection checks will work. Also, you don't have to change any repository configurations apart from adding the fine-grained personal access token as a secret. But the downsides are:

• The requirement to use a personal access token, even for organizational repositories.
• The overhead of generating, configuring and renewing that personal fine-grained access token.

1. generate fine-grained personal access token

Follow the GitHub documentation for creating a fine-grained personal access token. In more detail, specify the following:

Resource owner

Here, you need to make sure to choose the account that your targeted repositories live under. This is either you personal account, or an organizational account. If you cannot see an organizational account that you are trying to target with your new fine-grained access token, you will have to make sure the organization has them activated via organizational Settings -> Third-party Access -> Personal access tokens.

Expiration

You can renew tokens, but I haven't done this. Not sure if you will have to re-generate a new one and replace the existing one or how this process is organized. But for the release-please use case, you probably want the longest possible expiration time.

Repository access

Grant the new token access to your targeted repositories. This will be either of:

• All repositories (very permissive, probably only use on tokens you only use in your personal account)
• Only select repositories (a token for a defined set of repositories will usually be the most reasonable and secure option)

Permissions

For permissions, set the following Repository permissions to Read and write:

• Contents
• Pull requests

Note: I am a bit astonished that GitHub Actions continuous integration tests were running on the release-please generated pull requests without the actions permissions set to read and write, but they do.

Once the token is generated, make sure to save it like you would save a password, as you will need it like a password for setting it up as a secret---and every time you set up an environment or repository secret with that token.

2. set token up as a secret

To make the token available in the secrets scope of your workflow definitions, you need to follow the GitHub documentation on creating secrets for a repository.

Basically, this is:

1. Got to Settings -> Security -> Secrets and variables -> Actions
2. Click on the green button New repository secret under the section Repository Secrets.
3. Choose a Name, which will become the variable you can later use under the secrets scope. Let's say you choose SOME_NEW_TOKEN.
4. In the Secret field, you paste the token that you generated and saved like a password (starts with github_pat_).
5. Hit Add secret

You can now use the variable ${{ secrets.SOME_NEW_TOKEN }} in the workflows in the respective repository, for example in the token: field for the release-please GitHub Action.