GitHub token

GitHub Actions using the default GITHUB_TOKEN cannot trigger other workflow runs. For example:

• on: pull_request or on: push workflows acting as checks on pull requests opened by GitHub Actions won't run.
• on: release or on: push: tags workflows acting on releases or tags created by GitHub actions won't run.

You can learn more in the GitHub docs.

How to trigger further workflow runs

Release-plz doesn't need to trigger further workflow runs to release your packages. However, if you want to run CI checks on the release PR, or if you want to trigger another workflow after release-plz pushes a tag or creates a release, you need to use one of the following methods.

Trigger workflow manually

To run on: pull_request workflows you can manually close and reopen the release pull request.

Use a Personal Access Token

Use a Personal Access Token (PAT) created on an account with write access to the repository. This is the standard method recommended by GitHub.

Note that the account that owns the PAT will be the author of the release pull request and the commit itself. If you don't want release-plz to open release pull requests and commit with your account, consider creating a machine user. If your machine user needs a cool avatar, you can use the release-plz logo.

Create the PAT, choosing one of the two types:

• Fine-grained: more secure because you can select the repositories where the PAT can be used. Follow these instructions, giving the PAT the following permissions:
  • Select the repositories where you want to use the PAT, to give release-plz write access:
  • Under "Repository permissions", assign "Contents" and "Pull requests" read and write permissions:
• Classic: less secure because you can't scope it to a single repository. Follow these instructions, giving the PAT repo permissions:

Once you generated your token, save it in the secrets, and pass it to both the actions/checkout and release-plz steps:

jobs:
  release-plz:
    name: Release-plz
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.RELEASE_PLZ_TOKEN }} # <-- PAT secret name
      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
      - name: Run release-plz
        uses: MarcoIeni/release-plz-action@v0.5
        env:
          GITHUB_TOKEN: ${{ secrets.RELEASE_PLZ_TOKEN }} # <-- PAT secret name
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

Use a GitHub App

Generate a GitHub token with a GitHub App. This is the approach used by the release-plz repo itself. With this approach, the GitHub App will be the author of the release pull request, e.g. release-plz[bot].

Here's how to use a GitHub App to generate a GitHub token:

1. Create a minimal GitHub App, setting the following fields:

   • Set GitHub App name.
   • Set Homepage URL to anything you like, such as your GitHub profile page.
   • Uncheck Active under Webhook. You do not need to enter a Webhook URL.
   • Under Repository permissions: Contents select Access: Read & write.
   • Under Repository permissions: Pull requests select Access: Read & write.
   • If you use protected tags: Under Repository permissions: Administration select Access: Read & write.
   • (Optional) Under Where can this GitHub App be installed? select Only on this account.
   • (Optional) Set the release-plz logo.

2. Create a Private key from the App settings page and store it securely.

3. Install the App on the repositories where you want to run release-plz.

4. Store the GitHub App ID, and the private key you created in step 2 in GitHub secrets. E.g. APP_ID, APP_PRIVATE_KEY.

5. Use actions/create-github-app-token to generate a token from the GitHub Action:

   steps:
     # Generating a GitHub token, so that PRs and tags created by
     # the release-plz-action can trigger actions workflows.
     - name: Generate GitHub token
       uses: actions/create-github-app-token@v1
       id: generate-token
       with:
         app-id: ${{ secrets.APP_ID }} # <-- GitHub App ID secret name
         private-key: ${{ secrets.APP_PRIVATE_KEY }} # <-- GitHub App private key secret name
     - name: Checkout repository
       uses: actions/checkout@v4
       with:
         fetch-depth: 0
         token: ${{ steps.generate-token.outputs.token }}
     - name: Install Rust toolchain
       uses: dtolnay/rust-toolchain@stable
     - name: Run release-plz
       uses: MarcoIeni/release-plz-action@main
       env:
         GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
         CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

Events that trigger workflows

You can further trigger workflows after release-plz release runs, in the following ways:

• When a GitHub release is published:

  on:
    release:
      types: [published]

• When a git tag is pushed:

  on:
    push:
      tags:
        - "*"

This can be useful to announce automatically the release on socials or to release binaries.

To learn more, see GitHub docs.