How to use ty in CI

Run ty against the same installed dependencies locally and in CI. A checker launched in isolation still needs the project’s environment to resolve third-party imports.

Lock the checker with the project

This recipe assumes a project managed by uv, with Python source in src/. Add ty and commit both pyproject.toml and uv.lock:

uv add --dev ty
uv run ty check src/

The --dev flag marks ty as a development dependencyA package needed during development (testing, linting, formatting) that is not shipped to users of your project. Installed with the --dev flag. , keeping it out of production installs. uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. A clean check prints All checks passed!.

The lockfile pins the checker version. Upgrade ty in a separate change so diagnostic changes are reviewed with the dependency update.

Add GitHub Actions annotations

name: Type check
on: [push, pull_request]
jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
      - uses: astral-sh/setup-uv@v10.3.3
      - run: uv sync --locked
      - run: uv run --locked ty check src/ --output-format github

uv sync --locked creates the environment from the committed lockfile, including development dependencies. The github format emits workflow annotations associated with diagnostic file locations.

Upload a GitLab Code Quality report

Use a runner image with uv and Python installed. The following job installs the locked environment and publishes ty’s JSON output as a Code Quality artifact:

type-check:
  image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
  script:
    - uv sync --locked
    - uv run --locked ty check src/ --output-format gitlab > ty-code-quality.json
  artifacts:
    when: always
    reports:
      codequality: ty-code-quality.json

The artifact is uploaded even when diagnostics fail the job. Match the image’s Python version to the project’s supported version.

Choose the report format and failure policy

ty exits 0 when the check is clean, 1 for warning or error diagnostics, and 2 for fatal setup errors or invalid invocation. To allow warnings while retaining failures on errors, use --exit-zero-on-warning or commit:

[tool.ty.terminal]
error-on-warning = false

--exit-zero also permits errors, so reserve it for an explicitly advisory trial. For required CI checks, preserve ty’s exit status and avoid shell constructs that hide failures.