Thiết kế Stages & Steps

Mục lụcCopy Anchor Link

• Mô hình stage step và agent
  • Ranh giới stage trong Pipeline
• Thiết kế ranh giới stage
  • Đặt tên theo mục tiêu
  • Độ hạt và khả năng quan sát
  • Chọn agent phù hợp
• Phân loại step trước khi dùng
  • Stage steps và step cụ thể
  • Step cơ bản và step phụ thuộc plugin
• Jenkinsfile Linux có thể chạy
  • Đọc Jenkinsfile theo stage
• Shell sh và batch bat
  • Exit code quyết định kết quả build
  • Quoting và đường dẫn
• Đặt tên custom step
  • Shared Library không phải plugin ngầm định
• Lab thiết kế và quan sát Pipeline
  • Kết quả mong đợi
• Lỗi thường gặp
• Checklist trước khi review
• Nguồn Jenkins chính thức
• Nền tảng nên đọc

Mô hình stage step và agentCopy Anchor Link

Một stage là một chặng có kết quả mà con người cần nhận biết, chẳng hạn Unit test hoặc Build package. Một step là hành động cụ thể bên trong chặng đó, chẳng hạn sh 'npm test'. Agent là môi trường thực thi: nó quyết định hệ điều hành, toolchain, workspace và executor thật sự chạy step.

direction: down
commit: Commit
controller: Controller xếp hàng
agent: Agent phù hợp
workspace: Workspace
checkout: Checkout source
test: Unit test
log: Log stage Test
build: Build package
artifact: Artifact/kết quả
commit -> controller -> agent -> workspace -> checkout -> test
test -> log: Lỗi
test -> build: Đạt
build -> artifact

Controller hiển thị trạng thái stage và tập hợp console log, còn lệnh chạy trên agent. Vì vậy, một Jenkinsfile đúng cú pháp vẫn có thể chờ trong queue nếu không có agent mang label yêu cầu, hoặc thất bại nếu agent thiếu node, npm, shell hay quyền trên workspace. Nền tảng về controller, queue, executor và workspace được giải thích tại Kiến trúc Jenkins.

Ranh giới stage trong PipelineCopy Anchor Link

Ranh giới stage nên trùng với một mục tiêu kiểm chứng được hoặc một điểm đổi loại công việc. Ví dụ, Checkout source, Unit test và Build package cho biết ngay mã chưa được lấy, test lỗi, hay quá trình đóng gói lỗi. Không dùng stage chung chung như Run, Process hoặc Step 2; chúng không trả lời người sửa build cần làm gì tiếp theo.

Một stage không phải một dòng lệnh. Hai lệnh npm ci và npm test có thể ở cùng stage Unit test nếu chúng cùng phục vụ phản hồi kiểm thử và cần đọc cùng log. Ngược lại, tách Build package khỏi Unit test khi artifact hoặc toolchain thay đổi: giao diện Jenkins sẽ chỉ đúng chặng bị đỏ và thời lượng từng chặng có thể được theo dõi độc lập.

Thiết kế ranh giới stageCopy Anchor Link

Đặt tên theo mục tiêuCopy Anchor Link

Tên stage nên là động từ hoặc kết quả nghiệp vụ ngắn, nhất quán với ngôn ngữ của nhóm. Những tên sau giúp nhận diện nguyên nhân nhanh hơn:

Tên cần mô tả đích, không mô tả implementation duy nhất. Chẳng hạn Unit test vẫn đúng khi nhóm đổi từ npm test sang mvn test; còn Run npm test buộc UI và lịch sử stage gắn với một công cụ.

Độ hạt và khả năng quan sátCopy Anchor Link

Tách stage khi ít nhất một điều đúng:

• kết quả tạo ra một quality gate độc lập, ví dụ lint pass/fail trước unit test;
• stage cần agent, container, quyền hoặc toolchain khác;
• người trực build sẽ xử lý lỗi bằng log khác nhau;
• thời lượng của chặng cần được đo riêng để tìm bottleneck.

Không tách Install dependency, Run test command và Print test result thành ba stage chỉ để pipeline có nhiều ô. Quá nhiều stage làm luồng khó đọc và tăng lần cấp agent nếu mỗi stage khai báo agent riêng. Một điểm bắt đầu tốt cho CI nhỏ là Checkout source → Unit test → Build package; điều chỉnh sau khi đã quan sát log, thời lượng và tỷ lệ lỗi.

Chọn agent phù hợpCopy Anchor Link

Khai báo agent { label 'linux && node20' } chỉ chạy khi có agent online mang cả hai label. Nhãn nên phản ánh năng lực đã quản lý, như linux, windows, node20, jdk21 hoặc arm64; không dùng agent any để che sự khác nhau về toolchain trong production.

Đặt agent ở cấp pipeline khi đa số stage dùng cùng môi trường và workspace. Đặt agent trong từng stage khi một chặng thật sự cần môi trường khác, ví dụ ký gói trên Windows sau khi test trên Linux. Khi stage dùng agent riêng, không giả định workspace của stage trước tự xuất hiện trên agent sau: cần checkout lại hoặc chuyển artifact bằng cơ chế đã được thiết kế.

