⭐ Python Developer · Chặng 10Bài 5/6Bài học~45 phút

CI cho dự án Python với GitHub Actions: Ruff, mypy, pytest

Tự động kiểm tra mỗi lần đẩy code: workflow GitHub Actions cài uv, chạy Ruff, mypy, pytest trên nhiều phiên bản Python bằng matrix.

CI cho dự án Python với GitHub Actions: Ruff, mypy, pytest

Học xong bài này, bạn sẽ

  • Hiểu CI và vì sao mọi dự án cần nó
  • Viết workflow chạy Ruff, mypy, pytest mỗi lần push
  • Chạy test trên nhiều phiên bản Python bằng matrix

Nên học trước: Đóng gói ứng dụng Python bằng Docker

Nội dung bài viết
  1. 1. Workflow đầu tiên
  2. 2. Đọc kết quả, sửa khi đỏ
  3. 3. Ma trận: chạy trên nhiều phiên bản Python
  4. 4. Thêm bước build Docker và badge
  5. Tóm tắt
  6. Bài tập

Bạn có test, có Ruff, có mypy. Nhưng nếu phải nhớ tự chạy chúng trước mỗi lần đẩy code, sớm muộn sẽ có lúc quên, và đồng nghiệp kéo về một nhánh hỏng. CI (Continuous Integration, tích hợp liên tục) là máy chủ tự động chạy toàn bộ kiểm tra mỗi khi có code mới được đẩy lên hoặc có pull request. GitHub Actions có sẵn trong mọi kho GitHub, miễn phí cho kho công khai.

1. Workflow đầu tiên

Tạo file .github/workflows/ci.yml trong dự án (dấu chấm ở đầu tên thư mục):

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  kiem-tra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Cài uv và Python
        uses: astral-sh/setup-uv@v9
        with:
          python-version: "3.14"
          enable-cache: true

      - name: Cài thư viện
        run: uv sync --locked

      - name: Ruff (lint + format)
        run: |
          uv run ruff check .
          uv run ruff format --check .

      - name: mypy
        run: uv run mypy app

      - name: pytest
        run: uv run pytest -q

Commit và push file này lên GitHub, mở tab Actions của kho để xem workflow chạy.

  • on: khi nào chạy. Ở đây: mỗi lần push lên main và mỗi pull request.
  • jobs → kiem-tra: một công việc chạy trên máy ảo Ubuntu sạch (runs-on) do GitHub cấp, xóa sau khi xong.
  • steps: các bước tuần tự. uses dùng một action có sẵn: actions/checkout lấy code về, astral-sh/setup-uv cài uv và Python. run chạy lệnh shell.
  • enable-cache: true lưu cache thư viện giữa các lần chạy, lần sau nhanh hơn.
  • uv sync --locked: lockfile không khớp thì dừng, đúng như máy bạn và Docker. Nhóm dev (pytest, ruff, mypy) được cài vì mặc định uv sync có kèm.
  • Bất kỳ lệnh nào trả mã thoát khác 0 (chặng 7), job dừng và báo đỏ.
