GitHub Actions

Prose runs on the standard ubuntu-latest runner. The install step downloads the wheel through uv, the check step runs prose check, and the exit code decides whether the job passes. The three jobs below differ in how much they show on the PR: a bare check, annotations inline on the diff, or a SARIF upload to Code Scanning.

Job Skeleton

Every job below plugs its prose check step into the same skeleton, which checks out the repository, installs uv, and installs the wheel:

name: prose

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - run: uv tool install prose-formatter
      - run: prose check .

actions/checkout puts the source on the runner, astral-sh/setup-uv installs uv and keeps its download cache between runs, and the last two steps install Prose and run the check. Each job below replaces the final run line.

Minimal Check

The minimal job fails the workflow on any pending rewrite or lint finding and shows nothing on the PR beyond the pass or fail badge. The Exit Codes reference lists which exits count as failure:

- run: prose check .

Workflow Command Annotations

The github output format prints one workflow command per finding, which GitHub renders as an annotation on the PR diff beside the line it concerns:

- run: prose check --output-format github .

The Output Formats reference covers the record format, and the CLI Reference covers --output-format and its default.

SARIF Upload

The sarif output format writes findings to a file that a second step uploads through GitHub's CodeQL action, so they persist across runs and appear in the repository's Security tab under Code Scanning:

- run: prose check --output-format sarif . > prose.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: prose.sarif

Each SARIF record carries the rule slug and the source location, so the Security tab keeps a history per rule. The Output Formats reference lists the fields of each record.

Persisting the Cache

Every run uses the per-user cache by default, but a runner's filesystem is discarded after each job. actions/cache keeps ~/.cache/prose between runs, so a file that has not changed costs a stat, a hash, and a deserialize instead of a full format:

- uses: actions/cache@v4
  with:
    path: ~/.cache/prose
    key: prose-${{ runner.os }}-${{ hashFiles('prose.toml', '.config/prose.toml', 'pyproject.toml') }}
- run: prose check .

The key changes whenever a config file changes, so a configuration edit starts from an empty cache. A macOS runner uses ~/Library/Caches/prose and a Windows runner %LOCALAPPDATA%\prose\cache, both listed on the cache page.

Pairing With Ruff in CI

A project that runs Ruff too runs both tools as check steps, each failing the job on a pending rewrite without writing to the runner's disk:

- run: uv tool install ruff
- run: uv tool install prose-formatter
- run: ruff format --check .
- run: prose check .

The Ruff integration page covers the pycodestyle codes to turn off in Ruff's linter and why Ruff's step comes first.

Exit Codes

A CI job reads the same Exit Codes the CLI documents. Any non-zero exit fails the step unless continue-on-error is set, so a single prose check step is a complete gate.

The Pre-Commit page covers running Prose at the commit boundary as well, and the Ruff page covers running Ruff alongside it.