python-uv-ci

Reusable GitHub Actions workflow for Python projects that use uv.

Usage

Create a workflow in the consuming repository, for example .github/workflows/python-uv-ci.yml:

name: Python uv CI

on:
  push:
    paths-ignore:
      - "**.md"
  pull_request:
    paths-ignore:
      - "**.md"

permissions:
  contents: read

jobs:
  python-uv-ci:
    uses: znamlab/python-uv-ci/.github/workflows/python-uv-ci.yml@v26.7.0
    permissions:
      contents: read
      pull-requests: write

Optional checks can be disabled or changed with inputs:

jobs:
  python-uv-ci:
    uses: znamlab/python-uv-ci/.github/workflows/python-uv-ci.yml@v26.7.0
    permissions:
      contents: read
      pull-requests: write
    with:
      run_tests: true
      run_lint: true
      type_checker: mypy # mypy, ty, or none

For repositories that need private GitHub dependencies, pass a GitHub App configuration explicitly:

jobs:
  python-uv-ci:
    uses: znamlab/python-uv-ci/.github/workflows/python-uv-ci.yml@v26.7.0
    permissions:
      contents: read
      pull-requests: write
    with:
      app_client_id: ${{ vars.APP_CLIENT_ID }}
      app_token_repositories: ${{ vars.APP_TOKEN_REPOSITORIES }}
    secrets:
      APP_PRIVATE_KEY: ${{ secrets.APP_PRIVATE_KEY }}

APP_TOKEN_REPOSITORIES should be left unset or empty when private GitHub dependencies are not needed. When it is set, APP_CLIENT_ID and APP_PRIVATE_KEY are required.

Security Notes

The reusable workflow keeps the default token permissions read-only and asks callers for pull-requests: write only so the coverage job can update a PR comment.

Private dependency access is optional. The GitHub App private key is accepted as a secret only, the generated installation token is revoked by actions/create-github-app-token, and the test job is skipped for forked pull requests when private dependency access is configured.

Prefer calling this workflow by an immutable tag or SHA once releases are created, rather than using @main.