Ghim phiên bản action@v7, @v9 là phiên bản chính của action tại thời điểm viết bài. Dự án cần bảo mật cao thường ghim theo mã commit đầy đủ (uses: actions/checkout@<mã SHA> # v7.0.1) như tài liệu của uv, để chắc chắn mã chạy trong CI không bị thay đổi ngầm.

2. Đọc kết quả, sửa khi đỏ

Thử đẩy một thay đổi làm hỏng test (ví dụ đổi mã trạng thái tạo công việc thành 200). Tab Actions hiện dấu ✗ đỏ; bấm vào job, mở bước pytest để xem đúng output như khi chạy trên máy:

FAILED tests/test_cong_viec.py::test_tao_va_giao_viec - AssertionError: {"id":1,"tieu_de":"Viết b...
FAILED tests/test_cong_viec.py::test_ai_thay_viec_nao - AssertionError: {"id":1,"tieu_de":"Việc",...
...
6 failed, 5 passed in 2.37s
Error: Process completed with exit code 1.

Một thay đổi nhỏ làm hỏng 6 test, vì hàm trợ giúp tao() trong test kiểm tra mã 201 và được dùng ở nhiều nơi. Trên pull request, GitHub hiện trạng thái kiểm tra ngay dưới phần mô tả. Vào Settings › Branches, thêm quy tắc bảo vệ nhánh main và bật "Require status checks to pass": không ai gộp được pull request khi CI còn đỏ.

3. Ma trận: chạy trên nhiều phiên bản Python

Thư viện hoặc công cụ cần hỗ trợ nhiều phiên bản Python thì nên test trên tất cả:

jobs:
  kiem-tra:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ["3.13", "3.14"]
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v9
        with:
          python-version: ${{ matrix.python-version }}
          enable-cache: true
      - run: uv sync --locked
      - run: uv run pytest -q

Ma trận 2 hệ điều hành × 2 phiên bản tạo 4 job chạy song song. fail-fast: false để một job lỗi không hủy các job khác, bạn thấy đủ bức tranh. Muốn chạy nhiều phiên bản Python, requires-python trong pyproject.toml phải cho phép các phiên bản đó (ví dụ ">=3.13"). Với ứng dụng web chạy trong Docker, chỉ cần test đúng phiên bản Python của image.

4. Thêm bước build Docker và badge

  docker:
    needs: kiem-tra                  # chỉ chạy khi job kiem-tra đã xanh
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Build image
        run: docker build -t quan-ly-cong-viec:${{ github.sha }} .

Job docker bảo đảm Dockerfile luôn build được. Bước tiếp theo trong thực tế (CD, triển khai liên tục) là đẩy image lên kho image và triển khai lên máy chủ; mỗi nền tảng có cách riêng nên ngoài phạm vi bài này.

Gắn huy hiệu trạng thái vào đầu README.md để ai mở kho cũng thấy dự án đang xanh:

![CI](https://github.com/ten-ban/quan-ly-cong-viec/actions/workflows/ci.yml/badge.svg)
Bí mật trong CIKhông bao giờ ghi khóa, mật khẩu vào file workflow. Đặt chúng trong Settings › Secrets and variables › Actions và dùng qua ${{ secrets.TEN_BI_MAT }}; GitHub tự che giá trị trong log. Test của chặng 9 không cần bí mật thật vì SECRET_KEY có giá trị mặc định cho môi trường phát triển.

Tóm tắt

  • Workflow là file YAML trong .github/workflows/; on chọn sự kiện, jobs → steps với uses và run.
  • Dự án uv: actions/checkout → astral-sh/setup-uv (cache) → uv sync --locked → Ruff, mypy, pytest.
  • Lệnh trả mã khác 0 làm job đỏ; bảo vệ nhánh main bằng status check bắt buộc.
  • strategy.matrix chạy trên nhiều hệ điều hành, phiên bản Python; needs nối các job; bí mật đặt trong Secrets.

Bài tập

Bài 1. CI cho dự án API

Thêm workflow ở mục 1 vào dự án quản lý công việc trên GitHub. Cố tình đẩy một commit làm hỏng test để thấy CI báo đỏ, đọc log tìm test lỗi, sửa và đẩy lại cho xanh.

Xem gợi ý

Làm trên một nhánh riêng và mở pull request: bạn sẽ thấy dấu ✗ ngay trong pull request, đúng như khi làm việc nhóm. Nếu job hỏng ở bước uv sync --locked, bạn quên commit uv.lock hoặc đã sửa pyproject.toml mà chưa chạy uv lock. Nếu Ruff format báo lỗi, chạy uv run ruff format . trên máy rồi commit.

Bài 2. Ma trận và badge

Thêm ma trận chạy test trên Python 3.13 và 3.14, gắn badge trạng thái CI vào README. Kiểm tra trong tab Actions có đủ các job song song.

Xem gợi ý

Dự án dùng enum.StrEnum và datetime.UTC (có từ Python 3.11), nên chạy được cả 3.13 lẫn 3.14; nhớ đặt requires-python = ">=3.13". Thử thêm "3.10" vào ma trận: job đó sẽ đỏ ở bước cài đặt hoặc import. Đó chính là giá trị của ma trận: phát hiện bạn đã vô tình dùng tính năng mới hơn phiên bản tối thiểu đã cam kết.

Nguồn tham khảo: GitHub Actions: Quickstart; Workflow syntax for GitHub Actions; uv: Using uv in GitHub Actions; astral-sh/setup-uv.

Bài tập thực hành

  1. Thêm workflow CI cho dự án API, cố tình đẩy một test sai để thấy CI báo đỏ, rồi sửa.
  2. Thêm matrix chạy trên Python 3.13 và 3.14, gắn badge trạng thái vào README.

Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.