Environment & Parameters

environment là cấu hình runtime không nhạy cảm của Pipeline, còn parameters là input lúc khởi tạo build. Cả hai làm Jenkinsfile linh hoạt hơn, nhưng không phải quyền truy cập: một giá trị được chọn không tự cho phép job chạm production, gọi hostname hoặc chạy lệnh tùy ý.

Mục lụcCopy Anchor Link

• Hai namespace env và params
  • env: biến môi trường của process
  • params: input của build
• Khai báo environment và parameters
  • Pipeline-level và stage-level environment
  • String, boolean và choice parameters
• Scope, override và precedence
  • Bản đồ scope
  • Quy tắc precedence
  • withEnv cho override ngắn hạn
• Khi nào giá trị được resolve?
  • Giá trị tĩnh và giá trị dynamic
  • Tính dynamic value trong script an toàn
• Jenkinsfile mẫu an toàn
  • Vì sao mẫu không nội suy parameter vào shell
• Credential, secret và ranh giới tin cậy
  • Binding ở scope hẹp
  • Masking không thay thế bảo mật
  • PR, fork và plugin assumptions
• Lab: quan sát scope và dynamic value
  • Chuẩn bị
  • Tạo Jenkinsfile lab
  • Xác minh cú pháp và parameter
  • Chạy staging và đọc log
  • Kiểm tra scope ngắn hạn
  • Chạy các trường hợp
• Lỗi thường gặp
• Checklist
• Nguồn Jenkins chính thức
• Đọc tiếp

Hai namespace env và paramsCopy Anchor Link

env: biến môi trường của processCopy Anchor Link

env là đối tượng Pipeline để đọc hoặc, trong các trường hợp phù hợp, đặt biến môi trường. Jenkins cũng đặt sẵn nhiều biến như BUILD_NUMBER, JOB_NAME, WORKSPACE và BRANCH_NAME khi ngữ cảnh cung cấp chúng. Khi gọi sh, các biến đang hiệu lực được truyền vào process shell; shell Unix đọc chúng bằng $NAME.

Dùng env cho cấu hình mà process cần biết, chẳng hạn tên ứng dụng, log level hoặc mã định danh build. Không dùng env làm kho secret trong Git. Với biến do environment {} khai báo, giá trị nên là hằng không nhạy cảm hoặc tham chiếu credential đã quản trị; chi tiết binding nằm ở Credentials trong Pipeline.

params: input của buildCopy Anchor Link

params chứa các parameter mà người dùng hoặc trigger đã chọn cho lần build hiện tại. Trong Declarative Pipeline, đọc chúng qua params.TÊN, ví dụ params.DEPLOY_TIER. params khác env: parameter là dữ liệu điều khiển flow, không phải lời hứa rằng process shell sẽ nhận được biến cùng tên trên mọi loại job/plugin.

Dùng parameter cho lựa chọn nhỏ, đã định nghĩa trước, rồi kiểm tra/map lại trước hành động có side effect. choice cho phép Jenkins UI giới hạn lựa chọn, nhưng Jenkinsfile vẫn nên có allowlist khi giá trị chuẩn bị đi vào logic nhạy cảm. string là input tự do hơn nên phải có giới hạn độ dài/định dạng và không được đưa thẳng vào shell, URL, hostname, path hay câu lệnh.

Khai báo environment và parametersCopy Anchor Link

Pipeline-level và stage-level environmentCopy Anchor Link

environment ở cấp pipeline áp dụng cho các stage. environment bên trong một stage chỉ áp dụng khi stage đó chạy và có thể đặt giá trị cùng tên để chuyên biệt hóa giá trị pipeline-level cho stage này.

pipeline {
  agent any

  environment {
    APP_NAME = 'inventory-api'
    LOG_LEVEL = 'info'
  }

  stages {
    stage('Package') {
      environment {
        LOG_LEVEL = 'debug'
      }
      steps {
        sh 'printf "%s\\n" "$APP_NAME:$LOG_LEVEL"'
      }
    }
  }
}

