Jenkins CLI & HTTP Remote API

Jenkins có web UI tiện cho con người, còn CLI và HTTP API phù hợp khi script hoặc hệ thống khác cần lặp lại một thao tác. Chúng không phải một API giao dịch chung: endpoint, permission, dữ liệu trả về và hành vi retry phụ thuộc Jenkins core, cấu hình authorization, phiên bản và đôi khi plugin.

Mục lụcCopy Anchor Link

• Chọn đúng giao diện tự động hóa
• Mô hình request và ranh giới tin cậy
• Xác thực, quyền và CSRF
  • Giữ token ngoài URL, history, argv và log
  • Quyền tối thiểu
  • Crumb cho request thay đổi
• Jenkins CLI
  • Kết nối HTTP(S), WebSocket và SSH
  • Kiểm tra chỉ đọc
• HTTP Remote API chỉ đọc
  • JSON, tree, depth và cửa sổ dữ liệu
  • URL encoding, status và timeout
• Mutation có kiểm soát
  • Trigger build không nhân đôi
• Lab sandbox
  • Chuẩn bị và kiểm tra chỉ đọc
  • Một mutation tùy chọn
  • Kết quả và cleanup
• Vận hành an toàn và tương thích
• Troubleshooting
• Checklist trước khi automation
• Nguồn Jenkins chính thức
• Đọc tiếp

Chọn đúng giao diện tự động hóaCopy Anchor Link

Bốn khái niệm dưới đây thường bị gọi chung là “Jenkins API”, nhưng chúng có ranh giới khác nhau.

Quy ước thực tế là tách automation thành hai đường. Read-only chỉ quan sát, ví dụ lấy version, job, build và queue. Mutating tạo build, đổi config hoặc xóa resource; nó cần owner, phạm vi job/folder rõ ràng, xác nhận và audit. Đừng thay thế UI bằng cách scrape HTML; dùng CLI hoặc endpoint tài liệu hóa của core/plugin.

Mô hình request và ranh giới tin cậyCopy Anchor Link

direction: right
client: Script / CLI user
proxy: Reverse proxy + TLS
controller: "Jenkins controller\nauthz + crumb + audit"
work: Job / queue / agent
client -> proxy: HTTPS, auth, timeout
proxy -> controller: Private HTTP(S)
controller -> client: Status, JSON, CLI output
controller -> work

Client chỉ gọi URL HTTPS canonical của controller. Reverse proxy kết thúc TLS hoặc chuyển tiếp TLS, áp dụng giới hạn ở edge và không để upstream Jenkins/port controller lộ trực tiếp ra Internet. Proxy phải hỗ trợ upload, redirect và WebSocket khi CLI/agent cần chúng; đặt timeout đủ lớn cho endpoint hợp lệ nhưng không vô hạn. Cấu hình URL public, forwarded headers và TLS nhất quán trước khi debug API; xem Jenkins sau Reverse Proxy và TLS.

Không biến Jenkins thành endpoint công khai chỉ để webhook hoặc script truy cập. Giới hạn network bằng VPN, private network, firewall/security group hoặc identity-aware proxy; allowlist client khi phù hợp. Rate limit ở proxy bảo vệ controller khỏi polling dày đặc, nhưng không được che mất audit log hoặc làm retry tạo side effect.

Xác thực, quyền và CSRFCopy Anchor Link

Với HTTP/CLI qua HTTP(S), dùng tài khoản Jenkins riêng cho automation và API token của tài khoản đó. API token thay cho password; rotation/revoke theo chính sách tổ chức. CLI cũng có thể dùng transport WebSocket khi controller hỗ trợ, hoặc SSH khi Jenkins đã bật SSH CLI và user đã đăng public key. Transport không thay thế authorization: cùng user vẫn chỉ có quyền Jenkins được cấp.

Giữ token ngoài URL, history, argv và logCopy Anchor Link

Không đặt token trong URL query/userinfo, shell history, curl -u user:token, command line/process argv, output debug, artifact, ticket, log hoặc repository. Biến môi trường cũng có thể bị process con, diagnostic dump hoặc log CI đọc được; dùng secret store của runner và file credential tạm có quyền đọc hạn chế khi công cụ hỗ trợ.

Ví dụ dưới đây dùng --netrc-file để token không xuất hiện trong command line. File được hệ thống secret tạo ngoài repo, permission 0600, và hostname phải khớp JENKINS_URL:

machine jenkins.example.invalid
login <jenkins-automation-user>
password <api-token-from-secret-store>

Thiết lập biến không chứa secret trong shell hiện tại:

export JENKINS_URL='https://jenkins.example.invalid/jenkins'
export JENKINS_AUTH_FILE="$HOME/.config/jenkins/automation.netrc"

Không dùng set -x trong script có request xác thực. CI nên mask secret, tắt command echo quanh bước nhạy cảm, giới hạn ai xem build log và xóa credential file tạm sau job.

Quyền tối thiểuCopy Anchor Link

Permission do authorization strategy và folder/job quyết định; không cấp Overall/Administer cho một script chỉ để “hết 403”. Mức tối thiểu điển hình là:

CLI command tự kiểm tra permission riêng; help hoặc who-am-i có thể thành công trong khi command khác bị từ chối. Plugin có thể đưa thêm permission. Xác nhận bằng một service account trong sandbox, không suy ra từ tài khoản administrator.

Crumb cho request thay đổiCopy Anchor Link

Jenkins dùng CSRF protection (crumb) để bảo vệ request thay đổi trạng thái. Khi xác thực bằng API token, Jenkins core hiện đại miễn crumb cho API request; tuy vậy client phải không giả định mọi controller, reverse proxy, SSO bridge hay plugin đều xử lý giống nhau. Với session/cookie hoặc password authentication, lấy crumb trước POST và gửi lại header do response chỉ định.

crumb_json=$(curl --fail-with-body --silent --show-error \
  --connect-timeout 5 --max-time 20 \
  --netrc-file "$JENKINS_AUTH_FILE" \
  "$JENKINS_URL/crumbIssuer/api/json")

crumb_field=$(printf '%s' "$crumb_json" | jq -r '.crumbRequestField')
crumb_value=$(printf '%s' "$crumb_json" | jq -r '.crumb')
test "$crumb_field" != null && test "$crumb_value" != null

Không in crumb_json; crumb không thay quyền xác thực. Nếu endpoint trả 403 No valid crumb dù token hợp lệ, kiểm tra base URL/proxy, auth method và policy/controller trước khi quyết định thêm crumb. Không tắt global CSRF protection để chữa lỗi một script.

Jenkins CLICopy Anchor Link

Tải jenkins-cli.jar từ chính controller qua URL như $JENKINS_URL/jnlpJars/jenkins-cli.jar, kiểm tra theo quy trình supply-chain của tổ chức, rồi giữ artifact/version cùng controller mà nó phục vụ. java -jar jenkins-cli.jar help trên controller là danh mục command và usage đáng tin cậy nhất; command khả dụng thay đổi theo core và plugin.

Kết nối HTTP(S), WebSocket và SSHCopy Anchor Link

CLI HTTP(S) dùng URL controller và API token. WebSocket tránh yêu cầu full-duplex HTTP truyền thống khi proxy cho phép upgrade WebSocket; dùng -webSocket nếu controller/đường đi đã hỗ trợ. Đừng bật tùy chọn chỉ vì một bài mẫu dùng nó: kiểm tra CLI help, controller LTS và proxy trước.

# HTTP(S) CLI; file auth chứa <user>:<api-token>, không commit file này.
java -jar jenkins-cli.jar -s "$JENKINS_URL" \
  -auth @"$HOME/.config/jenkins/cli-auth" who-am-i

# Cùng lệnh qua WebSocket khi Jenkins và reverse proxy đã hỗ trợ.
java -jar jenkins-cli.jar -s "$JENKINS_URL" -webSocket \
  -auth @"$HOME/.config/jenkins/cli-auth" version

cli-auth phải nằm ngoài repository, permission 0600, chỉ gồm <jenkins-user>:<api-token>. Cú pháp -auth @file giữ secret ra khỏi argv, nhưng đường dẫn file và tên user vẫn có thể hiện trong log; không log nội dung file.

SSH CLI là phương án riêng, không phải SSH agent. Nó chỉ dùng được khi administrator đã bật SSH CLI, công khai SSH endpoint/port phù hợp và tài khoản Jenkins có public key được cấu hình. Ví dụ minh họa, thay mọi placeholder theo endpoint Jenkins công bố:

ssh -i "$HOME/.ssh/jenkins_cli_ed25519" \
  -p '<jenkins-cli-ssh-port>' \
  '<jenkins-user>@jenkins.example.invalid' version

Không tự mở SSH port qua Internet. Xác minh host key, giữ private key trong secret store/SSH agent và áp dụng cùng permission Jenkins cho user SSH. Nếu controller chỉ công bố HTTP(S) CLI, không suy diễn một SSH port từ port agent hoặc port hệ điều hành.

Kiểm tra chỉ đọcCopy Anchor Link

Hai lệnh nhỏ này xác nhận URL, transport, authentication và authorization mà không tạo build:

java -jar jenkins-cli.jar -s "$JENKINS_URL" \
  -auth @"$HOME/.config/jenkins/cli-auth" who-am-i

java -jar jenkins-cli.jar -s "$JENKINS_URL" \
  -auth @"$HOME/.config/jenkins/cli-auth" version

Kết quả mong đợi là danh tính service account (không phải token) và version controller. Đặt -- hoặc quote cẩn thận cho input do người dùng cung cấp nếu command hỗ trợ argument; không ghép input vào shell string.

HTTP Remote API chỉ đọcCopy Anchor Link

HTTP Remote API biểu diễn object Jenkins theo URL resource: controller/view có $JENKINS_URL/api/json, một job có $JENKINS_URL/job/<job-name>/api/json, folder lồng nhau có nhiều đoạn /job/<folder>/job/<job>. JSON là lựa chọn thông dụng cho script; XML hoặc Python representation cũng có thể có. Response model không phải schema versioned cứng: chỉ đọc field cần thiết và chịu được field mới/mất.

JSON, tree, depth và cửa sổ dữ liệuCopy Anchor Link

Không lấy toàn bộ controller rồi lọc ở client. tree chọn field cần dùng, depth mở rộng model theo cấp và range {start,end} tạo một cửa sổ phần tử trong danh sách. curl --get --data-urlencode bảo đảm các ký tự [], ,, {} trong tree được URL-encode thay vì tự nối query string.

# Chỉ liệt kê tên và URL job mà account được phép thấy.
curl --fail-with-body --silent --show-error \
  --connect-timeout 5 --max-time 20 \
  --netrc-file "$JENKINS_AUTH_FILE" \
  --get "$JENKINS_URL/api/json" \
  --data-urlencode 'tree=jobs[name,url]'

# Một cửa sổ 5 build mới trong response của job placeholder.
JOB_PATH='job/example-readonly-job'
curl --fail-with-body --silent --show-error \
  --connect-timeout 5 --max-time 20 \
  --netrc-file "$JENKINS_AUTH_FILE" \
  --get "$JENKINS_URL/$JOB_PATH/api/json" \
  --data-urlencode 'tree=builds[number,url,result,building]{0,5}'

Range trong tree là giới hạn dữ liệu response, không phải cursor giao dịch. Khi cần quét dài, dùng các cửa sổ nhỏ, lưu watermark bền vững (ví dụ build number đã xử lý), chấp nhận dữ liệu thay đổi giữa hai request và không mặc định depth=2 sẽ rẻ. Kiểm tra tree trên Jenkins sandbox vì plugin/job type có thể bổ sung field hoặc list khác.

Transcript dưới đây là minh họa tĩnh, không gọi Jenkins. Credential header được lược bỏ; request thực tế vẫn cần authentication và quyền đọc như phần trên. Dữ liệu, tên job và kết quả lỗi chỉ là mẫu, không phải schema bảo đảm của mọi controller.

{
  "jobs": [
    {
      "name": "example-readonly-job",
      "url": "https://jenkins.example.invalid/jenkins/job/example-readonly-job/"
    }
  ]
}

Access denied: kiểm tra Overall/Read và scope job theo policy sandbox. Body thực tế có thể khác.

URL encoding, status và timeoutCopy Anchor Link

Tên job/folder chứa space, /, % hoặc Unicode phải được encode mỗi path segment, không encode cả URL hay dùng tên hiển thị chưa chuẩn hóa. Với job lồng nhau, tạo đúng các segment /job/<encoded-name>; không ghép input chưa encode vào URL. Encode query bằng --data-urlencode như trên.

Luôn đặt --connect-timeout và --max-time. curl --fail-with-body biến HTTP 4xx/5xx thành lỗi nhưng vẫn cho body chẩn đoán có kiểm soát; không ghi body có thể chứa metadata nhạy cảm ra log dùng chung. Phân loại response trước khi retry:

Dùng exponential backoff có jitter và giới hạn tổng thời gian. Poll queue/build chậm dần thay vì mỗi giây; ghi request ID, endpoint đã được che bớt và status vào audit log, không ghi auth header/token hoặc full response mặc định.

Mutation có kiểm soátCopy Anchor Link

Mutation nên chạy trong change window hoặc workflow có owner. Trước POST, script cần xác nhận environment/job, đọc trạng thái hiện tại, in ý định không nhạy cảm và yêu cầu xác nhận tương tác (trừ khi CI đã có approval/audit tương đương). Chỉ gọi endpoint của job cụ thể, không dùng tài khoản có quyền toàn cục.

Trigger build không nhân đôiCopy Anchor Link

POST .../buildWithParameters có thể trả thành công sau khi controller đã nhận request nhưng client lại timeout. Jenkins Remote API không cung cấp generic idempotency key cho mọi trigger. Vì vậy retry POST tự động sau một timeout có thể tạo hai build.

Thiết kế job sandbox để nhận parameter REQUEST_ID và lưu/kiểm tra giá trị đó ở một nơi bền vững mà job kiểm soát (ví dụ record của hệ thống đích). Khi request cùng ID đã được xử lý, job phải thoát thành công mà không làm lại side effect. Đó là idempotency ở workflow, không phải thuộc tính mặc định của Jenkins. Trong script client, sau POST mơ hồ chỉ retry các GET quan sát queue/build; điều tra trước khi trigger lại.

Ví dụ sau chỉ áp dụng cho job parameterized đã được owner phê duyệt. Nó lấy crumb để tương thích cả deployment yêu cầu crumb; API-token authentication thường được miễn crumb ở Jenkins core hiện đại. REQUEST_ID là placeholder do caller tạo một lần và giữ ổn định khi quan sát lại, không tự sinh ID mới trong vòng retry.

#!/usr/bin/env bash
set -euo pipefail

: "${JENKINS_URL:?set a sandbox base URL}"
: "${JENKINS_AUTH_FILE:?set a protected netrc path}"
JOB_PATH='job/example-controlled-job'
REQUEST_ID='change-<approved-ticket>-<unique-id>'

printf 'Will trigger %s with REQUEST_ID=%s on %s\n' \
  "$JOB_PATH" "$REQUEST_ID" "$JENKINS_URL"
read -r -p 'Type TRIGGER to continue: ' confirmation
test "$confirmation" = 'TRIGGER'

crumb_json=$(curl --fail-with-body --silent --show-error \
  --connect-timeout 5 --max-time 20 --netrc-file "$JENKINS_AUTH_FILE" \
  "$JENKINS_URL/crumbIssuer/api/json")
crumb_field=$(printf '%s' "$crumb_json" | jq -r '.crumbRequestField')
crumb_value=$(printf '%s' "$crumb_json" | jq -r '.crumb')
test "$crumb_field" != null && test "$crumb_value" != null

curl --fail-with-body --silent --show-error \
  --connect-timeout 5 --max-time 20 --netrc-file "$JENKINS_AUTH_FILE" \
  -X POST -H "$crumb_field: $crumb_value" \
  --data-urlencode "REQUEST_ID=$REQUEST_ID" \
  "$JENKINS_URL/$JOB_PATH/buildWithParameters"

printf 'Trigger submitted. Do not retry this POST on a timeout; poll queue/build with GET.\n'

curl chỉ gửi token từ netrc file; crumb header là tạm thời và không được ghi log. Production client nên lấy response header Location của queue khi có, tương quan nó với REQUEST_ID, rồi poll URL đó bằng exponential backoff có giới hạn. Không được coi connection timeout là bằng chứng không có build nào được schedule.

Lab sandboxCopy Anchor Link

Lab này không dùng Jenkins production, không cần tạo/delete job và không in secret. Cần một controller local/isolated đã có service account chỉ đọc, cùng một job có sẵn tên example-readonly-job. Mutation là tùy chọn và chỉ dùng job disposable đã được chuẩn bị trước.

Chuẩn bị và kiểm tra chỉ đọcCopy Anchor Link

