---
url: https://docs.nemo12.com/ops/automerge.md
description: >-
  Gắn nhãn automerge là PR tự gộp khi CI của PR xanh; thay cho Allow auto-merge
  mà repo private gói miễn phí không có. Cần secret AUTOMERGE_TOKEN.
---

# Tự gộp PR khi CI xanh (SRC-1334)

Chủ dự án 11.10.2026: gộp tay sau mỗi lượt CI dài khoảng 20 phút thì `main` thường đã đổi, PR xung đột, phải gỡ
và chạy CI lại. Nút "Allow auto-merge" của GitHub cần luật bảo vệ nhánh, mà repo private gói miễn phí không có
(API trả "Upgrade to GitHub Pro"). Chủ dự án chọn tự dựng thay vì trả tiền.

## Cách dùng

```bash
gh pr edit <số PR> --add-label automerge
```

Workflow `.github/workflows/automerge.yml` chạy mỗi khi workflow `ci` của một PR xong, và khi một PR vừa được gắn
nhãn. PR được gộp (kiểu merge commit) khi đủ bốn điều:

1. PR mở và có nhãn `automerge`.
2. Lượt `ci` mới nhất của **đúng commit đầu PR** xanh. Đẩy commit mới thì phải chờ lượt CI mới.
3. Nếu `main` đã có commit mới **ở cùng vùng code** kể từ lúc CI của PR chạy, workflow cập nhật nhánh PR theo
   `main` (nút "Update branch") và chờ lượt CI mới thay vì gộp (SRC-1341). Đây là phần "hàng đợi gộp" tự dựng:
   hai PR xanh riêng chưa chắc xanh khi gộp chung, nên PR chỉ được gộp khi đã kiểm cùng mọi thay đổi chạm
   vùng của nó. Vùng là thư mục cấp hai (`apps/learn`, `workers/api`...); `packages/`, `migrations/`,
   `.github/` và gốc repo dùng chung nên chồng với mọi vùng code; `docs/` chỉ chồng với `docs/`. `main` đổi ở
   vùng khác thì gộp luôn, nếu không với khoảng 30 commit mỗi ngày hàng đợi sẽ không bao giờ chảy.
4. PR không xung đột. Nếu xung đột, workflow thử gộp `main` vào nhánh PR bằng `git merge` thật ngay trong runner
   (SRC-1343): hai PR cùng chèn dòng vào đuôi một mảnh sổ chung là xung đột với nút gộp của GitHub, nhưng git
   gỡ được nhờ `merge=union` trong `.gitattributes` (nút của GitHub không đọc luật đó). Gộp sạch thì đẩy lên,
   CI chạy lại, lượt sau tự gộp. Xung đột thật trong code thì workflow để lại bình luận kèm tên file. Xung đột thì workflow để lại bình luận và không gộp; gỡ tay rồi đẩy lại, nhãn vẫn còn.

Sau khi gộp, CI của `main` chạy lại toàn bộ cổng và chỉ deploy khi xanh, như với PR gộp tay.

## Vì sao cần AUTOMERGE_TOKEN

Gộp bằng `GITHUB_TOKEN` mặc định thì GitHub **không** phát sự kiện `push` vào `main`, nên `ci.yml` không chạy và
không deploy (deploy chỉ chạy trên `push`; một lượt `workflow_dispatch` không deploy). Vì vậy workflow gộp bằng
token cá nhân của chủ dự án, cất trong secret `AUTOMERGE_TOKEN`. Thiếu secret thì workflow đỏ và nói rõ, không gộp.

Tạo token (chủ dự án làm, một lần): GitHub → Settings → Developer settings → Fine-grained tokens → Generate:
chỉ repository `dac2205/nemo12.com`, quyền **Contents: Read and write** và **Pull requests: Read and write**.
Rồi repo → Settings → Secrets and variables → Actions → New repository secret, tên `AUTOMERGE_TOKEN`.
Token hết hạn thì workflow đỏ với cùng thông báo; tạo token mới và thay secret.