Trong stage Package, output là inventory-api:debug; ngoài stage đó, LOG_LEVEL trở lại info. agent any chỉ giúp ví dụ ngắn; Pipeline thật nên chọn label/toolchain và trust boundary rõ ràng như giải thích ở Declarative Pipeline.

String, boolean và choice parametersCopy Anchor Link

Khai báo parameters ở cấp pipeline, không đặt trong steps. Ba loại dưới đây có vai trò khác nhau:

Lần đầu Jenkins chạy một Jenkinsfile mới có parameters, UI của một số job có thể chưa hiện Build with Parameters cho đến khi build đầu tiên đã lưu properties của job. Chạy lần đầu trên branch/job lab, xác nhận parameter và default trong UI rồi mới dùng nó trong flow quan trọng.

Scope, override và precedenceCopy Anchor Link

Bản đồ scopeCopy Anchor Link

Sơ đồ này mô tả thứ tự các scope bao quanh một sh trong stage. Scope gần process hơn có thể che cùng tên biến từ scope ngoài trong thời gian nó còn hiệu lực.

direction: down
baseline: Jenkins/controller, node hoặc agent env
pipeline: "Pipeline-level environment\nAPP_NAME, LOG_LEVEL=info"
stage: "Stage-level environment\nLOG_LEVEL=debug"
overlay: "withEnv\nLOG_LEVEL=trace"
process: Shell đọc APP_NAME và LOG_LEVEL=trace
params: "params.DEPLOY_TIER\nnamespace riêng, chỉ dùng khi\nJenkinsfile đọc nó"
baseline -> pipeline -> stage -> overlay -> process

Quy tắc precedenceCopy Anchor Link

Khi cùng tên biến môi trường xuất hiện ở các scope trên, áp dụng các quy tắc thực hành sau:

1. Giá trị stage-level che giá trị cùng tên ở pipeline-level trong stage đó.
2. withEnv bên trong stage che giá trị từ pipeline-level lẫn stage-level trong closure của nó. Khi closure kết thúc, giá trị stage-level có hiệu lực lại.
3. Biến được khai báo bằng Declarative environment không nên bị sửa bằng phép gán imperative env.NAME = '...'. Jenkins bảo vệ giá trị Declarative theo cách này; dùng withEnv khi cần override tạm.
4. Biến do code tạo bằng env.NAME = '...' có thể bị ghi đè bởi một phép gán env sau đó, nhưng cách này làm provenance khó thấy hơn. Chỉ dùng cho giá trị runtime đã validate và ưu tiên một tên mới, ví dụ RUN_SUMMARY, thay vì đổi hằng cấu hình như APP_NAME.
5. params.NAME không tham gia precedence của env.NAME. Nếu tên trùng nhau, chúng vẫn là hai namespace khác; đọc đúng namespace và đừng dựa vào việc plugin có export parameter thành environment hay không.

Không dùng precedence để vượt policy. Một withEnv có thể đổi LOG_LEVEL cho test, nhưng không được dùng để tự nạp credential, đổi endpoint sang host do user nhập, hay giả mạo biến mà tool security dựa vào.

withEnv cho override ngắn hạnCopy Anchor Link

withEnv phù hợp khi một process riêng cần biến khác mà không muốn làm rò giá trị sang step kế tiếp. Đây là một Pipeline step, nên availability cụ thể phụ thuộc bộ plugin Pipeline của controller; kiểm tra Pipeline Syntax trên chính Jenkins của bạn.

Diff chỉ thay scope của lệnh diagnostic: bản trước đọc debug, bản sau tạm đọc trace. Cả hai vẫn kiểm tra debug ở step kế tiếp. Đây là fragment stage, đặt bên trong stages của Declarative Pipeline.

Trong block, shell nhận trace; sau block, test xác nhận stage-level debug đã trở lại. Dùng triple single quote cho script nhiều dòng để Groovy không nội suy $LOG_LEVEL trước shell. Việc quote đúng không làm input không tin cậy an toàn: giải pháp chính vẫn là không đưa input tự do vào script.

