0

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


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí