GitHub Actions Integration

pycmdcheck integrates seamlessly with GitHub Actions to provide automated package quality checks with inline annotations directly in your pull requests.

Quick Start

Add pycmdcheck to your CI workflow:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install dependencies
        run: pip install pycmdcheck
      - name: Run pycmdcheck
        run: pycmdcheck check --format github --profile ci

GitHub Format Output

The --format github flag produces GitHub Actions workflow commands that create inline annotations in your pull requests.

When pycmdcheck finds issues, they appear directly on the affected files:

Errors appear as red annotations
Warnings appear as yellow annotations
Notes appear as blue annotations

This makes it easy to see exactly where issues are located without digging through log output.

Example Output

::error file=src/mypackage/__init__.py,line=1::ST001: Package missing py.typed marker for type checking support
::warning file=pyproject.toml,line=15::MT003: Missing optional metadata field 'keywords'
::notice file=tests/test_main.py,line=42::TS001: Test coverage below recommended threshold

Using Profiles

pycmdcheck includes built-in profiles optimized for different use cases:

Profile	Description	Use Case
`ci`	Skips slow checks (e.g., vulnerability scans), fails on warnings	Continuous integration pipelines
`release`	Focuses on structure, metadata, release, and security checks	Pre-release validation
`strict`	Runs all checks, fails on any issue including notes	Comprehensive quality gate
`relaxed`	Skips informational checks, fails only on errors	Initial adoption / legacy projects

CI Profile

Best for pull request checks. Optimized for speed by skipping slow vulnerability scans:

- name: Run pycmdcheck
  run: pycmdcheck check --format github --profile ci

Release Profile

Use before publishing a new version. Focuses on release-critical checks:

- name: Run pycmdcheck (release)
  run: pycmdcheck check --format github --profile release --error-on warning

Strict Profile

For projects that want comprehensive quality enforcement:

- name: Run pycmdcheck (strict)
  run: pycmdcheck check --format github --profile strict

Relaxed Profile

Good for gradually adopting pycmdcheck in existing projects:

- name: Run pycmdcheck (relaxed)
  run: pycmdcheck check --format github --profile relaxed

Controlling Exit Codes

The --error-on flag controls which severity level causes a non-zero exit code:

Flag	Behavior
`--error-on error`	Exit non-zero only on errors (default)
`--error-on warning`	Exit non-zero on warnings or errors
`--error-on note`	Exit non-zero on any issue

# Fail the build on warnings
- name: Run pycmdcheck
  run: pycmdcheck check --format github --error-on warning

Matrix Testing Multiple Python Versions

Test your package across multiple Python versions:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
        run: pip install pycmdcheck
      - name: Run pycmdcheck
        run: pycmdcheck check --format github --profile ci

Release Workflow

Run comprehensive checks before publishing releases:

name: Release Check

on:
  push:
    tags: ["v*"]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install dependencies
        run: pip install pycmdcheck
      - name: Run pycmdcheck (release profile)
        run: pycmdcheck check --format github --profile release --error-on warning

Using a Reusable Workflow

For more convenience, you can create a reusable workflow in your organization:

# .github/workflows/pycmdcheck.yml
name: pycmdcheck

on:
  workflow_call:
    inputs:
      python-version:
        type: string
        default: "3.12"
      error-on:
        type: string
        default: "warning"

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ inputs.python-version }}
      - run: pip install pycmdcheck
      - run: pycmdcheck check --format github --error-on ${{ inputs.error-on }}

Then use it in other workflows:

- name: Run pycmdcheck
  uses: ./.github/workflows/pycmdcheck.yml
  with:
    python-version: "3.12"
    error-on: warning

See the pycmdcheck repository for more examples.

Skipping Specific Checks

Skip checks that don’t apply to your project:

- name: Run pycmdcheck
  run: pycmdcheck check --format github --skip ST001 --skip DC002

Or skip entire groups:

- name: Run pycmdcheck
  run: pycmdcheck check --format github --skip-group tests --skip-group docs

Running Only Specific Checks

Focus on specific checks or groups:

# Only run metadata and structure checks
- name: Run pycmdcheck
  run: pycmdcheck check --format github --only-group metadata --only-group structure

Combining with Other Tools

pycmdcheck works well alongside other quality tools:

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install pycmdcheck ruff mypy pytest

      - name: Lint with ruff
        run: ruff check .

      - name: Type check with mypy
        run: mypy src

      - name: Test with pytest
        run: pytest

      - name: Package check with pycmdcheck
        run: pycmdcheck check --format github --profile ci

Caching Dependencies

Speed up your workflow by caching pip dependencies:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
      - name: Install dependencies
        run: pip install pycmdcheck
      - name: Run pycmdcheck
        run: pycmdcheck check --format github --profile ci

Troubleshooting

Annotations Not Appearing

Make sure you’re using --format github. Without this flag, pycmdcheck outputs human-readable text instead of workflow commands.

Too Many Annotations

GitHub limits the number of annotations per check run. If you have many issues, consider: 1. Using --error-on error to focus on critical issues first 2. Using profiles to limit which checks run 3. Fixing issues incrementally

Slow Checks

Use the ci profile to skip slow checks like vulnerability scanning:

run: pycmdcheck check --format github --profile ci