Khi nào giá trị được resolve?Copy Anchor Link

Giá trị tĩnh và giá trị dynamicCopy Anchor Link

Jenkins parse cấu trúc Declarative trước khi thực thi flow. Khi người dùng khởi tạo build, parameter được chọn rồi Pipeline đọc qua params. Giá trị environment có scope tương ứng khi Jenkins đi vào Pipeline/stage/block đó; built-in như BUILD_NUMBER và WORKSPACE chỉ có ý nghĩa khi Jenkins đã tạo build hoặc cấp agent/workspace phù hợp.

Giá trị tĩnh nên nằm trực tiếp trong environment, ví dụ APP_NAME = 'inventory-api'. Đừng cố gọi shell để “tính động” trong top-level environment: việc đó phụ thuộc thứ tự cấp agent, workspace và version/plugin, có thể làm lúc parse hoặc lúc cấp agent khó đoán hơn. Nếu giá trị cần command hoặc metadata runtime, tính nó sau khi stage đã có agent, trong script {} hoặc step rõ ràng.

Với when chỉ đọc parameter/metadata, thêm beforeAgent true để Jenkins quyết định trước khi giữ executor. Xem Điều kiện when và phê duyệt input để biết thứ tự when, input và stage agent.

Tính dynamic value trong script an toànCopy Anchor Link

Dynamic value là dữ liệu chỉ biết khi build đang chạy, ví dụ build number hoặc kết quả một phép map đã review. Mẫu an toàn là: lấy input có giới hạn, kiểm tra allowlist, map sang giá trị cố định, rồi đặt một biến mới cho những step tiếp theo. Không chạy Groovy hay shell do parameter cung cấp.

script {
  def tiers = [
    'staging': 'STAGING',
    'production': 'PRODUCTION',
  ]
  def selectedTier = tiers[params.DEPLOY_TIER]

  if (selectedTier == null) {
    error('DEPLOY_TIER is not allowlisted')
  }

  def mode = params.DRY_RUN ? 'dry-run' : 'preview'
  env.RUN_SUMMARY = "${selectedTier}-${mode}-${env.BUILD_NUMBER}"
}

RUN_SUMMARY chỉ được tạo từ map cố định, boolean và BUILD_NUMBER do Jenkins tạo. Step sh sau đó có thể đọc $RUN_SUMMARY mà không cần nội suy params vào script. Nếu dynamic value thật sự cần gọi tool, gọi một command cố định, lấy output qua sh(returnStdout: true, script: '...').trim(), kiểm tra format/allowlist/độ dài trước khi lưu và không làm điều này trong scope có secret trừ khi bắt buộc.

Jenkinsfile mẫu an toànCopy Anchor Link

Mẫu này có string, boolean và choice parameter; environment tĩnh ở hai scope; withEnv; và một dynamic value tính trong script. Nó chỉ in metadata đã kiểm soát và không checkout, deploy, gọi network hay dùng credential. Cần Declarative Pipeline và agent Unix linux; sh là step Unix. Đổi label theo agent lab thực tế, không chuyển workload không tin cậy sang controller để mẫu chạy được.

