Shared GitHub Actions and reusable workflows for Citrine's Python repositories.

To use these shared workflows in your repository, call them from a workflow file (e.g. .github/workflows/pr.yml):

name: PR

on:
  pull_request:

jobs:
  checks:
    uses: CitrineInformatics/common-gh-actions/.github/workflows/repo-checks.yml@v3
    secrets: inherit
    with:
      src: src/my_package

  tests:
    uses: CitrineInformatics/common-gh-actions/.github/workflows/matrix-tests.yml@v3
    secrets: inherit
    with:
      src: src/my_package

Pin to a major version tag (e.g. @v3) to receive non-breaking updates automatically.

If you want private repository access (i.e., your repository depends on another private repository for its testing), your repository must have the following Actions secrets configured:

• AUTOMATION_APP_ID — The GitHub App ID
• AUTOMATION_APP_PRIVATE_KEY — The GitHub App private key

The initialize action will use them to generate a GitHub App token for private repository access. Pass them to reusable workflows with secrets: inherit.

Checks out the caller's repository, sets up Python (via actions/setup-python), and installs project dependencies using uv.

Other Actions (extract-version, check-version-bump, check-deprecations) do not include checkout — callers must handle it themselves. This is intentional so that build issues do not interfere with other checks.

Extracts the project version.

The script assumes that you have a pyproject.toml. It support both static and dynamic version strings (both file and attr), but only supports constant values. It runs in its own Python 3.12 environment so that build problems do not interfere with checks.

Verifies that the pyproject.toml version on the PR branch is strictly greater than the version on main. Uses extract-version internally.

Scans Python source files for @deprecation.deprecated decorators and warnings.warn(..., DeprecationWarning) calls, then checks whether any have passed their removal version. Uses extract-version internally.

Runs standard PR checks: linting, version bump verification, and deprecation scanning.

• validate-inputs -- Fails fast if linter is not a valid option.
• linting -- ruff check and ruff format --check with the project-pinned version (when linter is ruff).
• linting-latest -- Same checks with the latest ruff release (when linter is ruff).
• linting-flake8 -- flake8 lint check (when linter is flake8).
• linting-black -- black --check formatting check (when linter is black).
• version-bump -- Compares PR vs. main version (skippable).
• deprecation-check -- Scans for expired deprecations (skippable).

Runs unit tests across a Python version / OS matrix, with coverage enforcement. The default matrix includes Python 3.10–3.14; use the skip_* and include_* inputs to customize. Coverage is only enforced on the pinned Python version (run-tests-default job).

• run-tests-default -- Tests with default dependencies and coverage threshold.
• run-tests -- Matrix across Python versions and OSes with lowest-direct resolution.
• run-tests-against-latest -- Matrix across Python versions and OSes with highest resolution, potentially including the main branches of citrine-python and gemd-python.

Builds Sphinx documentation and deploys to GitHub Pages.

These are workflows that cannot be shared as reusable workflows due to external limitations. Copy them into your repository.

Packages and publishes to PyPI using an API token. Requires a repository secret called PYPI_API_TOKEN.

Cannot be a reusable workflow because PyPI's Trusted Publishing uses the calling repo's identity. See pypi/warehouse#11096.

This repo uses its own shared workflows for CI. To work locally:

uv sync --dev
uv run ruff check .github/actions tests
uv run ruff format --check .github/actions tests
uv run pytest