token.md

GitHub token

GitHub Actions using the default GITHUB_TOKEN cannot trigger other workflow runs, i.e. cannot start new GitHub Actions jobs.

You can learn more in the GitHub docs.

:::tip To perform actions after release-plz runs without triggering further workflow runs, you can use GitHub Action output. :::

Why you might need further workflow runs

Release-plz doesn't need to trigger further workflow runs to open the release PR or release your packages. However, you might need release-plz to trigger further workflow runs in the following cases.

CI checks

Workflows acting as checks on pull requests opened by GitHub Actions with the default GitHub token won't run.

For example, you might have CI checks that run:

• On a pull request:

  on:
    pull_request:

• On push:

  on:
    push:

If release-plz uses the default GitHub token, CI checks on the release PR (i.e. the PR opened by release-plz) won't run.

Actions after release

After release-plz release released the packages (typically after running on the main branch), you can further trigger workflows, 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 attach files (such as binaries) to the GitHub release.

If release-plz uses the default GitHub token, these workflows won't be triggered.

How to trigger further workflow runs

To trigger further workflow runs from release-plz, 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.

:::info 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:

steps:
  - name: Checkout repository
    uses: actions/checkout@v4
    with:
      fetch-depth: 0
      # highlight-next-line
      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:
      # highlight-next-line
      GITHUB_TOKEN: ${{ secrets.RELEASE_PLZ_TOKEN }} # <-- PAT secret name
      CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
    with:
      ...

:::warning As shown in the example below, you need to add the token field to the actions/checkout step, too. This allows release-plz to use the PAT also when spawning git commands, such as git tag. :::

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:
   # highlight-start
     # 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:
         # GitHub App ID secret name
         app-id: ${{ secrets.APP_ID }}
         # GitHub App private key secret name
         private-key: ${{ secrets.APP_PRIVATE_KEY }}
   # highlight-end
     - name: Checkout repository
       uses: actions/checkout@v4
       with:
         fetch-depth: 0
   # highlight-next-line
         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:
   # highlight-next-line
         GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
         CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
       with:
         ...