pipeline {
  agent none

  parameters {
    string(
      name: 'RELEASE_NOTE',
      defaultValue: '',
      trim: true,
      description: 'Metadata tối đa 120 ký tự; không được đưa vào shell hoặc hostname.'
    )
    booleanParam(
      name: 'DRY_RUN',
      defaultValue: true,
      description: 'Chỉ chọn chế độ mô phỏng đã định nghĩa.'
    )
    choice(
      name: 'DEPLOY_TIER',
      choices: ['staging', 'production'],
      description: 'Chỉ là lựa chọn policy; không cấp quyền deploy.'
    )
  }

  environment {
    APP_NAME = 'inventory-api'
    LOG_LEVEL = 'info'
  }

  stages {
    stage('Validate và tính runtime metadata') {
      agent { label 'linux' }
      steps {
        script {
          if (params.RELEASE_NOTE.length() > 120) {
            error('RELEASE_NOTE must be 120 characters or fewer')
          }

          def tiers = [
            'staging': 'STAGING',
            'production': 'PRODUCTION',
          ]
          def selectedTier = tiers[params.DEPLOY_TIER]
          if (selectedTier == null) {
            error('DEPLOY_TIER is not allowlisted')
          }

          def mode = params.DRY_RUN ? 'dry-run' : 'preview'
          env.RUN_SUMMARY = "${selectedTier}-${mode}-${env.BUILD_NUMBER}"
        }

        sh '''
          set -eu
          test -n "$RUN_SUMMARY"
          printf '%s\n' "app=$APP_NAME summary=$RUN_SUMMARY level=$LOG_LEVEL"
        '''
      }
    }

    stage('Package preview') {
      agent { label 'linux' }
      environment {
        LOG_LEVEL = 'debug'
      }
      steps {
        withEnv(['LOG_LEVEL=trace']) {
          sh '''
            set -eu
            printf '%s\n' "package app=$APP_NAME summary=$RUN_SUMMARY level=$LOG_LEVEL"
          '''
        }
        sh 'test "$LOG_LEVEL" = "debug"'
      }
    }

    stage('Staging preview') {
      when {
        beforeAgent true
        expression { params.DEPLOY_TIER == 'staging' }
      }
      agent { label 'linux' }
      steps {
        sh '''
          set -eu
          printf '%s\n' "staging preview only: $RUN_SUMMARY"
        '''
      }
    }
  }

  post {
    always {
      echo 'Pipeline finished; no deployment or credential binding was attempted.'
    }
  }
}

Vì sao mẫu không nội suy parameter vào shellCopy Anchor Link

• RELEASE_NOTE chỉ được kiểm tra độ dài và không bị in. Nó có thể chứa nội dung tự do, nên không xuất hiện trong shell, path, URL, hostname hay message có khả năng bị diễn giải.
• DEPLOY_TIER có choice và còn được map lại qua tiers. Shell chỉ nhận RUN_SUMMARY được tạo từ map cố định, boolean và build number.
• DRY_RUN đi qua biểu thức boolean để tạo dry-run hoặc preview; không phải một chuỗi do user truyền vào command.
• Stage Staging preview chỉ quyết định có in một dòng cố định hay không. Dù chọn production, mẫu không deploy và không mở endpoint nào.

Trong Pipeline thật, target phải được map trong code/cấu hình đáng tin cậy sang endpoint cố định, còn authorization tồn tại ở Jenkins và hệ thống đích. Thêm gate/approval phù hợp theo Điều kiện when và phê duyệt input, không biến parameter thành lối tắt qua các gate đó.

Credential, secret và ranh giới tin cậyCopy Anchor Link

Binding ở scope hẹpCopy Anchor Link

Không truyền secret bằng string parameter hay environment hard-code. Tạo credential trong Jenkins, cấp scope folder/job hẹp nhất rồi bind đúng block cần dùng. credentials('credential-id') là helper của Declarative environment; withCredentials là step của plugin Credentials Binding. Chúng là capability khác với params và cần credential ID tồn tại cùng permission phù hợp.

withCredentials([
  string(credentialsId: 'release-api-token', variable: 'API_TOKEN')
]) {
  sh '''
    set +x
    # Công cụ đã review đọc API_TOKEN từ environment.
    ./scripts/publish-release
  '''
}

Đây chỉ là pattern tham chiếu, không phải một phần của lab/mẫu chạy được ở trên. Nó giả định plugin Credentials Binding và script ./scripts/publish-release tồn tại; kiểm tra snippet, version plugin và quyền trên controller của bạn. Giữ binding ngắn, dùng single quote/triple single quote để tránh Groovy interpolation của secret, và không gửi token qua URL hoặc command line.

Masking không thay thế bảo mậtCopy Anchor Link

Jenkins/Credentials Binding cố gắng mask secret đã biết trong Console Output, kể cả một số dạng shell-escaped. Masking không chặn code có secret gửi nó ra network, ghi vào file/artifact/cache, biến đổi/encode nó hoặc để process khác cùng agent đọc. Không echo, printenv, env, set, cat hay bật set -x quanh binding.

