Biến môi trường Jenkins

Biến môi trường giúp Jenkins truyền cấu hình và metadata vào process build, nhưng cùng một tên có thể xuất hiện ở controller, agent, job và Jenkinsfile. Trang này chỉ ra giá trị đi từ đâu, scope nào thắng tại một process cụ thể và khi nào phải dùng Jenkins Credentials thay vì environment.

Mục lụcCopy Anchor Link

• Mô hình và hai namespace
  • Controller, agent và process shell
  • Biến built-in và biến custom
  • Parameters: params và environment của build
• Nguồn biến môi trường
  • Bảng nguồn scope và lifecycle
  • Thay đổi cấu hình, restart và build đang chạy
• Scope, precedence và override
  • Sơ đồ precedence của một process
  • Quy tắc thực hành
  • Bảng chẩn đoán precedence
• Đọc và truyền giá trị đúng cách
  • Shell process khác Jenkins env
  • Quote và interpolation
  • Null boolean path và khác biệt hệ điều hành
• Jenkinsfile mẫu an toàn
• Secret và credentials
  • Environment không phải secret store
  • Binding ngắn hạn và giới hạn masking
• Lab sandbox: quan sát override vô hại
  • Chuẩn bị và Jenkinsfile
  • Kết quả mong đợi và cleanup
• Troubleshooting
• Checklist
• Nguồn Jenkins chính thức
• Đọc tiếp

Mô hình và hai namespaceCopy Anchor Link

Controller, agent và process shellCopy Anchor Link

Controller điều phối build và tạo context Pipeline. Agent nhận executor, workspace và chạy sh, bat hoặc powershell. Khi Jenkins gọi một step process, nó tạo một environment cho process đó từ context đang hiệu lực trên agent. Vì vậy, biến của service controller không tự động là biến của shell trên agent.

Ví dụ JENKINS_URL có thể do controller cung cấp cho build, còn PATH của process lại phụ thuộc OS, image hoặc cấu hình node/agent. WORKSPACE chỉ có ý nghĩa sau khi Jenkins đã cấp agent và workspace. Không chuyển workload lên controller chỉ vì một biến chỉ có ở đó; hãy chọn agent có label và trust boundary phù hợp. Xem Kiến trúc Jenkins và Tổng quan Jenkins Agent.

Biến built-in và biến customCopy Anchor Link

Built-in variables là metadata Jenkins hoặc plugin đặt theo context, như BUILD_NUMBER, BUILD_TAG, JOB_NAME, NODE_NAME, WORKSPACE, JENKINS_URL và, với Multibranch Pipeline khi nguồn SCM cung cấp, BRANCH_NAME. Đừng giả định mọi biến built-in luôn có: một job không có workspace chưa có WORKSPACE; Freestyle, Pipeline và plugin Branch Source cũng có thể cung cấp context khác nhau. Tra Global Variable Reference trên controller để xem biến/step của chính instance.

Custom variables là tên đội tự đặt, ví dụ APP_COMPONENT=reports-api hoặc LOG_LEVEL=info. Dùng tên mô tả trách nhiệm, tránh ghi đè các tên Jenkins/tool/OS phổ biến như PATH, HOME, JAVA_HOME nếu chưa hiểu hậu quả. Thiết lập custom variable ở scope hẹp nhất đáp ứng nhu cầu và ghi owner của những biến global.

Parameters: params và environment của buildCopy Anchor Link

Jenkins export build parameters tiêu chuẩn thành environment variables khi build bắt đầu, nên step process thường có thể đọc DEPLOY_TIER bằng $DEPLOY_TIER (POSIX shell), %DEPLOY_TIER% (cmd.exe) hoặc $env:DEPLOY_TIER (PowerShell). Cùng giá trị đó cũng có qua params.DEPLOY_TIER trong Pipeline. Không cần tự export một parameter tiêu chuẩn chỉ để shell thấy nó.

