GitHub Action

Note

The composite Action described on this page lands in P3.2 (the sibling plan to this docs site). The contract documented here is the authored interface — once P3.2 ships and a release tag is cut, uses: tyy0811/physics-lint@v1.X.Y will resolve. Until then this page is the design reference; for current CI integration use the inline pip install physics-lint && physics-lint check pattern from the README.

physics-lint ships a composite GitHub Action at the root of tyy0811/physics-lint for drop-in CI integration. Call it as:

uses: tyy0811/physics-lint@v1.0.0
with:
  model: physics_lint_adapter.py

Convention note

The dominant convention for major Actions is a separate <name>-action repo (astral-sh/ruff-action, astral-sh/setup-uv, github/codeql-action). physics-lint ships its Action in-repo at root instead, which trades convention alignment for version-sync automation: the Action tag and the installed physics-lint version are locked by construction (uses: …@v1.0.0 installs physics-lint==1.0.0).

Minimal example

name: physics-lint
on: [push, pull_request]

permissions:
  contents: read
  security-events: write

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tyy0811/physics-lint@v1.0.0
        with:
          model: physics_lint_adapter.py

Matrix example (multi-model)

For repositories with multiple model artifacts (e.g., tyy0811/laplace-uq-bench):

jobs:
  lint:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        model:
          - { name: unet, path: models/unet_adapter.py }
          - { name: fno,  path: models/fno_adapter.py }
          - { name: ddpm, path: models/ddpm_pred.npz }
    steps:
      - uses: actions/checkout@v4
      - uses: tyy0811/physics-lint@v1.0.0
        with:
          model: ${{ matrix.model.path }}
          category: physics-lint-${{ matrix.model.name }}
          output: physics-lint-${{ matrix.model.name }}.sarif

Inputs

Input	Required	Default	Notes
model	yes	—	Path to adapter .py or .npz dump
config	no	pyproject.toml	Path to config TOML
category	no	physics-lint	SARIF category for code-scanning distinction
output	no	physics-lint.sarif	SARIF output path
version	no	derived from Action ref	physics-lint PyPI version. See below
python-version	no	3.11	Passed to actions/setup-python
mesh	no	false	When true, installs physics-lint[mesh]
fail-on-error	no	true	When false, the CLI’s non-zero exit on error-severity rules is suppressed
upload-sarif	no	true	When false, skips the github/codeql-action/upload-sarif step

Version pinning

The version input default is derived from github.action_ref:

• If the caller pins a tag (e.g., uses: tyy0811/physics-lint@v1.0.0), the Action installs physics-lint==1.0.0. Tag and install are locked by construction.

• If the caller pins a branch or SHA, the Action falls back to the latest published physics-lint (no determinism is possible without an explicit input).

• Override at any time with with: version: 1.0.1 (or any valid PyPI version specifier).

Permissions

physics-lint does not configure workflow-level permissions itself. The caller must set:

permissions:
  contents: read
  security-events: write

security-events: write is required for the SARIF upload step. Without it, the upload silently fails (or fails with a permissions error, depending on the runner). See security for the full threat model around adapter execution in CI.

Advanced usage

For options not exposed as Action inputs (e.g., disabling specific rules), install and run physics-lint directly instead of using the Action:

- run: |
    pip install 'physics-lint==1.*'
    physics-lint check models/fno.py \
      --disable PH-VAR-002 \
      --format sarif \
      --output physics-lint.sarif

- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: physics-lint.sarif

The Action’s input surface is intentionally small; expansion happens in v2 if real usage justifies it.