ni/python-actions

ni/python-actions is a Git repository containing reusable GitHub Actions for NI Python projects.

Table of Contents

• ni/python-actions
  • Table of Contents
  • ni/python-actions/setup-python
    • Usage
    • Inputs
      • python-version
    • Outputs
      • python-version
      • python-path
    • Environment Variables
      • pythonVersion
  • ni/python-actions/setup-poetry
    • Usage
    • Inputs
      • poetry-version
      • use-cache
    • Outputs
      • cache-hit
  • ni/python-actions/check-project-version
    • Usage
    • Inputs
      • project-directory
      • expected-version
  • ni/python-actions/update-project-version
    • Usage
    • Inputs
      • project-directory
      • branch-prefix
      • create-pull-request
      • version-rule and use-dev-suffix
      • token

ni/python-actions/setup-python

The setup-python action installs Python and adds it to the PATH.

It is a thin wrapper for https://github.com/actions/setup-python which is intended to single-source the default Python version for multiple NI Python projects.

By default, this action installs Python 3.11.9.

Usage

steps:
- uses: ni/python-actions/[email protected]

Inputs

python-version

You can specify the python-version input for testing with multiple versions of Python:

strategy:
  matrix:
    python-version: [3.9, '3.10', 3.11, 3.12, 3.13]
steps:
- uses: ni/python-actions/[email protected]
  with:
    python-version: ${{ matrix.python-version }}

Outputs

python-version

You can use the python-version output to get the actual version of Python, which is useful for caching:

steps:
- uses: ni/python-actions/[email protected]
  id: setup-python
- uses: actions/cache@v4
  with:
    path: .venv
    key: venv-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('poetry.lock') }}

python-version is unique across implementations (CPython vs. PyPy) and free-threaded builds:

• CPython: "3.13.4".
• CPython with free-threading: "3.13.4t"
• PyPy: "pypy3.11.11-v7.3.19"

python-path

actions/setup-python sets the pythonLocation environment variable to the directory containing the Python installation.

You can also use the python-path output to get the path to the Python interpreter:

steps:
- uses: ni/python-actions/[email protected]
  id: setup-python
- run: pipx install <package> --python ${{ steps.setup-python.outputs.python-version }}

Environment Variables

pythonVersion

This is the same as outputs.python-version and is mainly intended for use in ni/python-actions/setup-poetry.

ni/python-actions/setup-poetry

The setup-poetry action installs Poetry, adds it to the PATH, and caches it to speed up workflows.

This action installs Poetry using the Python version that was selected by the setup-python action, so you must call setup-python first.

By default, this action installs Poetry 1.8.2.

Usage

steps:
- uses: ni/python-actions/[email protected]
- uses: ni/python-actions/[email protected]
- run: poetry install -v

Inputs

poetry-version

steps:
- uses: ni/python-actions/[email protected]
- uses: ni/python-actions/[email protected]
  with:
    poetry-version: 2.1.3
- run: poetry install -v

use-cache

If you run into caching problems, you can disable caching by specifying use-cache: false.

Outputs

cache-hit

You can use cache-hit to check whether Poetry was loaded from cache. This is mainly intended for testing the action.

ni/python-actions/check-project-version

The check-project-version action uses Poetry to get the version of a Python project and checks that it matches an expected version. By default, this action checks against github.ref_name, which is the GitHub release tag for GitHub release events.

This action requires Poetry, so you must call setup-python and setup-poetry first.

Usage

steps:
- uses: ni/python-actions/[email protected]
- uses: ni/python-actions/[email protected]
- uses: ni/python-actions/[email protected]
  if: github.event_name == 'release'

Inputs

project-directory

You can specify project-directory to check a project located in a subdirectory.

- uses: ni/python-actions/[email protected]
  with:
    project-directory: packages/foo

expected-version

You can specify expected-version to check against something other than github.ref_name.

- uses: ni/python-actions/[email protected]
  with:
    expected-version: ${{ steps.get-expected-version.outputs.version }}

ni/python-actions/update-project-version

The update-project-version action uses Poetry to update the version of a Python project and creates a pull request to modify its pyproject.toml file.

This action requires Poetry, so you must call setup-python and setup-poetry first.

Creating a pull request requires the workflow or job to have the following GITHUB_TOKEN permissions:

permissions:
  contents: write
  pull-requests: write

Usage

steps:
- uses: ni/python-actions/[email protected]
- uses: ni/python-actions/[email protected]
- uses: ni/python-actions/[email protected]

Inputs

project-directory

You can specify project-directory to update a project located in a subdirectory.

- uses: ni/python-actions/[email protected]
  with:
    project-directory: packages/foo

branch-prefix

You can specify branch-prefix to customize the pull request branch names. The default value of users/build/ generates pull requests with names like users/build/update-project-version-main and users/build/update-project-version-releases-1.1.

- uses: ni/python-actions/[email protected]
  with:
    branch-prefix: users/python-build/

create-pull-request

You can use create-pull-request and project-directory to update multiple projects with a single pull request.

- uses: ni/python-actions/[email protected]
  with:
    project-directory: packages/foo
    create-pull-request: false
- uses: ni/python-actions/[email protected]
  with:
    project-directory: packages/bar
    create-pull-request: false
- uses: ni/python-actions/[email protected]
  with:
    project-directory: packages/baz
    create-pull-request: true

version-rule and use-dev-suffix

You can specify version-rule and use-dev-suffix to customize the versioning scheme.

• version-rule specifies the rule for updating the version number. For example, major will update 1.0.0 -> 2.0.0, while patch will update 1.0.0 -> 1.0.1. See the docs for poetry version for the list of rules and their behavior.
• use-dev-suffix specifies whether to use development versions like 1.0.0.dev0.

The defaults are version-rule=patch and use-dev-suffix=true, which have the following behavior:

Old Version	New Version
1.0.0	1.0.1.dev0
1.0.1.dev0	1.0.1.dev1
1.0.1.dev1	1.0.1.dev2

When you are ready to exit the "dev" phase, you should manually update the version number to the desired release version before creating a release in GitHub.

token

The default GITHUB_TOKEN cannot trigger PR workflows, so the generated pull request will not run any status checks. You can work around this by using token to specify a token that is saved in a repo/org secret.

See Triggering further workflow runs in the create-pull-request action documentation for more info about this problem and other solutions to it.