Hai API phục vụ hai mục đích khác nhau. params.NAME giữ giá trị parameter theo kiểu/ngữ nghĩa parameter cho Groovy/Pipeline, chẳng hạn params.DRY_RUN là boolean. env.NAME là biểu diễn chuỗi trong Pipeline environment; process chỉ nhận biểu diễn này. Ví dụ params.DRY_RUN nên được dùng trong condition Groovy, còn shell phải so sánh chuỗi "true"/"false" nếu thật sự cần đọc $DRY_RUN.

Parameter là một nguồn baseline của environment build, không phải một tầng env tách biệt. Nếu tên parameter trùng với environment, withEnv hoặc biến do plugin inject, giá trị env.NAME/process thấy có thể bị overlay bởi scope gần step hơn. params.NAME vẫn là input đã chọn. Jenkins documentation bảo đảm parameter được export khi build bắt đầu và environment áp dụng cho các step theo scope, nhưng không quy định một precedence phổ quát cho mọi plugin hay parameter type tùy biến. Tránh collision bằng tên riêng; nếu không tránh được, kiểm chứng trên controller/version/plugin bằng lab ở dưới.

Nguồn biến môi trườngCopy Anchor Link

Bảng nguồn scope và lifecycleCopy Anchor Link

Không có một nguồn duy nhất cho environment. Bảng này mô tả nơi một giá trị thường được tạo và nơi nó có thể được quan sát; plugin hoặc loại job có thể bổ sung biến khác.

environment không thay thế cấu hình tool. Ví dụ, nối một đường dẫn tùy ý vào PATH không cài JDK, không xác minh checksum và không tạo quyền dùng tool. Với tool dùng chung, xem Cấu hình hệ thống Jenkins; với labels và executor, xem Labels & Executors.

Thay đổi cấu hình, restart và build đang chạyCopy Anchor Link

Một build đang chạy không phải bảng điều khiển để thay đổi environment giữa chừng. Nó có thể đã tạo process environment hoặc đã đi qua stage cần biến đó. Hãy trigger một build sandbox mới để xác minh thay đổi thay vì suy ra từ build cũ.

Scope, precedence và overrideCopy Anchor Link

Sơ đồ precedence của một processCopy Anchor Link

Khi cùng tên LOG_LEVEL được đặt ở nhiều lớp, hãy đọc từ ngoài vào trong. Scope gần step process nhất sẽ che giá trị của scope ngoài trong thời gian nó hiệu lực.

direction: down
baseline: "Controller/global + node/agent\nparameter export lúc bắt đầu build"
env: "Baseline env.LOG_LEVEL\nprocess LOG_LEVEL"
pipeline: "Pipeline environment\nLOG_LEVEL=info"
stage: "Stage environment\nLOG_LEVEL=debug"
overlay: "withEnv\nLOG_LEVEL=trace"
process: Process nhận LOG_LEVEL=trace
params: "params.LOG_LEVEL\nAPI giữ input parameter\nkhông bị env overlay"
baseline -> env -> pipeline -> stage -> overlay -> process
params -> baseline: Export ban đầu {style.stroke-dash: 4}

Sơ đồ là mô hình cho Declarative/Pipeline context thông dụng, không phải cam kết của mọi plugin inject environment. Đối với job/folder/plugin, xác minh bằng một build lab có tên marker mới thay vì ghi đè biến hệ thống quan trọng.

Quy tắc thực hànhCopy Anchor Link