Phân loại step trước khi dùngCopy Anchor Link

Stage steps và step cụ thểCopy Anchor Link

Trong Declarative Pipeline, stage('Unit test') là directive tạo một chặng hiển thị được, không phải step chạy command. steps { ... } là block chứa các hành động. Bên trong block này mới là các step như echo, checkout, sh và bat.

Step cơ bản và step phụ thuộc pluginCopy Anchor Link

Đừng hiểu “built-in step” là mọi Jenkins cài mới đều có mọi lệnh. Jenkins Core điều phối controller và agent; khả năng Pipeline, Declarative syntax và các step thường được phân phối qua các plugin Pipeline. Một Jenkins LTS cài bộ Pipeline phổ biến thường có các step cơ bản như echo, sh, bat và checkout, nhưng tên plugin hay phiên bản có thể thay đổi theo bản cài.

Vì vậy, hãy tra Pipeline Syntax → Steps Reference trên controller của chính bạn trước khi thêm step mới. Trang này phản ánh plugin đang cài, thay vì giả định một plugin có trên mọi Jenkins.

Jenkinsfile Linux có thể chạyCopy Anchor Link

Ví dụ sau dành cho một Multibranch Pipeline hoặc Pipeline from SCM đã cấu hình repository. Nó yêu cầu agent Linux có labels linux và node20, cùng git, node và npm. checkout scm sẽ lấy revision mà job đang build; với job script nội tuyến không cấu hình SCM, bước này không có nguồn để checkout.

pipeline {
  agent { label 'linux && node20' }

  stages {
    stage('Checkout source') {
      steps {
        echo 'Checking out the revision selected by Jenkins'
        checkout scm
      }
    }

    stage('Unit test') {
      steps {
        sh label: 'Install dependencies and run tests', script: '''
          set -eu
          echo 'Running unit tests'
          npm ci
          npm test
        '''
      }
    }

    stage('Build package') {
      steps {
        sh label: 'Build distributable package', script: '''
          set -eu
          echo "Building in $WORKSPACE"
          npm run build
        '''
      }
    }
  }
}

Đọc Jenkinsfile theo stageCopy Anchor Link

• agent { label 'linux && node20' } giữ một agent phù hợp trong toàn Pipeline, nên ba stage dùng cùng workspace của lần build đó.
• echo tạo dấu mốc dễ tìm trong Console Output. Thông điệp là hằng số hoặc metadata không nhạy cảm; không echo credential hay toàn bộ biến môi trường.
• checkout scm lấy source vào WORKSPACE. Nếu checkout thất bại, xem URL/credential SCM và log của chính stage này.
• sh chạy chuỗi lệnh trong shell Unix. set -e dừng script ở command lỗi; set -u biến việc dùng biến chưa đặt thành lỗi. Exit code khác 0 làm step thất bại, từ đó stage và build thất bại.
• Triple single quote Groovy ('''...''') chuyển nguyên script cho shell. Dòng "Building in $WORKSPACE" dùng double quote của shell để shell mở rộng biến môi trường, không yêu cầu Groovy nội suy ${...}.

Ví dụ minh họa một ứng dụng Node.js. Với dự án khác, thay npm ci, npm test và npm run build bằng các lệnh đã chạy được trên agent tương ứng. Khái niệm CI/CD và lý do đưa Jenkinsfile vào repository có tại Nền tảng CI/CD.

Shell sh và batch batCopy Anchor Link

Exit code quyết định kết quả buildCopy Anchor Link

Trên Linux/Unix, sh coi exit code 0 là thành công; giá trị khác 0 là lỗi và mặc định làm Pipeline dừng. Nếu cần thu exit code để thêm ngữ cảnh, dùng returnStatus: true, rồi chủ động fail bằng error:

script {
  int status = sh(returnStatus: true, script: 'npm test')
  if (status != 0) {
    error "Unit test failed with exit code ${status}"
  }
}

Trên Windows, bat chạy qua cmd.exe. Lệnh cuối cùng cần trả về mã lỗi chính xác; exit /b %ERRORLEVEL% chuyển mã lỗi của command vừa chạy về Jenkins.

bat '''
  @echo off
  echo Running unit tests
  call npm ci
  if errorlevel 1 exit /b %ERRORLEVEL%
  call npm test
  exit /b %ERRORLEVEL%
'''

call quan trọng với file batch như npm.cmd: không có call, cmd.exe có thể không quay lại script cha để chạy dòng tiếp theo. Khi npm test thất bại, bat trả exit code khác 0, stage Unit test đỏ và Console Output hiển thị command lỗi.

Quoting và đường dẫnCopy Anchor Link

Groovy quote, shell quote và Windows quote là ba lớp khác nhau. Dùng Groovy single quote hoặc triple single quote khi không cần Groovy nội suy. Chỉ dùng double quote ở shell/batch để bao đường dẫn có khoảng trắng hoặc để mở rộng biến của chính shell.

Linux với sh: $WORKSPACE được shell mở rộng. Double quote giữ đường dẫn là một đối số, kể cả khi workspace chứa khoảng trắng.

