Zero-Barrier: Tự động hóa CI/CD GitHub Actions cho Zola

Mục lục (thu gọn)

Trong hầu hết quy trình xuất bản nội dung, con người vẫn là nút cổ chai. Bạn viết xong bài, mở Pull Request, rồi chờ ai đó bấm "Approve", chờ CI, chờ merge, chờ deploy. Với một hệ thống chạy hàng chục thay đổi mỗi ngày, chuỗi chờ đợi đó giết chết tốc độ. Bài viết này mổ xẻ cách mình xây dựng mô hình Zero-Barrier Automation trên nền Zola SSG: một pipeline nơi Pull Request tự kiểm tra, tự sửa lỗi an toàn, tự merge và tự deploy mà không cần một cú click phê duyệt nào của con người — nhưng vẫn giữ production sạch. Nói cách khác, đây là một hướng dẫn tự động hóa CI/CD GitHub Actions ở mức triệt để nhất: kéo dài chuỗi tự động từ khâu kiểm thử, qua merge, tới deploy production.

Zero-Barrier Automation là gì

Zero-Barrier không có nghĩa là "không có rào chắn". Nó có nghĩa là dịch chuyển rào chắn từ con người sang code. Thay vì một reviewer đọc diff rồi phán "ổn", ta để một bộ kiểm tra xác định trước quyết định thay. Triết lý vận hành gói gọn trong một vòng lặp:

Bug found → Fix it → Learn from it → Auto-healing, với pipeline Detect → Classify → Heal → Build → Merge → Deploy.

Điểm mấu chốt là phân loại mức độ nghiêm trọng. Không phải lỗi nào cũng được quyền chặn deploy:

• P0 (build vỡ, TOML frontmatter invalid, conflict marker sót, workflow YAML hỏng, secret commit): fail CI ngay.
• P1: thử auto-heal trước, chỉ fail nếu không tự sửa được.
• P2/P3 (cảnh báo SEO, PageSpeed, external link): chỉ report, không bao giờ block merge.

Nếu ta để mọi cảnh báo nhỏ đều chặn merge, hệ thống sẽ tê liệt. QA ở đây đóng vai hệ miễn dịch của deployment, không phải cảnh sát chặn cửa. Bạn có thể theo dõi sức khỏe pipeline này realtime trên trang /insights/, còn lịch sử từng lần merge/deploy nằm ở /changelog/.

Tự động hóa CI/CD GitHub Actions: kiến trúc tổng thể

Toàn bộ luồng đi qua bốn tầng, mỗi tầng là một cổng kiểm soát độc lập:

1. Local gate — qa_check.py --scope chạy trước khi commit, phân tích git diff.
2. CI gate — GitHub Actions chạy lại QA đầy đủ + zola build trên môi trường sạch.
3. Merge gate — auto-merge.yml squash-merge khi và chỉ khi CI xanh.
4. Deploy gate — deploy.yml + deploy-guard.yml đảm bảo commit mới nhất thực sự lên GitHub Pages.

Điểm quan trọng nhất về mặt kỹ thuật: CI luôn kiểm tra toàn bộ repository chứ không chỉ diff. Một PR chỉ sửa docs vẫn có thể fail nếu branch cắt từ main cũ đang chứa bug đã được fix ở nơi khác. Vì thế bước rebase lên main mới nhất là bắt buộc, không phải tùy chọn.

Bước 1 — QA cục bộ với scoped build

Sai lầm phổ biến của người mới là mỗi lần sửa một chữ cũng chạy full zola build mất vài chục giây. Với static site hàng trăm bài, điều đó lãng phí khủng khiếp. Giải pháp là scoped build: phân tích git diff để quyết định thực sự cần build gì.

import subprocess  # trích từ qa_check.py, rút gọn logic classify_scope()

def scope_from_git_diff():
    """Xác định phạm vi ảnh hưởng từ diff so với origin/main."""
    out = subprocess.run(
        ["git", "diff", "--name-only", "origin/main...HEAD"],
        capture_output=True, text=True,
    ).stdout.splitlines()
    return classify_scope(out)

def classify_scope(files):
    scopes = set()
    for f in files:
        if f.startswith("content/") and f.endswith(".md"):
            scopes.add("content")     # chỉ cần QA + check link, KHÔNG cần zola build
        elif f.startswith("templates/") and f.endswith(".html"):
            scopes.add("template")    # cần full build
        elif f.startswith("sass/"):
            scopes.add("style")       # cần full build
        elif f in ("config.toml",) or f.startswith(".github/workflows/"):
            scopes.add("config_global")  # bắt buộc full build
        elif f.startswith("data/") and f.endswith(".json"):
            scopes.add("data")        # thường không cần build
    return scopes

def needs_full_build(scopes):
    return bool(scopes & {"template", "style", "config_global"})