1. Agent/node và global property tạo baseline cho process, nhưng không đáng tin để che cấu hình job mà không có owner.
2. Pipeline-level environment áp dụng trong Pipeline. Stage-level environment che cùng tên trong stage đó.
3. withEnv che giá trị bên ngoài chỉ trong closure. Đây là lựa chọn rõ ràng cho override tạm.
4. Không dùng env.NAME = '...' để cố sửa giá trị đã khai báo bằng Declarative environment; behavior này dễ gây hiểu nhầm và không phải cách override tường minh. Đặt một tên runtime mới đã validate, hoặc dùng withEnv.
5. Parameter tiêu chuẩn vừa có qua params.NAME vừa được export thành env.NAME/process environment khi build bắt đầu. params.NAME giữ input theo kiểu parameter, còn env.NAME là chuỗi và có thể bị environment, withEnv hoặc plugin overlay khi trùng tên. Đừng suy luận collision từ tên giống nhau: đặt tên riêng hoặc quan sát cả ba bề mặt trên controller của bạn.
6. Credentials binding có thể đưa secret vào environment của scope binding, nhưng không là một tầng precedence để lạm dụng. Chỉ bind ngay cạnh công cụ cần capability đó.

Bảng chẩn đoán precedenceCopy Anchor Link

Đọc và truyền giá trị đúng cáchCopy Anchor Link

Shell process khác Jenkins envCopy Anchor Link

Trong Groovy/Pipeline, đọc environment bằng env.NAME; đọc parameter bằng params.NAME. Parameter tiêu chuẩn cũng được Jenkins export thành environment lúc build bắt đầu, nên Unix shell có thể đọc $NAME hoặc ${NAME} mà không cần export lại. env không phải một map Java/Groovy chung để mọi process đang chạy cùng thấy thay đổi; một assignment Pipeline chỉ ảnh hưởng các step được tạo sau trong scope phù hợp. Khi tên trùng nhau, params.NAME diễn tả input parameter còn env.NAME là chuỗi effective environment ở scope hiện tại.

script {
  def tier = params.DEPLOY_TIER
  if (!(tier in ['sandbox', 'staging'])) {
    error('DEPLOY_TIER is not allowlisted')
  }
  env.RUN_MODE = tier == 'staging' ? 'preview' : 'sandbox'
}

sh 'printf "mode=%s build=%s\\n" "$RUN_MODE" "$BUILD_NUMBER"'

Mẫu chỉ map một parameter từ allowlist sang giá trị cố định và in metadata vô hại. Không lấy parameter tự do để đặt PATH, label, credential ID, hostname hay command.

Quote và interpolationCopy Anchor Link

Groovy interpolation xảy ra trước khi Jenkins gửi script tới shell. Shell interpolation xảy ra khi shell chạy. Giữ hai lớp này tách biệt, đặc biệt trong scope có credential.

Single quote ở Groovy không tự làm dữ liệu không tin cậy trở nên an toàn: nó chỉ tránh Groovy nội suy. Input tự do vẫn không được đưa vào script, URL, path hoặc command. Trong shell Unix, luôn quote expansion như "$NAME" khi nó là dữ liệu, để space và glob không làm đổi argument. Trên Windows, quy tắc escape khác giữa cmd.exe và PowerShell; chọn đúng step/shell rồi kiểm tra trên agent Windows thực tế.

Null boolean path và khác biệt hệ điều hànhCopy Anchor Link

Environment là chuỗi. env.FLAG = false trở thành chuỗi như "false"; trong Groovy, chuỗi không rỗng thường là truthy. Đọc boolean từ params qua params.DRY_RUN, hoặc so sánh tường minh với chuỗi đã được chuẩn hóa khi nguồn thực sự là environment.

if (params.DRY_RUN) {
  echo 'Dry run is enabled.'
}

if ((env.FEATURE_FLAG ?: '').toLowerCase() == 'true') {
  echo 'Feature flag is explicitly true.'
}

env.MISSING có thể là null trong Groovy, còn shell với set -u sẽ lỗi khi mở rộng biến chưa đặt. Dùng default có chủ đích, ví dụ ${OPTIONAL_NAME:-} trong POSIX shell, nhưng đừng biến default thành cách bỏ qua một config bắt buộc: kiểm tra test -n "$REQUIRED_NAME" và fail sớm khi cần.

