Workflow Permissions on GitHub

Default GitHub token permissions

The GitHub tutorial uses the builtin GITHUB_TOKEN for the action to get access to the repository. It uses the following permissions on the token:

jobs:
  releaser-pleaser:
    permissions:
      # - list commits
      # - push commits for the release pull request
      # - push new releases & tags
      contents: write

      # - read pull requests for Changelog
      # - read and write release pull request
      # - create labels on the repository
      pull-requests: write

These permissions are sufficient for simple operations. But fail if you want to run another workflow on push: tag.

Workflows on Tag Push

When using the automatic GITHUB_TOKEN to create tags, GitHub does not create new workflow runs that are supposed to be created. This is done to prevent the user from "accidentally creating recursive workflow runs". You can read more about this behaviour in the GitHub Actions docs.

Workflows that have a trigger on pushed tags are often used to build artifacts for the release, like binaries or container images.

on:
  push:
    tags:
      - "v*.*.*"

To circumvent this restriction, you can create a personal access token and instruct releaser-pleaser to use that instead to talk to GitHub.

1. Create Personal Access Token

On your account settings, navigate to the Personal access tokens section.

You can either use a "Fine-grained" or "Classic" token for this. Fine-grained tokens can be restricted to specific actions and repositories and are more secure because of this. On the other hand they have a mandatory expiration of 1 year maximum. Classic tokens have unrestricted access to your account, but do not expire.

Copy the token for the next step.

Fine-grained token

When you create a fine-grained token, restrict the access to the repository where you are using releaser-pleaser.

In the repository permissions you need to give read and write access for Contents and Pull requests. All other permissions can be set to No access (default).

No account permissions are required and you can set all to No access (default).

2. Repository Secret

Next you need to add the personal access token as a repository secret.

Open the repository settings to Secrets and variables > Actions:

https://github.com/YOUR-NAME/YOUR-REPO/settings/secrets/actions

Click on New repository secret and add the personal access token to a secret named RELEASER_PLEASER_TOKEN.

3. Update Workflow

Update the workflow file (.github/workflows/releaser-pleaser.yaml) to pass the new secret to the releaser-pleaser action. You can also remove the permissions of the job, as they are now unused.

 jobs:
   releaser-pleaser:
     runs-on: ubuntu-latest # The action uses docker containers
-    permissions:
-      contents: write
-      pull-requests: write
     steps:
       - name: releaser-pleaser
         uses: apricote/releaser-pleaser@v0.2.0
+        with:
+          token: ${{ secrets.RELEASER_PLEASER_TOKEN }}

The next release created by releaser-pleaser will now create the follow-up workflows as expected.