Azure Pipelines: version lấy từ git tag, chia stage, và nút phê duyệt trước production
Tester hỏi: "Bản add-in đang chạy trên production là bản nào?". Mình mở Azure DevOps, thấy danh sách các lần chạy pipeline tên 20260417.3, 20260417.4, 20260421.1. Không cái tên nào nói gì về phiên bản phần mềm. Phải mở từng lần chạy, xem commit, đối chiếu với release note.
Mình sửa pipeline build add-in Outlook để mỗi lần chạy mang đúng số phiên bản lấy từ git tag, artifact nằm trong thư mục cùng số đó, và bước lên production phải qua một nút phê duyệt. Bài này đi qua pipeline đó, cùng ba chỗ mình viết chưa đúng mà phải đọc lại tài liệu mới thấy.
Bức tranh trước: stage, job, step
Pipeline Azure có ba tầng. Hiểu tầng nào làm gì thì đọc YAML dễ hơn nhiều:
Pipeline
└── Stage: "Build" ← một giai đoạn lớn, có thể chờ phê duyệt trước khi vào
├── Job: GetVersion ← chạy trên MỘT máy agent, các job khác máy khác
│ └── Step: git describe ← từng lệnh, chạy tuần tự trên cùng máy
└── Job: Build (dependsOn GetVersion)
├── Step: pnpm install
├── Step: pnpm build
└── Step: publish artifact
└── Stage: "DeployProd" ← chỉ chạy khi Build xong VÀ có người bấm duyệt
└── Deployment job ← job đặc biệt gắn với một Environment
Hai job khác nhau có thể chạy trên hai máy khác nhau, nên chúng không chia sẻ file hay biến với nhau. Muốn truyền một giá trị (như số phiên bản) từ job này sang job kia, phải dùng output variable. Đó là phần đầu của pipeline.
Lấy version từ tag và đổi tên lần chạy
Quy ước của team: mỗi lần release, gắn tag dạng addin-prod-1.8.2 lên commit. Job đầu tiên đọc tag gần nhất khớp mẫu đó:
- job: GetVersion
steps:
- checkout: self
fetchDepth: 0 # lấy đủ lịch sử, git describe mới tìm được tag
fetchTags: true
- bash: |
latestTag=$(git describe --tags --match "$(tagPrefix)-*" --abbrev=0 2>/dev/null || echo "")
if [ -z "$latestTag" ]; then
echo "##vso[task.logissue type=error]Không tìm thấy tag khớp $(tagPrefix)-*"
exit 1
fi
version=${latestTag#$(tagPrefix)-}
echo "##vso[task.setvariable variable=Version;isoutput=true]$version"
echo "##vso[build.updatebuildnumber]$version"
name: ExtractVersion
Những dòng bắt đầu bằng ##vso[...] là cách script nói chuyện với Azure Pipelines qua stdout (logging commands):
| Lệnh | Làm gì |
|---|---|
##vso[task.setvariable variable=Version;isoutput=true]1.8.2 |
Đặt biến Version, và cho job khác đọc được |
##vso[build.updatebuildnumber]1.8.2 |
Đổi tên lần chạy từ 20260421.1 thành 1.8.2 |
##vso[task.logissue type=error]... |
Hiện dòng lỗi đỏ trong trang kết quả |
Giờ danh sách lần chạy hiện 1.8.2, 1.8.3. Câu hỏi của tester trả lời trong một giây.
Chỗ chưa đúng thứ nhất: không có tag thì im lặng dùng số build
Bản đầu của mình xử lý trường hợp không tìm thấy tag bằng cách lặng lẽ dùng số build làm version. Nghe an toàn, nhưng ghép với một chi tiết khác thì thành bẫy: ở nhiều organization, pipeline tạo mới từ cuối năm 2022 mặc định bật shallow fetch với độ sâu 1, tức chỉ lấy commit mới nhất. Không có lịch sử thì git describe có thể không thấy tag nào, và pipeline vui vẻ ra bản tên 20260421.1 mà không ai để ý.
Sửa hai chỗ: fetchDepth: 0 cùng fetchTags: true ở bước checkout, và không có tag thì dừng pipeline thay vì đoán. Một bản release không có số phiên bản đáng để dừng lại hỏi.
Truyền version sang job khác
- job: Build
dependsOn: GetVersion
variables:
Version: $[ dependencies.GetVersion.outputs['ExtractVersion.Version'] ]
steps:
- bash: echo "Đang build bản $(Version)"
Đọc từ trái sang: trong các job mà job này phụ thuộc (dependencies), lấy job GetVersion, output của step tên ExtractVersion, biến Version. Ba thứ phải khớp: name: của step, tên biến trong setvariable, và isoutput=true. Sai một cái là biến rỗng, không có lỗi gì.
Cú pháp $[ ... ] là runtime expression: được tính lúc job chuẩn bị chạy, khi job trước đã xong và có output. Bài sau trong series sẽ đặt nó cạnh hai cú pháp biến còn lại.
Build, và chỗ chưa đúng thứ hai: kiểm tra mã lỗi hai lần
set -e
pnpm install
if [ $? -ne 0 ]; then
echo "pnpm install failed"
exit 1
fi
set -e làm script dừng ngay khi có lệnh lỗi. Nên nếu pnpm install lỗi, script đã dừng trước khi tới dòng if. Khối if không bao giờ chạy với giá trị khác 0, nó chỉ làm script dài gấp ba. Chọn một trong hai cách, và set -e gọn hơn:
- bash: |
set -euo pipefail # lỗi là dừng, biến chưa khai báo là lỗi, lỗi giữa pipe cũng tính
corepack enable # dùng đúng bản pnpm ghi trong packageManager của package.json
pnpm install --frozen-lockfile
pnpm run build:prod
test -d dist || { echo "Không thấy thư mục dist sau khi build"; exit 1; }
workingDirectory: addin
displayName: 'Cài package và build'
corepack enable thay cho npm install -g pnpm: lệnh cũ cài bản pnpm mới nhất ở thời điểm chạy, tháng sau có thể khác tháng này. Corepack đọc trường packageManager (ví dụ "pnpm@9.12.0") trong package.json nên mọi máy dùng cùng một bản. --frozen-lockfile thì giống npm ci: lock file lệch là báo lỗi thay vì tự sửa.
Artifact theo version, và chỗ chưa đúng thứ ba: kiểm nhầm chỗ
- task: CopyFiles@2
inputs:
SourceFolder: addin
Contents: 'dist/**'
TargetFolder: '$(Build.ArtifactStagingDirectory)/$(Version)'
- task: PublishPipelineArtifact@1
inputs:
targetPath: '$(Build.ArtifactStagingDirectory)/$(Version)'
artifact: 'addin-prod'
Bản đầu có thêm một bước "Verify artifacts" sau khi publish, kiểm thư mục dist có trong thư mục staging. Nhưng thư mục staging là thứ ta vừa copy vào ở bước trên, kiểm nó sau khi publish không chứng minh được artifact trên Azure có đủ file. Muốn kiểm thật, đặt bước kiểm trước khi publish, và kiểm thứ có ý nghĩa: file manifest của add-in có đúng số phiên bản không, file HTML chính có trong dist không.
Stage production và nút phê duyệt
- stage: DeployProd
dependsOn: Build
jobs:
- deployment: Deploy
environment: Production
strategy:
runOnce:
deploy:
steps:
- download: current
artifact: addin-prod
- bash: echo "Triển khai bản $(Build.BuildNumber)"
deployment là loại job đặc biệt, gắn với một Environment tên Production. Được hai thứ:
- Lịch sử triển khai: trang Environment liệt kê bản nào lên lúc nào, từ commit nào. Kết hợp với tên lần chạy là version, đây chính là câu trả lời cho câu hỏi đầu bài.
- Phê duyệt và kiểm tra: vào Environment → Approvals and checks, thêm người phải duyệt. Stage này sẽ dừng chờ, người đó nhận thông báo và bấm duyệt hoặc từ chối.
Phê duyệt cấu hình trên giao diện, không nằm trong YAML. Đây là chủ ý: người sửa được file YAML không tự bỏ được bước duyệt.
Bản đầu của mình đặt cả bước build vào trong deployment job gắn Environment Production. Chạy được, nhưng nghĩa là muốn build để thử cũng phải chờ duyệt production, và lịch sử của Environment đầy những lần "triển khai" thực ra chỉ là build. Tách build ra stage thường, chỉ để phần đưa lên production trong deployment job, như trên.
Ba chỗ sửa, tóm lại
| Trước | Sau |
|---|---|
| Không tìm thấy tag thì dùng số build, checkout mặc định | fetchDepth: 0, fetchTags: true; không có tag thì dừng |
set -e cộng if [ $? -ne 0 ] sau mỗi lệnh |
set -euo pipefail, bỏ các khối if |
npm install -g pnpm |
corepack enable theo packageManager |
| Kiểm thư mục staging sau khi publish | Kiểm nội dung trước khi publish |
| Build nằm trong deployment job | Build ở stage riêng, deployment job chỉ để triển khai |
Thử ngay: mở danh sách lần chạy của pipeline release, nhìn tên. Nếu là ngày tháng cộng số thứ tự, thêm một dòng ##vso[build.updatebuildnumber] là xong phần dễ nhất.
Bài sau trong series: một pipeline deploy lên nhiều máy đích, template theo từng máy, agent tự host, và vì sao mật khẩu không được nằm trong file YAML. Team bạn đánh version theo tag, theo ngày, hay theo số build? Comment cho mình biết với.
P.S. Quy ước tag và cách đặt version mình thống nhất với team qua skill git-workflow-manager trong PrimeKit, bộ skill mình tự làm. Skill lo các thao tác Git theo conventional commits (commit, push, PR, merge) và quét secret trước khi commit, nên lịch sử commit đủ sạch để đọc ra một bản release có gì. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:git-workflow-manager. Gắn tag release lúc nào vẫn là quyết định của người phát hành.
Tài liệu để đọc thêm
- Logging commands, Microsoft Learn
- Đặt và dùng output variable, Microsoft Learn
- Deployment jobs, Microsoft Learn
- Approvals and checks, Microsoft Learn
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
- Front End thực chiến: những bài toán UI mà tutorial không dạy: ngày giờ và giờ mùa hè, tầng dữ liệu theo hợp đồng API, chart, in ấn và accessibility, Outlook Add-in, E2E với Playwright.
- Dùng AI hiệu quả trong công việc: kinh nghiệm thực chiến của dev: viết prompt đủ ngữ cảnh, bắt AI bịa API, giao việc cho agent, review code AI viết, debug, đọc codebase lạ, đóng gói quy trình thành skill.
All rights reserved