PATH dùng dấu : trên Unix và ; trên Windows; case sensitivity của tên biến cũng phụ thuộc OS/tool. Đường dẫn có space cần được quote. Không tách/ghép PATH bằng một rule dùng cho cả sh, bat và PowerShell. Đặt toolchain trong image, node configuration hoặc tools đã review thay vì dựa vào path local của một agent.

Jenkinsfile mẫu an toànCopy Anchor Link

Mẫu Declarative này thể hiện parameter, Pipeline/stage environment, withEnv và xử lý boolean. Nó không checkout, không gọi network, không dùng credential và chỉ in metadata không nhạy cảm. Cần một agent Unix có label placeholder sandbox-linux; thay label này bằng pool sandbox của bạn, không phải controller.

pipeline {
  agent none

  options {
    skipDefaultCheckout(true)
    timeout(time: 3, unit: 'MINUTES')
  }

  parameters {
    choice(
      name: 'DEPLOY_TIER',
      choices: ['sandbox', 'staging'],
      description: 'Lựa chọn mô phỏng; không cấp quyền deploy.'
    )
    booleanParam(
      name: 'DRY_RUN',
      defaultValue: true,
      description: 'Chỉ điều khiển output sandbox.'
    )
    choice(
      name: 'LAB_PARAM_MARKER',
      choices: ['parameter-baseline'],
      description: 'Marker vô hại để quan sát params, env và process environment.'
    )
    choice(
      name: 'LAB_COLLISION_MARKER',
      choices: ['parameter-baseline'],
      description: 'Marker vô hại để quan sát collision với stage environment.'
    )
  }

  environment {
    APP_COMPONENT = 'example-component'
    LOG_LEVEL = 'info'
  }

  stages {
    stage('Validate context') {
      agent { label 'sandbox-linux' }
      steps {
        script {
          def tiers = ['sandbox': 'sandbox', 'staging': 'preview']
          def selected = tiers[params.DEPLOY_TIER]
          if (selected == null) {
            error('DEPLOY_TIER is not allowlisted')
          }
          env.RUN_MODE = params.DRY_RUN ? "${selected}-dry-run" : "${selected}-check"
          if (params.LAB_PARAM_MARKER != 'parameter-baseline') {
            error('LAB_PARAM_MARKER is not allowlisted')
          }
          echo "params.LAB_PARAM_MARKER=${params.LAB_PARAM_MARKER}"
          echo "env.LAB_PARAM_MARKER=${env.LAB_PARAM_MARKER}"
        }
        sh '''
          set -eu
          test -n "$RUN_MODE"
          test "$LAB_PARAM_MARKER" = 'parameter-baseline'
          printf 'process.LAB_PARAM_MARKER=%s\\n' "$LAB_PARAM_MARKER"
          printf 'component=%s mode=%s level=%s build=%s\\n' \\
            "$APP_COMPONENT" "$RUN_MODE" "$LOG_LEVEL" "$BUILD_NUMBER"
        '''
      }
    }

    stage('Observe parameter collision') {
      agent { label 'sandbox-linux' }
      environment {
        LAB_COLLISION_MARKER = 'declarative-overlay'
      }
      steps {
        script {
          echo "params.LAB_COLLISION_MARKER=${params.LAB_COLLISION_MARKER}"
          echo "env.LAB_COLLISION_MARKER=${env.LAB_COLLISION_MARKER}"
        }
        sh '''
          set -eu
          printf 'process.LAB_COLLISION_MARKER=%s\\n' "$LAB_COLLISION_MARKER"
        '''
      }
    }

    stage('Observe short override') {
      agent { label 'sandbox-linux' }
      environment {
        LOG_LEVEL = 'debug'
      }
      steps {
        withEnv(['LOG_LEVEL=trace']) {
          sh '''
            set -eu
            test "$LOG_LEVEL" = 'trace'
            printf 'inside-withEnv=%s\\n' "$LOG_LEVEL"
          '''
        }
        sh '''
          set -eu
          test "$LOG_LEVEL" = 'debug'
          printf 'after-withEnv=%s\\n' "$LOG_LEVEL"
        '''
      }
    }
  }

  post {
    always {
      echo 'Sandbox example finished; no credential, deploy, artifact, or network action was used.'
    }
  }
}