sh '''
  set -eu
  test -f "$WORKSPACE/package.json"
  ./scripts/check-file "$WORKSPACE/docs/release notes.md"
'''

Windows với bat: %WORKSPACE% được cmd.exe mở rộng và backslash là dấu phân tách đường dẫn. call giúp chạy file .cmd một cách rõ ràng.

bat '''
  @echo off
  call "%WORKSPACE%\scripts\check-file.cmd" "%WORKSPACE%\docs\release notes.md"
  exit /b %ERRORLEVEL%
'''

Không ghép secret vào command, kể cả bằng quote. Ví dụ, curl -H "Authorization: Bearer $TOKEN" có thể lộ token qua log debug, process list hoặc lỗi command. Lưu secret trong Jenkins Credentials, giới hạn scope của credential và gọi công cụ theo cơ chế an toàn đã được đội kiểm tra. Xem nguyên tắc cài đặt và bảo vệ controller/agent tại Yêu cầu hệ thống.

Đặt tên custom stepCopy Anchor Link

Custom step nên mang ý định của tổ chức, dùng động từ và danh từ: verifyProject(), publishBuildMetadata() hoặc notifyBuildResult(). Tránh tên mơ hồ như run() và tránh gắn tên tool vào API chung nếu muốn giữ quyền đổi implementation. Tên tốt nói việc cần đạt; implementation có thể gọi sh, bat hay API khác.

Shared Library không phải plugin ngầm địnhCopy Anchor Link

verifyProject() dưới đây chỉ tồn tại nếu đội đã tạo Shared Library và cấu hình library đó cho job/folder/global Jenkins. Nó không phải Jenkins core step và không giả định plugin tích hợp bên thứ ba nào. Ví dụ vars/verifyProject.groovy của Shared Library có thể là:

// vars/verifyProject.groovy
def call() {
  sh label: 'Verify project', script: '''
    set -eu
    npm ci
    npm test
  '''
}

Sau khi library đã được nạp theo chính sách của tổ chức, Jenkinsfile trên agent Linux có thể gọi:

stage('Verify project') {
  steps {
    verifyProject()
  }
}

Giữ custom step nhỏ, ghi rõ điều kiện cần có và trả lỗi có ngữ cảnh. Nếu cần chạy Windows, đừng tái sử dụng helper chỉ chứa sh; hãy tạo implementation theo platform hoặc kiểm tra agent trước khi gọi. Shared Library cũng là code có quyền chạy trong Pipeline, nên review, version/pin theo quy ước và không đặt credential trong source library.

Lab thiết kế và quan sát PipelineCopy Anchor Link

Lab này dùng Jenkinsfile Linux ở trên. Điều kiện trước: Jenkins có Pipeline plugins cần thiết, một agent online mang linux và node20, và repository Node.js có package.json, script test và script build. Nếu chưa nắm mô hình controller-agent, đọc Tổng quan về Jenkins trước.

Kết quả mong đợiCopy Anchor Link

• Khi agent có đủ labels và toolchain, ba stage xuất hiện theo thứ tự Checkout source, Unit test, Build package và build kết thúc SUCCESS.
• Khi npm run test-does-not-exist được dùng, chỉ stage Unit test thất bại; console log có command và exit code để chẩn đoán.
• Khi agent không có một trong hai label, build chờ trong queue thay vì chạy nhầm agent.
• Khi đường dẫn có khoảng trắng, các ví dụ đã quote vẫn truyền đường dẫn như một đối số duy nhất.

Lỗi thường gặpCopy Anchor Link

Checklist trước khi reviewCopy Anchor Link

• Mỗi stage có tên theo mục tiêu/kết quả và là một ranh giới quan sát có ích.
• Stage không quá vụn; các chặng tách riêng khi quality gate, agent, toolchain hoặc cách xử lý lỗi khác nhau.
• agent/labels khớp hệ điều hành và toolchain thực tế; queue được kiểm tra khi build chờ.
• checkout scm chỉ dùng trong job đã cấu hình SCM và credential có quyền tối thiểu.
• sh hoặc bat kiểm tra exit code; đường dẫn và biến workspace được quote đúng platform.
• Log chứa dấu mốc hữu ích nhưng không chứa secret, token, password, private key hoặc dump environment.
• Mỗi step tích hợp đã được đối chiếu với plugin/configuration hiện có; custom step có owner và nguồn Shared Library/helper rõ ràng.
• Workspace, artifact và chuyển đổi giữa agent được thiết kế thay vì giả định là dùng chung.

Nguồn Jenkins chính thứcCopy Anchor Link

• Pipeline syntax — cú pháp Declarative Pipeline, agent, stages và steps.
• Using a Jenkinsfile — Jenkinsfile, agent và workspace.
• Pipeline Steps Reference — danh sách step theo plugin đang cài.
• Pipeline: Basic Steps — plugin cung cấp các step Pipeline cơ bản.
• Pipeline: SCM Step — checkout tổng quát cho Pipeline.
• Pipeline: Nodes and Processes — các step chạy process như sh và bat.
• Extending with Shared Libraries — cách tổ chức custom step/library.

Nền tảng nên đọcCopy Anchor Link