Your First Real Workflow

~14 min · walkthrough, starter, python

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

From zero to a green Python CI

This lesson builds a complete first workflow you'd actually keep. The project is a small Python package with pytest and ruff. The goal is to lint, type-check, and test on every PR and on main.

Repo layout

pyproject.toml — pinning Python version + ruff + pytest + mypy.
src/mypkg/
tests/
.github/workflows/ci.yml — what we'll write.

What the workflow does

Trigger on PR + push to main + manual dispatch.
Single job quality-checks on ubuntu-latest.
Checkout, set up Python 3.12, install deps with cache, lint, type-check, test.
Cancel in-progress runs on the same PR.

Read the workflow below as one document. Notice: every line earns its place. Nothing is decorative.

Code

.github/workflows/ci.yml — full·yaml

name: ci
run-name: ci on ${{ github.actor }} / ${{ github.head_ref || github.ref_name }}

on:
  pull_request: {}
  push:
    branches: [main]
  workflow_dispatch: {}

permissions: read-all

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  quality-checks:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: pip

      - name: Install
        run: |
          python -m pip install --upgrade pip
          pip install -e '.[dev]'

      - name: Lint
        run: ruff check .

      - name: Format check
        run: ruff format --check .

      - name: Type check
        run: mypy src

      - name: Test
        run: pytest -q --cov=src --cov-report=term-missing

External links

Exercise

Drop this workflow into a Python repo of yours, adjust the install / test commands to match the project, and push. Watch the run in the Actions tab. If anything is red, the fix belongs in your project (not the workflow), and that's the whole point.