RUN_MODE được tạo từ allowlist, boolean và chuỗi cố định. DEPLOY_TIER không được nội suy vào shell. LAB_PARAM_MARKER chứng minh cùng parameter tiêu chuẩn xuất hiện qua params, env và process environment. LAB_COLLISION_MARKER chỉ quan sát collision: params phải còn input đã chọn, còn env/process phản ánh overlay effective của stage trên Jenkins đang chạy. LOG_LEVEL là ví dụ override vô hại: stage che Pipeline và withEnv che stage; test sau closure chứng minh giá trị stage trở lại.

Để chọn cấu trúc Pipeline, xem Declarative Pipeline hoặc Scripted Pipeline. Parameter, environment và withEnv được giải thích bổ sung tại Environment & Parameters.

Secret và credentialsCopy Anchor Link

Environment không phải secret storeCopy Anchor Link

Không đặt token, mật khẩu, private key, connection string nhạy cảm hoặc secret bootstrap trong Global properties, node property, folder/job environment, Jenkinsfile, parameter hoặc file .env commit vào SCM. Những nguồn này có thể bị nhiều job, process con, plugin, log/diagnostic, workspace, backup hoặc người có quyền cấu hình quan sát.

Dùng Jenkins Credentials với credential ID có nghĩa rõ, scope folder/job nhỏ nhất và permission tối thiểu. Tách token đọc source, token publish artifact và credential deploy. Một parameter tên TARGET=production không cấp authorization và không được dùng để chọn credential ID tùy ý. Binding credential là quyết định tin cậy cả Jenkinsfile, Shared Library, agent image, process con và source kích hoạt stage.

Binding ngắn hạn và giới hạn maskingCopy Anchor Link

withCredentials của Credentials Binding nạp credential vào closure hẹp. Dùng single quote/triple single quote để shell mới mở rộng biến, tránh Groovy interpolation của secret.

withCredentials([
  string(credentialsId: 'placeholder-service-token', variable: 'SERVICE_TOKEN')
]) {
  sh '''
    set +x
    # Công cụ đã review đọc SERVICE_TOKEN từ environment.
    ./tool --use-environment-token
  '''
}

placeholder-service-token chỉ là credential ID placeholder, không phải giá trị secret. Đoạn này không phải lab chạy được nếu ID/tool chưa tồn tại. Trong Pipeline thật, binding chỉ bao quanh command cần capability; không chuyển secret thành argument, URL hoặc file output nếu công cụ có cách đọc environment/file descriptor an toàn hơn.

Tránh Groovy interpolation, echo, command-line/proc argv, URL, log, artifact, cache, test report và notification chứa secret. Không chạy PR/fork hoặc source không tin cậy trên agent có credential phát hành; áp dụng least privilege cho folder/job, identity agent, filesystem và egress. Nếu nghi ngờ lộ lọt, dừng sử dụng credential và rotate/thu hồi theo incident process; xóa log không thu hồi bản sao đã bị đọc. Xem quy trình và file binding tại Credentials trong Pipeline.

Lab sandbox: quan sát override vô hạiCopy Anchor Link

Chuẩn bị và JenkinsfileCopy Anchor Link

Lab không cần repository, credential, artifact, network hay secret. Cần controller sandbox, agent Unix online với label sandbox-linux, shell sh và quyền tạo Pipeline job. Đặt executor built-in node/controller là 0 trên môi trường production; không dùng controller thay agent để làm lab chạy nhanh hơn.

