Freestyle Project

Freestyle project là job được khai báo chủ yếu bằng giao diện Jenkins. Nó nối một nguồn mã, điều kiện kích hoạt, nơi chạy, các build step và hành động sau build thành một luồng CI. Điều này nhanh cho tác vụ đơn giản, nhưng cấu hình nằm ngoài repository nên ownership, audit và tái lập cần được thiết kế có chủ đích.

Mục lụcCopy Anchor Link

• Khi nào dùng Freestyle?
  • Mô hình job và vòng đời build
  • So với Pipeline, Declarative và Job DSL
• Cấu hình qua UI
  • Bảng trường UI quan trọng
  • SCM, trigger và tham số
  • Node, label, workspace và tools
  • Build environment và build steps
  • Publishers và post-build actions
• Bảo mật và quyền vận hành
  • Credentials, masking và least privilege
  • Shell injection, đường dẫn và tham số
• Vận hành đáng tin cậy
  • Timeout, retry, retention và notification
  • Ownership, audit, export và rollback
  • Tái lập và chống configuration drift
• Di chuyển sang Jenkinsfile
  • Tiêu chí và kế hoạch chuyển đổi
  • Ví dụ Jenkinsfile an toàn
• Lab sandbox: build, test và lưu artifact
  • Chuẩn bị
  • Các bước trong UI
  • Kết quả mong đợi và dọn dẹp
• Troubleshooting
• Checklist trước khi vận hành
• Nguồn Jenkins chính thức
• Đọc tiếp

Khi nào dùng Freestyle?Copy Anchor Link

Freestyle là một project model tổng quát của Jenkins: mỗi cấu hình UI xác định một job, và mỗi lần chạy tạo một build có number, console log, workspace, kết quả và metadata riêng. Nó hợp với một repository, một chuỗi bước tuyến tính và ít nhánh điều kiện, chẳng hạn kiểm tra một script nội bộ hoặc đóng gói một artifact. Trước khi tạo job đầu tiên, xem bối cảnh controller, agent và queue tại Tổng quan về Jenkins.

Không dùng Freestyle như cách tránh quản trị quy trình. Một job có deploy, nhiều môi trường, logic điều kiện, nhiều contributor hoặc thay đổi thường xuyên sẽ sớm cần review dựa trên Git và migration sang Jenkinsfile.

Mô hình job và vòng đời buildCopy Anchor Link

Một lần chạy đi qua các thành phần sau. Một plugin có thể thêm trường UI hoặc đổi chính xác hành vi của một bước; vì vậy hãy xác nhận plugin/version trước khi copy cấu hình.

direction: down
A: "SCM revision"
B: "Trigger: webhook, poll, schedule\nhoặc Build Now"
C: "Freestyle project trên\ncontroller"
D: "Node/label khớp và có executor?" {
  shape: diamond
}
E: "Build queue"
F: "Workspace trên agent"
G: "Checkout và build steps"
H: "Test và tạo artifact/report"
I: "Publisher/post-build action"
J: "Retention, kết quả và\nnotification"

A -> B
B -> C
C -> D
D -> E: "Chưa"
E -> D
D -> F: "Có"
F -> G
G -> H
H -> I
I -> J

Sơ đồ dùng D2 và được render lúc build qua @vanhiep99w/docs-kit. Nguồn sơ đồ vẫn nằm trong MDX để review cùng nội dung.

• SCM chọn revision để checkout, thường là Git URL, branch/revision và credential đọc repository private.
• Build triggers quyết định khi nào job vào queue: webhook/plugin SCM, polling, lịch định kỳ hoặc người có quyền bấm Build Now.
• Build environment/wrappers chuẩn bị hoặc bao bọc build, ví dụ timestamp log, timeout, nạp tool, cleanup workspace hay biến môi trường. Nhiều wrapper đến từ plugin.
• Build steps thực thi công việc: Invoke Gradle, Execute shell, gọi tool/plugin hoặc script của repository.
• Publishers/post-build actions thu JUnit report, archive artifact, fingerprint, gửi notification hoặc gọi downstream job sau khi build có kết quả.
• Tools là các tool global do quản trị viên khai báo (JDK, Git, Maven, NodeJS qua plugin). Job chọn tên tool đã được chuẩn bị, không nên tự tải bản latest không kiểm soát trong mỗi run.
• Node/label route build đến agent có OS, toolchain và trust tier phù hợp. Workspace là thư mục làm việc của job trên agent, không phải kho artifact lâu dài hay ranh giới an ninh hoàn chỉnh. Xem thêm Tổng quan Jenkins Agent.

