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.
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
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ênmainvà 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ự.usesdùng một action có sẵn:actions/checkoutlấy code về,astral-sh/setup-uvcài uv và Python.runchạy lệnh shell.enable-cache: truelư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 địnhuv synccó 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 đỏ.
@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:

${{ 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/;onchọn sự kiện,jobs→stepsvớiusesvà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
mainbằng status check bắt buộc. strategy.matrixchạy trên nhiều hệ điều hành, phiên bản Python;needsnố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
- 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.
- 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.