Xem hướng dẫn đầy đủ, gồm secret file và workspace, ở Credentials trong Pipeline.

PR, fork và plugin assumptionsCopy Anchor Link

Jenkinsfile, dependency, source và parameter từ pull request (PR), đặc biệt PR từ fork, đều là input không tin cậy. Không cấp credential phát hành, Docker socket, cloud role, agent chứa dữ liệu nhạy cảm hoặc quyền production cho build đó. Chạy CI không tin cậy trên agent tách biệt; chỉ bind capability nhạy cảm sau merge hoặc trong flow được tổ chức tin cậy/phê duyệt.

environment, parameters, when và cấu trúc pipeline {} cần plugin Pipeline: Declarative. withEnv, sh, withCredentials, Branch Source metadata và integration deploy có thể do plugin/OS khác cung cấp, với behavior/version khác nhau. Pipeline Syntax và Declarative linter của controller là nguồn xác nhận cho instance đang chạy; tài liệu cú pháp chung không chứng minh agent có tool, credential có permission hay plugin đã cài. Để chuẩn bị controller/agent lab, xem Yêu cầu hệ thống và chạy Jenkins với Docker.

Lab: quan sát scope và dynamic valueCopy Anchor Link

Chuẩn bịCopy Anchor Link

Lab dùng Jenkinsfile mẫu ở trên và không cần repository ứng dụng, credential hay service ngoài. Cần Jenkins có Pipeline: Declarative, agent Unix online có label linux, shell sh và quyền tạo Pipeline job. Nếu agent không có label đó, sửa label của lab thành label thực tế; không dùng controller/built-in node cho workload không tin cậy.

Chạy các trường hợpCopy Anchor Link

Sau mỗi build, đọc build number, stage state và Console Output thay vì chỉ nhìn trạng thái xanh/đỏ. Nếu build chờ queue, kiểm tra agent linux và executor trước khi sửa Jenkinsfile. Để hiểu job, build, agent và log, xem Tổng quan Jenkins Pipeline và Jenkinsfile.

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

ChecklistCopy Anchor Link

• environment chỉ chứa cấu hình không nhạy cảm hoặc credential reference đã review; không hard-code secret.
• Tôi đọc đúng env.NAME và params.NAME như hai namespace riêng.
• Pipeline-level, stage-level và withEnv có scope tối thiểu; tên biến không che nhau vô tình.
• Override tạm dùng withEnv; hằng Declarative không bị sửa bằng env.NAME =.
• Parameter string có giới hạn/validation và không xuất hiện trong shell, URL, hostname, path, artifact hay log.
• Choice/boolean được map hoặc so sánh rõ ràng trước flow có tác động; parameter không được coi là authorization.
• Dynamic value được tính sau khi có runtime context, validate trước khi dùng và không thực thi command do input cung cấp.
• Shell dùng single quote/triple single quote khi cần shell mở rộng biến; không Groovy-interpolate secret.
• Credential binding ở closure/stage hẹp nhất; không echo, set -x, dump environment hoặc archive dữ liệu binding.
• PR/fork không nhận secret hay agent đặc quyền; plugin, step, agent và credential assumptions đã được xác minh trên controller.
• Lab đã chứng minh ít nhất một override withEnv, một dynamic value, một stage when chạy và một stage bị skip.

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

• Using a Jenkinsfile — environment, parameters, credentials và biến Pipeline.
• Pipeline Syntax — Declarative directives, when, parameter và thứ tự thực thi.
• Pipeline development tools — Pipeline Syntax, Directive Generator và Declarative linter.
• Using credentials — credential store, scope và permission.
• Credentials Binding plugin — withCredentials, masking và cảnh báo secret file/workspace.
• Pipeline: Basic Steps — withEnv và các Pipeline step cơ bản.
• Multibranch Pipeline — branch/PR metadata và trust policy theo SCM source.

Đọc tiếpCopy Anchor Link