So với Pipeline, Declarative và Job DSLCopy Anchor Link

Pipeline không đồng nghĩa Declarative: Pipeline có thể là Scripted hoặc Declarative. Job DSL tạo ra job configuration; Jenkinsfile là build flow nằm cùng revision source. Một tổ chức có thể dùng Job DSL để chuẩn hóa folder/Freestyle cũ, đồng thời chuyển logic build mới sang Jenkinsfile.

Cấu hình qua UICopy Anchor Link

Tạo job tại New Item → Freestyle project. Đặt tên theo trách nhiệm và môi trường, ví dụ catalog-api-ci, thay vì tên người hoặc máy. Hạn chế người có quyền Configure: quyền này có thể thay lệnh chạy, agent được chọn và credential được job dùng.

Bảng trường UI quan trọngCopy Anchor Link

Các nhãn UI có thể khác theo plugin và phiên bản Jenkins. Nếu không thấy lựa chọn trong bảng, đừng cài plugin trực tiếp trên production chỉ để theo ví dụ; yêu cầu quản trị viên đánh giá tương thích, security advisory, license và kế hoạch rollback plugin.

SCM, trigger và tham sốCopy Anchor Link

Với Git, chọn Git trong Source Code Management, nhập URL HTTPS/SSH của repository và chọn credential đã tồn tại nếu repository private. Credential nên có quyền đọc repository đúng scope; không nhúng PAT vào URL, Execute shell, tham số hay description. Chọn branch/revision theo policy, ví dụ */main cho CI sau merge. Đừng để người kích hoạt build nhập tùy ý repository URL hoặc ref rồi checkout bằng shell: đó là chuyển quyền network/source selection sang input không kiểm soát.

Chọn trigger theo nguồn sự kiện đáng tin cậy:

• Webhook từ SCM thường phản hồi nhanh và giảm polling. Xác thực webhook ở SCM/plugin theo cấu hình tổ chức.
• Poll SCM kiểm tra thay đổi định kỳ và có thể tăng tải; dùng khi webhook không khả dụng, với lịch thận trọng.
• Build periodically phù hợp kiểm tra hoặc tác vụ độc lập với commit. Nó không thay thế trigger SCM.
• Build after other projects are built chỉ phù hợp khi dependency và điều kiện kết quả đã rõ. Tránh chuỗi job ngầm khó truy vết.

Parameterized build hữu ích cho input hữu hạn như TARGET_ENV = sandbox | staging. Dùng Choice Parameter thay vì Free-form text khi có thể. Parameter được đưa vào environment nên vẫn phải validate lại trong shell. Tìm hiểu ngữ nghĩa environment/parameters khi chuyển sang Pipeline tại Environment & Parameters.

Node, label, workspace và toolsCopy Anchor Link

Trong Restrict where this project can be run, chọn label theo năng lực và mức tin cậy, ví dụ linux && ci-sandbox. Không dùng built-in node/controller để chạy code repository; controller nên dành cho điều phối. Label không tự cấp quyền: agent vẫn cần account OS hạn chế, network policy, disk quota và cleanup phù hợp.

Workspace được Jenkins cấp dưới remote root của agent và có thể bị tái sử dụng. Không ghi vào /tmp/shared, home directory hay một path do parameter quyết định. Nếu build dùng cache, phân tách cache theo project/trust tier và tránh chia cache ghi được giữa build PR không tin cậy với release.

Chọn tool theo tên global tool do quản trị viên quản lý. Ghi version cần thiết trong description hoặc repository, ví dụ JDK 21 và Maven 3.9.x. Pin dependency bằng lockfile, pin image/toolchain theo version hoặc digest đã kiểm thử. Công việc liên quan global tools, node properties và ownership hệ thống nằm tại Cấu hình hệ thống Jenkins.