Nhờ đó một PR content thuần chỉ cần chạy qa_check.py + check_internal_links.py, bỏ qua zola build local — CI đằng nào cũng build lại đầy đủ trước khi merge production. Kết quả điểm chất lượng từng bài được lưu và hiển thị công khai ở /seo-bang-vang/, còn thống kê tổng quan crawl-depth nằm trong khu /stats/.

Bên cạnh scope, qa_check.py còn quét các "chất độc" khiến build vỡ mà mắt thường khó thấy: FAQ dùng sai field, conflict marker <<<<<<< còn sót, heading <h1> trùng, hay category đặt sai cấp ngoài [taxonomies].

Bước 2 — Cổng CI với QA Gatekeeper

Local gate có thể bị bỏ qua (ai đó commit vội), nên CI mới là nguồn sự thật. Đây là workflow rút gọn cho cổng QA. Lưu ý nó chạy trên push của branch thay vì pull_request — cách này né được vụ "workflows awaiting approval" khi dùng GITHUB_TOKEN mặc định.

name: QA Gatekeeper   # .github/workflows/qa.yml (rút gọn)
on:
  push:
    branches-ignore: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  qa-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # cần full history để diff origin/main

      - name: Setup Python
        uses: actions/setup-python@v5
        with: { python-version: "3.11" }

      - name: Validate workflow YAML (P0 gate)
        run: python3 scripts/validate_workflows.py

      - name: Scoped QA
        run: python3 qa_check.py --scope

      - name: Build references
        run: python3 scripts/build_references.py

      - name: Zola build
        uses: shalzz/zola-deploy-action@master
        env:
          BUILD_ONLY: true

      - name: Internal link gate (P0)
        run: python3 scripts/check_internal_links.py

Bước validate_workflows.py là bài học từ một sự cố thật: một file YAML hỏng cú pháp lọt lên main khiến mọi PR hiện dấu đỏ, dù PR đó hoàn toàn sạch. Vì workflow không parse được nên GitHub không bao giờ chạy job, và qa_check.py (chỉ dùng stdlib, không parse YAML) không bắt được. Từ đó, validate YAML trở thành một P0 gate cứng đứng trước mọi bước tốn thời gian.

Bước 3 — Auto-merge khi CI xanh

Đây là trái tim của Zero-Barrier. Khi cổng QA báo xanh, không có con người nào bấm nút — một workflow đảm nhận việc merge.

