Poetrel

Poetrel is a GitHub Action that automates GitHub releases for Poetry projects.

It can also handle publishing the project to PyPI, if provided the pypi-token input.

As a composite action of Javascript actions, any OS is supported.

Usage

Before merging a pull request on your main branch, you can set a poetrel: label to this PR, for Poetrel to:

• Bump the project version accordingly
• Update the project Changelog
• Optionally publish the new version to PyPI
• And create a GitHub release describing the changes as detailed in the Changelog

Here are some example labels that you may use:

Supported actions are listed in the Poetry documentation.

Alternatively, you can specify Poetrel to create a release without updating the pyproject.toml version, by using the following label:

It can be useful if you are preparing the first release of your project for example.

Note

The Poetrel action will fail if the commit that triggered the workflow did not originate from a PR with a poetrel: label.

Here is how you can integrate Poetrel in your workflow:

name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest

    permissions:
      # Give the GITHUB_TOKEN write permission to commit
      # and push the updated Changelog and pyproject.toml
      contents: write

    concurrency: pypi
    environment:
      name: pypi
      url: https://pypi.org/project/<YOUR_PROJECT_NAME>/

    steps:
      - name: Checkout project
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Release project
        uses: corentin-regent/poetrel@v1
        with:
          pypi-token: ${{ secrets.PYPI_TOKEN }}

The PYPI_TOKEN secret can be generated here for your project and has to be added to your repository secrets in the GitHub settings.

Changelog format

Poetrel supports both the Markdown format and the reStructuredText format for the Changelog file (inferred from the file extension).

All you have to do is list your changes in an Unreleased section, and Poetrel will handle adding the versions to the Changelog each time the project is released.

The content of this Unreleased section is used as the description of the GitHub release that is created.

Protected branches

Poetrel needs contents: write permissions in order to push the modified Changelog and pyproject.toml.

If your main branch is protected, granting the permissions to the GITHUB_TOKEN will not suffice. Instead you will need to use either a personal access token, deploy keys, or a service account.

Here is how you would use Poetrel using a personal access token:

steps:
  - name: Check out repository
    uses: actions/checkout@v4
    with:
      fetch-depth: 0
      token: ${{ secrets.PAT }}

  - name: Release project
    uses: corentin-regent/poetrel@v1
    with:
      pypi-token: ${{ secrets.PYPI_TOKEN }}

Inputs

See the action.yml file for a reference of all supported inputs.

Notably, you can choose to setup Python and Poetry yourself in your workflow, and pass setup-poetry: false as an argument to Poetrel.

If you wish to override the commit message, make sure to still include [skip ci] if you would like Poetrel's commit not to trigger additional workflow runs.

Automatic releases for a GitHub Action

Poetrel also offers an action for releasing GitHub Actions, in a similar fashion.

Poetrel will, when merging a pull request with one of the following labels:

• Infer the current project version from the changelog
• Bump it accordingly and write the new version in the changelog
• Create a GitHub release for this new version
• Create or update the tag for the corresponding major version (e.g. v1)

Note

Only the these three labels are supported for this poetrel/release-gh-action action.

However, you will still need to create manually the first release of your action, to populate the Changelog and list your Action in the GitHub Marketplace.

Here is how you can integrate this action in your workflow:

name: Continuous Deployment

on:
  push:
    branches:
      - main

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
    concurrency: github-marketplace
    environment:
      name: github-marketplace
      url: https://github.com/marketplace/actions/<YOUR_ACTION_NAME>

    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.PAT }}

      - name: Release the GitHub Action
        uses: corentin-regent/poetrel/release-gh-action@v1

See release-gh-action/action.yml for a reference of supported inputs.

Synchronizing the labels in your repo

For the Poetrel labels to be maintainable in your repository, we offer a corentin-regent/poetrel/sync-labels action, which will synchronize your labels with the ones defined here.

In order to also keep your existing labels, you will need to list them in a labels.toml file in your repository. The labels package can do this for you.

You will only need to setup a personal access token with issues: read permissions, and fill in and run the following commands:

pip install labels
export LABELS_USERNAME="<GITHUB_USERNAME>"
export LABELS_TOKEN="<PERSONAL_ACCESS_TOKEN>"
labels fetch -o <REPO_OWNER> -r <REPO_NAME> -f .github/labels.toml

Here is an example workflow that would then synchronize your labels with Poetrel every time the workflow is changed (e.g. when first created, and when a new Poetrel major version is used):

name: Synchronize Poetrel labels

on:
  push:
    branches:
      - main
    paths:
      - '.github/workflows/labels.yml' # the path to your workflow file (can be different)

jobs:
  sync:
    name: Synchronize Poetrel labels
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Sync labels with GitHub
        uses: corentin-regent/poetrel/sync-labels@v1

See the sync-labels/action.yml file for a reference of all supported inputs.