Python + Poetry GitHub Action Template

Getting started from the template

  1. Rename the src/action_python_poetry package.
  2. Globally replace instances of action-python-poetry and action_python_poetry with your project and package name.
  3. If your repo is private, set it up on CodeCov and add a codecov token to your repo under the CODECOV_TOKEN secret.
  4. Create and test your action. in your package will be executed when the action is run. The environment variables your tests use can be set in pyproject.toml and/or managed in test fixtures.
  5. Update action.yml,, and .github/workflows/test-action.yml to reflect your action’s specification.
  6. Update as appropriate, making sure to retain the original copyright and permissions notices in your distribution according to the MIT license that this template is distributed under.
  7. Remove this section from
  8. Happy hacking!

Like this template?

"Buy Me A Coffee"


name: Run Action

    runs-on: ubuntu-latest
      - uses: k2bd/action-python-poetry@v1
          helloName: k2bd
          repeats: 3

Action Specification



The name of the person to say hello to


Optional – default 1

Number of times to say hello to this person


Install Poetry and poetry install the project

Useful Commands

Note: if Poetry is managing a virtual environment for you, you may need to use poetry run poe instead of poe

  • poe autoformat – Autoformat code
  • poe lint – Linting
  • poe test – Run Tests

Testing the action

The action can be tested locally by building the Dockerfile, e.g.

docker run -e INPUT_HELLONAME=k2bd -e INPUT_REPEATS=2 $(docker build -q .)

Additionally, there is a manual invocation action on the repo called “Test Action” that can be used to invoke the repo’s version of the action from the Actions tab of the repo.


Release a new version by creating a new annotated semver tag e.g. git tag -a v1.2.3 -m "Release version 1.2.3" and pushing it (git push --tags). Then create a new release from that tag in GitHub.

There is an autoversioning action that keeps major version tags (v1, v2, …) and latest up-to-date when a new release is published.


View Github