Build environment và build stepsCopy Anchor Link

Build environment/wrapper áp dụng quanh build hoặc chuẩn bị workspace. Thứ tự và sự tồn tại của các lựa chọn phụ thuộc plugin. Hai kiểm soát có giá trị thực tế là timeout hữu hạn và dọn workspace theo policy; timestamp giúp liên kết console log với sự kiện bên ngoài.

Giữ build step mỏng: gọi script đã review trong SCM thay vì nhét hàng trăm dòng shell vào UI. Script cần trả exit code khác 0 khi quality gate fail để Jenkins đánh dấu build thất bại. Ví dụ Execute shell cho một repository có ci/build.sh:

#!/usr/bin/env bash
set -eu

# `ci/build.sh` được versioning cùng source; không lấy command từ parameter.
./ci/test.sh
mkdir -p -- "$WORKSPACE/out"
printf '%s\n' "build=${BUILD_NUMBER}" > "$WORKSPACE/out/build.txt"

set -eu khiến lỗi và biến chưa đặt dừng script; không tự biến shell thành sandbox. Execute shell cần shell Unix, còn Windows dùng step/batch phù hợp và cú pháp quoting khác. Không ghi secret, command có token hoặc môi trường đầy đủ vào console để debug.

Publishers và post-build actionsCopy Anchor Link

Sau build, cấu hình publisher theo đúng artifact/report thực tế. Một workflow nhỏ, dễ quan sát là build → test → artifact/report → notification:

1. Build step checkout rồi chạy test bắt buộc; test fail trả exit code khác 0.
2. Build step tạo artifact trong một thư mục cố định dưới workspace, chẳng hạn out/.
3. Publish JUnit test result report đọc reports/*.xml; Archive the artifacts lưu out/** và chỉ fingerprint khi cần traceability.
4. Notification gửi trạng thái và link build cho owner sau khi Jenkins đã có kết quả. Tránh đưa console log hoặc artifact chưa được kiểm tra vào kênh công khai.

Chỉ archive file cần để tái sử dụng/điều tra. Artifact lớn, retention dài hoặc phát hành cần kho artifact chuyên dụng và policy riêng. Thu report và archive trước wrapper cleanup; một post-build action không nên làm build xanh lại sau khi test fail. Nội dung về report, flaky test và quality gate có tại Tự động hóa kiểm thử.

Bảo mật và quyền vận hànhCopy Anchor Link

Credentials, masking và least privilegeCopy Anchor Link

Trong Freestyle, plugin có thể bind credential vào biến môi trường hoặc file tạm cho một build step. Dùng credential ID từ store Jenkins; không ghi secret thật vào form, Git, build parameter, URL hay artifact. Chỉ cấp credential ở folder/job/environment cần nó, chỉ cho step cần nó, và dùng token có quyền tối thiểu, thời hạn/rotation theo policy.

Masking chỉ cố che chuỗi đã biết trong console log. Nó không ngăn code độc hại in secret qua biến đổi, lưu secret vào artifact, gửi qua network, hoặc process khác cùng agent đọc environment/file. Không bật set -x khi có credential; không echo environment; tách agent/pool cho workload không tin cậy và không cấp credential release cho PR chưa được tin cậy. Xem cách scope credential và binding an toàn trong Credentials trong Pipeline.

Shell injection, đường dẫn và tham sốCopy Anchor Link

Mỗi parameter, tên nhánh, webhook payload, commit message và file từ workspace đều là dữ liệu không tin cậy. Không dùng eval, command substitution từ input, sh -c "$PARAM", hay ghép input vào command có ý nghĩa shell. Không coi Choice Parameter là validation duy nhất, vì build có thể bị gọi qua API hoặc cấu hình có thể đổi.

Mẫu Execute shell dưới đây chỉ cho phép hai giá trị hữu hạn. Nó quote biến, dùng -- để kết thúc option và giữ output bên trong $WORKSPACE; không dùng nó để chọn URL SCM hay đường dẫn tùy ý.

#!/usr/bin/env bash
set -eu

case "${TARGET_ENV:-}" in
  sandbox|staging) ;;
  *) printf '%s\n' 'TARGET_ENV must be sandbox or staging' >&2; exit 64 ;;
esac

out_dir="$WORKSPACE/out/$TARGET_ENV"
mkdir -p -- "$out_dir"
printf 'target=%s\n' "$TARGET_ENV" > "$out_dir/target.txt"
./ci/package.sh --target "$TARGET_ENV" --output "$out_dir"

Không tạo path bằng ../, không glob input chưa kiểm soát, không dùng rm -rf "$PARAM", và không tin một symlink trong workspace khi thao tác file nhạy cảm. Nếu cần chọn revision, artifact hay đích deploy, map lựa chọn UI hữu hạn sang giá trị đã review trong script thay vì chấp nhận string tự do.

Vận hành đáng tin cậyCopy Anchor Link

Timeout, retry, retention và notificationCopy Anchor Link

Đặt timeout cho build hoặc step có thể treo, theo plugin wrapper đã được phê duyệt. Chọn giá trị dựa trên p95 thực tế và chừa biên nhỏ; timeout quá rộng chỉ biến treo thành queue dài. Khi timeout xảy ra, xác nhận công cụ con đã dừng và cleanup idempotent, vì process/agent mất kết nối có thể cần xử lý riêng.

Retry chỉ dành cho thao tác idempotent có lỗi tạm thời, như tải dependency từ mirror đã biết. Giới hạn attempt, log lý do và không retry mù test fail, migration database hay publish có side effect. Với flow phức tạp hơn, xem semantics của retry, timeout và kết quả build tại Xử lý lỗi và Retry.

Cấu hình Discard old builds theo nhu cầu điều tra, compliance và dung lượng: giữ số build/ngày đủ để trace artifact và incident, rồi xác nhận disk usage. Retention phải xét cả build records, console log, archived artifacts và external artifact store. Notification nên dựa vào transition hữu ích (failure mới, recovery, release) và owner rõ ràng, thay vì gửi mọi build thành spam.

Ownership, audit, export và rollbackCopy Anchor Link

UI là nguồn cấu hình hiện hành của Freestyle, nên job cần owner kỹ thuật, backup owner và mô tả mục đích/alert route. Ghi ticket hoặc pull request phê duyệt trong description/changelog nội bộ trước khi đổi SCM, label, script, trigger, credential ID, publisher hoặc retention. Hạn chế quyền Configure/Delete; quyền chạy và quyền sửa cấu hình là hai mức rủi ro khác nhau.

Jenkins lưu cấu hình item trong $JENKINS_HOME/jobs/.../config.xml. Chỉ người được ủy quyền mới export/copy XML, vì file có thể lộ URL nội bộ, credential ID, cấu trúc job hoặc metadata nhạy cảm dù không nên chứa secret thô. Lưu bản export đã được review trong kho kiểm soát truy cập, hoặc quản lý bằng Job DSL/Jenkins Configuration as Code khi phù hợp. Backup toàn JENKINS_HOME cần tính nhất quán, quyền truy cập hạn chế và restore được diễn tập; xem Backup & Restore Jenkins.

Rollback là một thay đổi có chủ đích: lưu export/bản cấu hình trước khi đổi, ghi build cuối cùng tốt và phiên bản plugin liên quan, sau đó khôi phục cấu hình đã review trong cửa sổ phù hợp. Sau rollback, chạy build sandbox/canary và đối chiếu revision, label, credential ID, artifact/report và retention; không coi import XML là đủ bằng chứng.

Tái lập và chống configuration driftCopy Anchor Link

Một build tái lập cần biết source revision, toolchain/version, dependency lockfile, agent image/OS, plugin assumptions và UI configuration đã tạo nó. Chỉ biết build number không đủ khi tool global đổi, agent được patch hoặc ai đó sửa form mà không có record.

Để giảm drift:

• giữ command, test và packaging script trong repository; chỉ để wiring tối thiểu ở UI;
• pin version plugin/tool theo policy, ghi dependency plugin của mỗi wrapper/publisher và thử trên staging trước khi nâng;
• export cấu hình sau thay đổi được phê duyệt, so sánh diff định kỳ với baseline và backup;
• theo dõi system log, Console Output và audit log mà tổ chức có để biết ai đổi gì, khi nào; xem Logs & Diagnostics;
• viết runbook rollback trước khi đổi trigger, agent pool hay post-build action có thể tác động release.

Di chuyển sang JenkinsfileCopy Anchor Link

Tiêu chí và kế hoạch chuyển đổiCopy Anchor Link

Chuyển khi job cần branch/PR-specific behavior, stage rõ ràng, review/diff bắt buộc, nhiều điều kiện/parallelism, dùng chung logic, hay khi configuration drift đã gây incident. Freestyle vẫn có thể hợp với tác vụ quản trị nhỏ, được owner kiểm soát và ít đổi; migration không phải lý do để copy nguyên shell UI vào một Jenkinsfile dài hơn.

Kế hoạch an toàn:

1. Inventory form hiện tại: SCM/ref/credential ID, trigger, label, tool version, wrappers, commands, publishers, retention và notification.
2. Đưa build/test/package commands vào script trong repository; kiểm thử script trên agent sandbox với source revision cố định.
3. Viết Jenkinsfile Declarative dùng cùng label, credentials scope hẹp, timeout, archive/report và post rõ ràng. Đọc hướng dẫn cấu trúc tại Jenkinsfile.
4. Tạo Pipeline job thử chạy từ branch migration. So sánh exit code, test count, artifact checksum, notification và thời lượng với Freestyle ở cùng commit; tránh chạy đồng thời hai job nếu chúng publish cùng đích.
5. Chuyển webhook/schedule sau khi canary đạt tiêu chí. Disable Freestyle cũ thay vì xóa ngay, giữ export và đường rollback trong khoảng retention đã thỏa thuận.

Ví dụ Jenkinsfile an toànCopy Anchor Link

Ví dụ thay một Freestyle job Linux có Choice Parameter TARGET_ENV, build script versioned, JUnit report và artifact out/. Credential chỉ xuất hiện trong stage publish giả định; không có secret thật trong file. timeout, retry và các step/plugin cần được kiểm tra trên controller.

pipeline {
  agent { label 'linux && ci-sandbox' }

  options {
    timeout(time: 20, unit: 'MINUTES')
    buildDiscarder(logRotator(numToKeepStr: '20', artifactNumToKeepStr: '10'))
    disableConcurrentBuilds()
  }

  parameters {
    choice(name: 'TARGET_ENV', choices: ['sandbox', 'staging'], description: 'Đích đã được phê duyệt')
  }

  stages {
    stage('Build and test') {
      steps {
        sh '''#!/usr/bin/env bash
          set -eu
          case "${TARGET_ENV:-}" in sandbox|staging) ;; *) exit 64 ;; esac
          ./ci/test.sh
          mkdir -p -- "$WORKSPACE/out/$TARGET_ENV"
          ./ci/package.sh --target "$TARGET_ENV" --output "$WORKSPACE/out/$TARGET_ENV"
        '''
      }
    }

    stage('Publish sandbox metadata') {
      when { expression { params.TARGET_ENV == 'sandbox' } }
      steps {
        retry(2) {
          sh './ci/publish-sandbox-metadata.sh'
        }
      }
    }
  }

  post {
    always {
      junit testResults: 'reports/*.xml', allowEmptyResults: false
      archiveArtifacts artifacts: 'out/**', fingerprint: true
      deleteDir()
    }
    failure {
      echo 'Thông báo thất bại tới kênh/owner đã được cấu hình, không kèm secret.'
    }
  }
}

retry(2) chỉ nên bao quanh script publish metadata đã được chứng minh idempotent; không dùng mẫu này cho publish release có thể tạo bản ghi trùng. Với staging/production, tách trust tier, approval và credential scope theo policy thay vì chỉ đổi giá trị parameter.

Lab sandbox: build, test và lưu artifactCopy Anchor Link

Lab này chỉ tạo file text trong workspace của agent, không checkout repository private, không dùng credential, không gọi network và không xóa dữ liệu ngoài workspace. Cần một Jenkins lab/local, một agent Linux label ci-sandbox, Git plugin không bắt buộc cho lab này, cùng JUnit plugin nếu muốn publish report. Không chạy trên controller production.

Chuẩn bịCopy Anchor Link

Tạo một Freestyle project tên freestyle-sandbox-demo. Trong General, đặt description có owner lab và bật This project is parameterized với Choice Parameter TARGET_ENV: sandbox, staging. Trong Restrict where this project can be run, nhập ci-sandbox. Nếu agent không có label này, dừng ở đây và nhờ quản trị viên cấp sandbox; không đổi label sang controller.

Các bước trong UICopy Anchor Link

1. Trong Build Environment, bật timeout 5 phút nếu wrapper đã có. Không cần credential hay SCM cho lab.
2. Thêm Build Step → Execute shell, rồi dán script vô hại sau:

#!/usr/bin/env bash
set -eu

case "${TARGET_ENV:-}" in sandbox|staging) ;; *) exit 64 ;; esac
mkdir -p -- "$WORKSPACE/out" "$WORKSPACE/reports"
printf 'environment=%s\n' "$TARGET_ENV" > "$WORKSPACE/out/result.txt"
printf '%s\n' '<testsuite name="sandbox" tests="1" failures="0"><testcase name="writes-result"/></testsuite>' \
  > "$WORKSPACE/reports/sandbox.xml"

3. Thêm Post-build Action → Publish JUnit test result report với pattern reports/*.xml.
4. Thêm Post-build Action → Archive the artifacts với pattern out/**; bỏ chọn archive empty artifacts nếu UI có lựa chọn này.
5. Lưu và bấm Build with Parameters, chọn sandbox. Mở build vừa tạo, đọc Console Output, Test Result và Artifacts.

Kết quả mong đợi và dọn dẹpCopy Anchor Link

Build thành công trên agent ci-sandbox. Console không in secret; JUnit hiển thị 1 test pass; Artifact có out/result.txt với environment=sandbox. Nếu report hoặc artifact không xuất hiện, kiểm tra pattern và đường dẫn tương đối với workspace trước khi chạy lại.

Sau lab, xóa artifact/build records theo retention của lab và chọn Delete Project chỉ khi project này không còn cần làm evidence đào tạo. Nếu không có quyền xóa hoặc retention được quản lý tập trung, disable project và báo owner lab. Không tự xóa workspace của agent bằng path shell; cleanup phải theo policy Jenkins/agent.

TroubleshootingCopy Anchor Link

Đọc Console Output cùng build number, revision, agent và thời điểm trước khi sửa. Để thu thập log/controller diagnostics có kiểm soát, xem Logs & Diagnostics.

Checklist trước khi vận hànhCopy Anchor Link

• Owner, backup owner, mục đích và kênh notification đã ghi trong description/runbook.
• SCM URL, ref và credential read-only được review; không có token trong UI/script/log.
• Trigger không tạo build trùng và parameter được giới hạn, validate lại trong script.
• Label route đúng agent/trust tier; controller không nhận build; workspace/cache có cleanup policy.
• Toolchain, plugin/wrapper/publisher assumptions và dependency version đã được xác nhận trên Jenkins LTS mục tiêu.
• Build step gọi script versioned, trả exit code đúng; không có eval, input command hoặc path không kiểm soát.
• Credential scope hẹp, masking không bị hiểu là boundary và PR không tin cậy không nhận secret.
• Report/artifact được thu trước cleanup; retention, fingerprint và notification phù hợp policy/dung lượng.
• Timeout/retry có giới hạn, side effect được đánh giá idempotent và có owner xử lý failure.
• Export/baseline, audit evidence, canary và rollback path đã tồn tại trước thay đổi quan trọng.

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

• Freestyle project
• Using Jenkins
• Pipeline
• Jenkinsfile
• Managing Nodes
• Using credentials
• Securing Jenkins
• Jenkins plugins

Đọc tiếpCopy Anchor Link