Git describe: Gắn nhãn phiên bản để truy vết bản build

Khi người dùng báo lỗi, câu hỏi đầu tiên thường là: hệ thống đang chạy bản nào? Tên file như app-final.zip hoặc nhãn latest không đủ để lần về mã nguồn. Git describe cung cấp một nhãn dễ đọc cho commit, nhưng để truy vết bản build đáng tin cậy, nhóm vẫn cần lưu commit đầy đủ và thông tin artifact.

1. Đọc nhãn mà không suy diễn quá mức

git describe --tags --long --always

Ví dụ minh họa: v2.3.0-5-gabc1234. Đây là tag được chọn, số commit bổ sung so với tag và mã commit rút gọn có tiền tố g. Không diễn giải số 5 thành năm lần triển khai hoặc năm thay đổi tính năng. Lịch sử có merge cũng không nhất thiết là một chuỗi thẳng.

Theo tài liệu Git describe, mặc định chỉ xét annotated tag; --tags cho phép cả lightweight tag, --long giữ dạng dài kể cả khi trùng tag, còn --always cho phép dùng hash rút gọn khi không tìm được tag phù hợp.

Nhãn này phục vụ quan sát. Không tự lấy nó làm phiên bản package: quy tắc sắp xếp phiên bản của registry hoặc công cụ triển khai cần được thiết kế riêng.

2. Lưu cả nhãn và commit đầy đủ

git describe --tags --long --always
git rev-parse --verify "HEAD^{commit}"
git status --porcelain=v1 --untracked-files=all

Lệnh thứ hai lấy danh tính commit; lệnh thứ ba cung cấp trạng thái dễ xử lý bằng script, gồm cả file chưa được theo dõi. Tài liệu rev-parse và status giải thích các tùy chọn này. Không hardcode độ dài hash trong hệ thống lưu metadata.

Đề xuất metadata của nhóm gồm năm trường: nhãn dễ đọc, commit đầy đủ, mã lần chạy CI, checksum hoặc digest artifact và thời điểm build. Nhãn giúp con người trao đổi; digest giúp đối chiếu đúng sản phẩm đã triển khai. Hai build từ cùng commit vẫn có thể khác nhau nếu dependency, công cụ hoặc biến môi trường thay đổi.

3. Phân biệt build thử và release chính thức

Với máy phát triển, có thể thêm dấu cảnh báo sửa đổi:

git describe --tags --long --always --dirty

Đừng coi việc không có hậu tố dirty là chứng nhận đầu vào sạch: file untracked hoặc ignored có thể ảnh hưởng quá trình build. Kiểm tra status riêng; với file bị ignore, quy định rõ build được phép đọc những đầu vào nào. Không tự động xóa file của lập trình viên để đạt điều kiện sạch.

Với release, nên đặt chính sách rõ ràng: build từ checkout cô lập, kiểm tra tag được phép, khóa dependency và lưu metadata trước khi chạy bước tạo file. Nếu công cụ build sinh file vào working tree rồi mới tính nhãn, nhãn có thể phản ánh tác dụng phụ của build thay vì trạng thái đầu vào ban đầu.

4. Giới hạn tag theo quy ước

git describe --tags --match "v[0-9]*" --long --always
git describe --tags --match "v[0-9]*" --exact-match HEAD

--match lọc theo glob, không phải biểu thức kiểm tra SemVer. --exact-match chỉ chấp nhận tag trỏ đúng commit; khi không có, lệnh thất bại. Trong bước kiểm tra release, không thêm fallback để biến điều kiện không đạt thành thành công.

Việc tìm thấy tag không xác minh người tạo, chữ ký hoặc quyền phát hành. Những điều đó thuộc kiểm soát release riêng. Nếu repository có nhiều sản phẩm, nhóm cần thống nhất namespace tag và cách chọn tag cho từng sản phẩm trước khi dùng nhãn trong thông báo triển khai.

5. Khi CI cho kết quả khác máy local

git rev-parse --is-shallow-repository
git tag --list "v*"
git rev-parse HEAD

Đầu tiên đối chiếu commit, sau đó kiểm tra lịch sử và tag hiện có trong checkout. Một clone nông hoặc thiếu tag là tín hiệu cần kiểm tra cấu hình checkout CI, không phải lý do sửa tag của repository. Việc tải thêm tag cũng không mặc nhiên cung cấp đủ mọi đoạn lịch sử cần duyệt.

Chọn chính sách lấy lịch sử phù hợp với dự án, rồi thử lại trên chính runner. Nếu chỉ cần danh tính chính xác, luôn lưu commit đầy đủ ngay cả khi nhãn chỉ còn hash. Nếu release yêu cầu tag, dừng pipeline với thông báo rõ ràng khi điều kiện chưa đáp ứng.

6. Đưa metadata đến nơi hỗ trợ cần

• Ghi metadata vào manifest nằm cùng artifact, không chỉ trong log CI có thể hết hạn.
• Hiển thị nhãn trong trang thông tin hoặc log khởi động; hạn chế công khai dữ liệu nội bộ không cần thiết.
• Ghi digest thực tế vào hồ sơ triển khai để phân biệt các artifact cùng commit.
• Thử quy trình hỗ trợ: từ một nhãn được báo, tìm đúng job CI, artifact và commit.

Checklist trước khi áp dụng gồm: có tag, không có tag, đúng tại tag, có sửa đổi tracked và có file untracked. Kết quả cần dễ hiểu trong mọi trường hợp, không chỉ trong repository của người viết script. Git describe hữu ích nhất khi là một phần của hồ sơ build, không phải nguồn thông tin duy nhất.