1. Tạo một Pipeline job tạm tên environment-scope-lab và dán Jenkinsfile ở phần Jenkinsfile mẫu an toàn.
2. Mở Pipeline Syntax hoặc Declarative Directive Generator trên controller để xác nhận plugin/cú pháp. Thay sandbox-linux chỉ bằng label của pool lab tách biệt.
3. Chạy lần đầu với DEPLOY_TIER=sandbox, DRY_RUN=true và giữ hai marker ở default. Đọc riêng ba dòng params.LAB_PARAM_MARKER, env.LAB_PARAM_MARKER, process.LAB_PARAM_MARKER; không thêm env, printenv hay secret để debug.
4. Ghi ba dòng LAB_COLLISION_MARKER trong stage collision. params phải biểu diễn input parameter-baseline; đối chiếu env và process với declarative-overlay để ghi nhận overlay trên Jenkins/version plugin của bạn. Không dùng quan sát này để suy ra precedence cho plugin hay parameter type khác.
5. Chạy lần hai với DEPLOY_TIER=staging và DRY_RUN=false. So sánh mode với build đầu, rồi quan sát hai dòng inside-withEnv và after-withEnv.
6. Xóa job lab khi không còn cần. Vì mẫu không checkout/tạo artifact/credential, cleanup chỉ cần xóa job sandbox theo policy của đội; không xóa history hay workspace của job khác.

Kết quả mong đợi và cleanupCopy Anchor Link

TroubleshootingCopy Anchor Link

ChecklistCopy Anchor Link

• Tôi biết biến này đến từ controller/system, agent, job/folder, parameter, Jenkinsfile, tool hay credential binding.
• Mỗi custom environment có owner, mục đích và scope hẹp nhất; global property chỉ chứa cấu hình không nhạy cảm.
• Tôi phân biệt params.NAME (input theo kiểu parameter), env.NAME (chuỗi effective) và biến process shell; biết parameter tiêu chuẩn được export lúc build bắt đầu.
• Tôi tránh collision giữa parameter, Pipeline/stage environment, withEnv và plugin injection; khi cần, tôi kiểm chứng params/env/process trên instance thay vì giả định precedence phổ quát.
• Pipeline-level, stage-level và withEnv không dùng chung tên vô tình; override tạm nằm trong closure ngắn.
• Tôi không dùng env.NAME = để sửa hằng Declarative và không dùng precedence để vượt policy/authorization.
• Built-in variable chỉ được dùng khi context thực sự có; controller/agent và workspace được xác minh trên build mới.
• Shell script dùng quote đúng, không Groovy-interpolate secret; boolean/null/path được xử lý tường minh và theo OS.
• Toolchain được quản lý bằng image/node/tool definition đã review, pin version; không sửa PATH mù quáng.
• Secret không nằm trong environment global/job, parameter, Jenkinsfile, log, proc argv, URL, artifact, cache hoặc report.
• Credential dùng ID, scope folder/job nhỏ, withCredentials ngắn, least privilege và agent tách khỏi workload không tin cậy.
• Tôi không coi masking là bảo mật; có quy trình rotate/thu hồi và cleanup khi có nghi ngờ lộ lọt.
• Lab đã xác minh precedence bằng marker vô hại, có kết quả mong đợi và cleanup rõ ràng.

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

• Using a Jenkinsfile — environment, built-in variables, parameters và credential helper.
• Pipeline Syntax — parameters — parameter được expose qua params và export thành environment variables khi build bắt đầu.
• Pipeline Syntax — Declarative environment, tools, parameters, agent và step.
• Pipeline: Basic Steps — tham chiếu withEnv và các Pipeline step cơ bản.
• Pipeline Global Variable Reference — global variables/steps khả dụng trên Jenkins instance.
• System Configuration — global properties, system configuration và phạm vi quản trị.
• Using Jenkins agents — controller, agent, executor và workspace.
• Using credentials — credential store, scope và permission.
• Credentials Binding plugin — withCredentials, masking và cảnh báo secret file/workspace.
• Jenkins Security — authorization, controller protection và vận hành bảo mật.

Đọc tiếpCopy Anchor Link