1. Đặt JENKINS_URL là HTTPS URL sandbox và để netrc/CLI auth file ngoài repository, quyền 0600.
2. Tải CLI jar từ sandbox; không tái dùng jar không rõ nguồn.
3. Chạy who-am-i, version và hai lệnh JSON ở phần trước.
4. Ghi lại version, service account và status code vào ghi chú lab; không ghi token hoặc raw auth header.

# Ví dụ kiểm tra permission của file secret trên Linux/macOS.
chmod 600 "$JENKINS_AUTH_FILE" "$HOME/.config/jenkins/cli-auth"
java -jar jenkins-cli.jar -s "$JENKINS_URL" \
  -auth @"$HOME/.config/jenkins/cli-auth" who-am-i

Một mutation tùy chọnCopy Anchor Link

Chỉ làm bước này khi owner đã tạo sẵn example-controlled-job, account có đúng Job/Build tại job đó và job có contract REQUEST_ID idempotent. Điền approved ticket/unique ID, chạy script ở phần trước, gõ TRIGGER, rồi poll queue/build bằng GET. Không thử endpoint create/delete/disable job trong lab này.

Kết quả và cleanupCopy Anchor Link

Kết quả chỉ đọc mong đợi: CLI trả user/version; JSON chỉ chứa field được yêu cầu; request sai quyền trả 403 thay vì thành công. Kết quả mutation mong đợi: một request được audit, tối đa một build nhận REQUEST_ID, và workflow chứng minh cùng ID không lặp side effect.

Cleanup không destructive: xóa file response tạm và shell history entry nếu shell hỗ trợ, hủy/revoke token chỉ khi token đó được tạo riêng cho lab, đóng terminal và để owner xử lý build/job theo policy. Không xóa job, build history, queue item hoặc credential dùng chung. Giữ log đã redaction theo retention policy để đối chiếu audit.

Vận hành an toàn và tương thíchCopy Anchor Link

• Đặt rate limit, WAF/proxy policy và TLS ở edge; vẫn allow method/path cần thiết cho CLI WebSocket và API đã duyệt. Test redirect, context path và WebSocket sau mỗi thay đổi proxy.
• Dùng timeout phân biệt connect/total, retry GET với backoff+jitter và giới hạn attempt. Với POST, chỉ retry khi endpoint/workflow có idempotency đã kiểm chứng; nếu không, tìm queue/build/audit trước.
• Ghi audit event gồm service account, thời điểm, ticket, action, resource, REQUEST_ID, status và correlation ID. Redact token, cookie, crumb, auth header, request body nhạy cảm và full response.
• Đọc controller/system log khi cần điều tra authz, crumb hoặc queue; không tăng log level hoặc dump credential trên production chỉ để debug. Theo dõi capacity, queue và lỗi API bằng Monitoring Jenkins, và liên hệ log với Jenkins logs.
• Nâng Jenkins LTS và plugin theo change management. Kiểm tra CLI help, endpoint api/json, authentication/crumb behavior và plugin integrations trong sandbox sau nâng cấp. Static code block ở trang này không chứng minh controller runtime có plugin, job parameter, SSH CLI hay WebSocket.

TroubleshootingCopy Anchor Link

Checklist trước khi automationCopy Anchor Link

• URL là HTTPS canonical sau reverse proxy; upstream controller không public.
• Service account riêng, API token/SSH key được lưu trong secret store hoặc file 0600, ngoài repo.
• Token không có trong URL, history, argv, log, artifact, ticket hoặc source code; tracing đã redact.
• Đã kiểm tra Overall/Read và đúng job/folder permission tối thiểu trên sandbox.
• CLI transport (HTTP(S), WebSocket hoặc SSH) được controller và proxy hỗ trợ, không suy đoán từ ví dụ.
• GET dùng tree/range hợp lý, URL được encode theo segment, timeout/backoff/rate limit được đặt.
• POST có owner, confirmation/approval, crumb handling và audit/correlation; workflow có REQUEST_ID idempotent nếu cần retry/khôi phục.
• HTTP status, 403 crumb/authz, timeout và 429 có nhánh xử lý rõ; POST mơ hồ không bị retry mù.
• Endpoint/field/plugin được test lại sau mỗi nâng Jenkins LTS hoặc plugin.

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

• Jenkins CLI
• Jenkins Remote Access API
• API token
• CSRF Protection
• Jenkins permissions
• Reverse proxy

Đọc tiếpCopy Anchor Link