name: Auto Merge   # .github/workflows/auto-merge.yml (rút gọn)
on:
  workflow_run:
    workflows: ["QA Gatekeeper"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  automerge:
    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Enable auto-merge for the open PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          BRANCH="${{ github.event.workflow_run.head_branch }}"
          PR=$(gh pr list --head "$BRANCH" --json number -q '.[0].number')
          if [ -n "$PR" ]; then
            gh pr merge "$PR" --squash --auto --delete-branch
          else
            echo "Không có PR mở cho branch $BRANCH — bỏ qua."
          fi

Cấu hình repo đi kèm rất quan trọng để mô hình này chạy:

• Branch protection cho main: Required approvals = 0, chỉ giữ đúng required check qa-check.
• Workflow permissions: Read and write, cho phép Actions tạo/merge PR.
• Không dùng lại bất kỳ job kiểu manual-approval nào — chúng tạo ra "chữ ký giả" chặn tự động hóa.

Một cạm bẫy tinh vi mình từng dính: nếu bạn push thêm commit fix trong lúc CI của commit trước đang chạy, --auto có thể chốt snapshot ở commit cũ. Bài học là khi cần verify trạng thái một SHA cụ thể, hãy tra gh api repos/{owner}/{repo}/commits/{SHA}/check-runs theo đúng SHA, đừng tra theo tên workflow chung chung.

Bước 4 — "Merged is not live"

Câu thần chú của mọi hệ thống static tự động hóa: merge không phải là live. Một PR merged vào main mới chỉ ghi vào Git. GitHub Pages cần một lần deploy.yml chạy thành công nữa, và bước này rất dễ thất bại thầm lặng vì rate limit API hoặc concurrency hủy run.

concurrency:            # deploy.yml — chống hủy deploy do batch merge
  group: pages
  cancel-in-progress: false   # xếp hàng deploy thay vì hủy → commit mới nhất luôn tới đích

Kèm theo đó là một deploy-guard.yml chạy theo giờ, so HEAD của main với commit đang live; nếu lệch thì tự dispatch lại deploy.yml. Nguyên tắc nghiệm thu cuối cùng cho mọi route mới:

test -f public/<route>/index.html                 # build đã sinh file (điều kiện 1)
curl -I https://seomoney.org/<route>/ | head -1    # phải trả HTTP/2 200

Nếu bạn chỉ dựa vào "PR đã merged" để báo cáo done, sớm muộn cũng có route trả 404 trong khi bạn tưởng nó đã sống.

Xử lý xung đột và tự chữa lành

Khi nhiều PR merge gần nhau, xung đột gần như luôn xảy ra ở các file CI tự sinh — điển hình là data/references.json hay data/seo-qa-scores.json do hook chấm điểm cập nhật timestamp. Đây là merge race, không phải xung đột logic. Chiến lược cố định:

git checkout --theirs data/seo-qa-scores.json   # file auto-generated: lấy bản main
python3 scripts/build_references.py       # sinh lại cho khớp state mới
git add data/

Ngược lại, với registry dùng chung (khối elif của series, hay categories.json) thì phải giữ cả hai bên — append mọi entry, không được chọn một phía kẻo mất dữ liệu của PR khác. Một validator định kỳ có thể tự động rebase các PR dirty, regenerate file sinh, rồi git push --force-with-lease an toàn để cả hệ thống tự lành mà không cần bạn can thiệp.

Những cạm bẫy thực chiến khi bỏ human review

Tự động hóa toàn phần không phải bữa trưa miễn phí. Vài bài học đắt giá:

• Bot observer không được tự đỏ. Mọi workflow chỉ báo cáo (perf-audit, compliance, remediation) phải bọc continue-on-error: true. Nếu chúng exit khác 0, chúng sẽ tự tạo nhiễu và có khi tự trigger lại thành vòng lặp.
• Gate tự tham chiếu là cái bẫy. Một job status-check từng đếm chính conclusion của nó làm "issue", nên một khi đỏ là đỏ mãi. Luôn loại trừ tên check của chính workflow đó khỏi vòng phát hiện lỗi.
• gh run rerun --failed -R <repo> không kèm run id là bom hẹn giờ. Nó rerun mọi run failed toàn repo, kích hoạt cascade qua các trigger workflow_run. Luôn scope theo đúng run id.
• Conflict-free PR khác build-safe PR. Một file FAQ sai field đã nằm trên main sẽ chặn build của mọi PR khác cho tới khi được sửa. Đừng tin dấu xanh mù quáng.

Cấu hình repo và tài liệu nền tảng cần nắm

Trước khi copy các workflow ở trên vào dự án của bạn, có vài điểm cấu hình trên chính GitHub cần bật đúng, nếu không toàn bộ pipeline sẽ "chạy nhưng không merge". Đây là phần mà rất nhiều người bỏ qua rồi ngồi debug hàng giờ.

Thứ nhất là branch protection. Bạn vào Settings → Branches, tạo rule cho main với Required approvals đặt về 0 và chỉ tick đúng một status check bắt buộc là qa-check. Cơ chế này được mô tả kỹ trong tài liệu branch protection của GitHub. Đừng để required check trỏ vào một job có thể không bao giờ chạy (ví dụ job chỉ trigger trên pull_request trong khi CI của bạn chạy trên push) — PR sẽ kẹt vĩnh viễn ở trạng thái "Expected — Waiting for status".

Thứ hai là quyền của Actions. Vào Settings → Actions → General, kéo xuống Workflow permissions và chọn "Read and write permissions", đồng thời tick "Allow GitHub Actions to create and approve pull requests". Nếu thiếu quyền này, lệnh gh pr merge --auto sẽ báo lỗi quyền và job auto-merge đỏ dù CI nội dung xanh. Chi tiết các trigger sự kiện và cách workflow_run nối chuỗi giữa các workflow nằm trong tài liệu chính thức về sự kiện của GitHub Actions.

Thứ ba, hãy tắt hẳn Dependabot auto-update nếu bạn muốn kiểm soát dependency thủ công. Một bản bump action ngoài ý muốn (ví dụ đổi API giữa các major version) có thể phá cú pháp workflow và, do CI kiểm tra toàn repo, kéo đỏ mọi PR khác đang mở. Với mô hình không có người duyệt, một thay đổi âm thầm như vậy đặc biệt nguy hiểm vì không ai chặn nó lại trước khi nó lên main.

Kết luận

Zero-Barrier Automation không phải là "vứt bỏ chất lượng để đổi lấy tốc độ". Nó là mã hóa tiêu chuẩn chất lượng thành code để máy thực thi nhất quán 24/7, nhanh và không mệt mỏi như con người. Với một blog static-first như SEOMONEY, nơi rủi ro phá production thấp và tần suất thay đổi cao, đây là mô hình vận hành gần như tối ưu: bạn viết, hệ thống lo phần còn lại từ kiểm tra tới deploy.

Nếu bạn muốn bắt đầu, hãy triển khai theo đúng thứ tự bốn tầng ở trên — đừng bật auto-merge trước khi cổng QA đủ chặt. Xem thêm điểm chất lượng từng bài đang chạy trên /seo-bang-vang/ và tình trạng vận hành pipeline realtime tại /insights/, rồi bắt tay dựng cổng CI đầu tiên của riêng bạn.