Job đầu tiên

Một Freestyle job là cách nhanh nhất để làm quen với vòng đời build: Jenkins lấy source code, chạy một hoặc nhiều build step, rồi giữ console log và trạng thái. Trong bài này, kết quả quan sát được là revision đã checkout và file jenkins-lab-result.txt được tạo trong workspace.

Mục lụcCopy Anchor Link

• Bạn sẽ làm gì?
• Trước khi bắt đầu
  • Điều kiện của lab
  • Hiểu các mục trên giao diện
• Lab: chạy Freestyle job đầu tiên
  • Chuẩn bị source và xác nhận branch
  • Tạo job từ New Item
  • Cấu hình SCM Git và credential
  • Thêm build step có kết quả quan sát được
  • Lưu, chạy Build Now và xác nhận kết quả
• Đọc Console Output và trạng thái build
  • Đọc log theo thứ tự
  • Ý nghĩa các trạng thái
• Tạo failure có chủ đích và khắc phục
• Từ lab đến production
  • Bảo vệ source, credential và agent
  • Khi nào chuyển sang Pipeline as Code
• Checklist hoàn thành
• Nguồn Jenkins chính thức
• Đọc tiếp

Bạn sẽ làm gì?Copy Anchor Link

Sau lab, bạn có thể:

• tạo một job qua New Item và nhận ra vì sao chọn Freestyle project;
• cấu hình Source Code Management → Git để Jenkins checkout một revision;
• chọn đúng agent, shell và tool Git cho build step;
• khởi chạy job bằng Build Now, đối chiếu output với lệnh đã cấu hình, rồi phân biệt kết quả SUCCESS và FAILURE;
• xử lý một lỗi build có chủ đích mà không cần đoán hoặc thay đổi credential bừa bãi.

Trước khi bắt đầuCopy Anchor Link

Điều kiện của labCopy Anchor Link

Bạn cần các điều kiện sau:

• URL Jenkins có thể truy cập và tài khoản có quyền Create cùng Configure job.
• Một agent tin cậy có ít nhất một executor Online. Agent Linux cần sh và Git CLI; agent Windows cần cmd.exe và Git CLI trong PATH.
• Git plugin đã được cài và bật để mục Git xuất hiện trong Source Code Management. Đây là plugin, không phải điều được suy ra chỉ từ Jenkins core.
• Agent được chọn có thể truy cập HTTPS tới github.com. Repository lab là public nên không cần credential.

Nếu bạn đang học local và chưa có controller, hãy bắt đầu bằng chạy Jenkins bằng Docker. Xem Yêu cầu hệ thống để kiểm tra Java, network và dung lượng. Khái niệm controller, agent, executor và workspace được giải thích sâu hơn tại Kiến trúc Jenkins.

Hiểu các mục trên giao diệnCopy Anchor Link

Freestyle job không đồng nghĩa với Pipeline. Job là đơn vị Jenkins theo dõi; Freestyle là một kiểu job có cấu hình UI. Pipeline thường lưu quy trình trong Jenkinsfile cùng repository. Để đặt lab vào bối cảnh CI/CD, xem Nền tảng CI/CD.

Lab: chạy Freestyle job đầu tiênCopy Anchor Link

Luồng lab là: Jenkins checkout một repository công khai → agent chạy lệnh → Console Output in revision và file kết quả → build kết thúc SUCCESS.

direction: down
repo: Repository Git công khai {icon: ../../assets/d2/git.svg}
workspace: Workspace trên agent
command: Execute shell / batch
result: Console Output + trạng thái build
repo -> workspace: Checkout
workspace -> command -> result

Chuẩn bị source và xác nhận branchCopy Anchor Link

Dùng repository công khai https://github.com/jenkins-docs/simple-java-maven-app.git của tổ chức Jenkins. Lab chỉ xác nhận checkout và tạo output; không chạy Maven, nên agent không cần JDK hay Maven riêng cho ví dụ này.

Trước khi điền branch vào Jenkins, chạy lệnh sau trên máy có Git và internet. Nó in branch mặc định của remote; dùng đúng tên branch sau refs/heads/ cho bước cấu hình tiếp theo.

git ls-remote --symref https://github.com/jenkins-docs/simple-java-maven-app.git HEAD

Ví dụ output có thể chứa ref: refs/heads/master HEAD. Khi đó branch specifier là */master. Nếu remote đổi branch mặc định, không đoán main hoặc master: dùng tên lệnh vừa trả về.

Tạo job từ New ItemCopy Anchor Link

Cấu hình SCM Git và credentialCopy Anchor Link

Trong trang Configure, tìm Source Code Management, chọn Git, rồi điền:

• Repository URL: https://github.com/jenkins-docs/simple-java-maven-app.git
• Credentials: để - none -, vì đây là repository public
• Branches to build: */<branch-vừa-xác-minh>, ví dụ */master

Sau khi nhập URL, Jenkins có thể hiển thị lỗi validation nếu Git plugin chưa có, agent không có Git CLI, URL/branch sai hoặc agent không tới được Git host. Chưa chuyển sang credential chỉ để chữa mọi lỗi checkout: với repo public, credential không phải điều kiện cần.

Khi repository là privateCopy Anchor Link

Repository private cần một credential đọc repository có quyền tối thiểu. Tạo credential tại Manage Jenkins → Credentials theo kiểu URL của repository: token đọc-only với Username with password cho HTTPS, hoặc SSH Username with private key cho SSH. Lưu private key hoặc token trong Jenkins Credentials, không lưu trong repository, trường URL, shell command hay console log.

Chọn scope hẹp nhất mà job thực sự nhìn thấy:

• Nếu Jenkins có credential provider theo folder, đặt job trong folder và dùng credential scope của folder để không cấp cho job ngoài folder.
• Nếu chỉ có scope mặc định, credential chọn cho SCM checkout phải ở scope job có thể dùng; System scope chỉ dành cho Jenkins nội bộ, không dùng cho checkout của build job. Global scope cho nhiều job nhìn thấy hơn, nên chỉ dùng khi không có scope hẹp hơn và giới hạn quyền cấu hình job.
• Credential chỉ cần quyền đọc đúng repository/branch. Dùng deploy key hoặc token riêng cho CI, giới hạn read-only, đặt expiry/rotation theo chính sách và thu hồi khi job không còn dùng.

Sau đó chọn credential từ danh sách Credentials của chính job. Không gõ token vào Repository URL như https://token@host/org/repo.git; URL đó có thể lộ trong cấu hình, lịch sử hoặc log.

Thêm build step có kết quả quan sát đượcCopy Anchor Link

Trong Build Steps, chọn loại lệnh khớp hệ điều hành của agent. Đây là build step tiêu chuẩn của Freestyle job, nhưng sự có mặt của shell, cmd.exe và Git CLI là phụ thuộc của agent. Không chọn một build step/plugin khác nếu bạn chưa cài và hiểu nó.

set -eu
printf 'Freestyle build #%s\n' "$BUILD_NUMBER"
printf 'workspace=%s\n' "$WORKSPACE"
printf 'revision='
git rev-parse --short HEAD
printf 'build=%s\n' "$BUILD_NUMBER" > jenkins-lab-result.txt
test -s jenkins-lab-result.txt
cat jenkins-lab-result.txt

Bạn có thể tùy chọn thêm Post-build Actions → Archive the artifacts với pattern jenkins-lab-result.txt để tải file từ trang build. Tính khả dụng, giao diện và report bổ sung tùy phiên bản Jenkins hoặc plugin; lab không phụ thuộc vào artifact/report vì Console Output đã đủ để xác minh lệnh chạy.

Lưu, chạy Build Now và xác nhận kết quảCopy Anchor Link

Freestyle build #1
workspace=/.../workspace/freestyle-first-job
revision=abc1234
build=1
Finished: SUCCESS

Đọc Console Output và trạng thái buildCopy Anchor Link

Đọc log theo thứ tựCopy Anchor Link

Console Output là bản ghi theo thời gian. Đọc từ trên xuống và dừng ở lỗi có nguyên nhân đầu tiên, không chỉ ở dòng cuối Finished: FAILURE:

1. Tìm phần Jenkins gán executor và workspace. Nếu không có phần này, build có thể vẫn đang chờ trong queue.
2. Tìm checkout Git. Xác nhận URL remote, branch/revision và thông báo lỗi xác thực hoặc git không tìm thấy.
3. Tìm dòng + trên shell Unix, hoặc lệnh được echo trên Windows. Nó cho biết lệnh nào Jenkins thực sự chạy.
4. Đọc exit code, thông báo ngay trước nó và trạng thái cuối. Sửa nguyên nhân nhỏ nhất, lưu lại rồi chạy build mới để xác minh.

Không in token để “debug”. Nếu cần xác minh credential private repository, kiểm tra ID/tên credential được chọn, quyền đọc repository, host key/TLS và log đã được Jenkins che bớt; không sao chép secret từ Jenkins sang terminal.

Ý nghĩa các trạng tháiCopy Anchor Link

Màu và biểu tượng có thể thay đổi theo giao diện hoặc theme; ưu tiên chữ trạng thái, Console Output, thời lượng và revision thay vì chỉ nhìn màu.

Tạo failure có chủ đích và khắc phụcCopy Anchor Link

Một lab tốt phải cho bạn thấy tín hiệu đỏ có nghĩa gì. Trong build step đang dùng, thay dòng tạo file bằng một lệnh chủ động thất bại, sau đó chọn Save và Build Now.

printf 'build=%s\n' "$BUILD_NUMBER" > jenkins-lab-result.txt

false

Build mới phải kết thúc FAILURE. Trong Console Output, tìm false hoặc exit /b 1, rồi dòng exit code. Sau khi quan sát, khôi phục đúng lệnh tạo jenkins-lab-result.txt, Save và chạy lại. Build kế tiếp phải trở về SUCCESS.

Các lỗi thường gặp khác và cách khoanh vùng:

Từ lab đến productionCopy Anchor Link

Bảo vệ source, credential và agentCopy Anchor Link

Lab dùng source công khai và lệnh vô hại; production có ranh giới khác. Áp dụng các nguyên tắc sau trước khi cho job truy cập repository riêng, registry hoặc hạ tầng phát hành:

• Không hard-code password, token, deploy key hay URL chứa token trong job config, repository, command line hoặc log. Dùng Jenkins Credentials với quyền tối thiểu, đúng scope và rotation.
• Để credential đọc repository riêng tách biệt với credential deploy. Job chỉ checkout code không cần token ghi repository, cloud admin hay production.
• Chạy source không tin cậy trên agent cô lập, ngắn hạn khi có thể. Không chạy source từ pull request/fork không tin cậy trên controller hoặc agent có secret giá trị cao.
• Khai báo toolchain của agent rõ ràng: version Git, JDK, Node.js, Maven hoặc tool dự án. Execute shell chỉ chạy command; nó không cài tool cho bạn.
• Giữ branch/revision, Console Output, artifact và retention đủ để truy vết. Nếu publish test report hoặc dùng build step đặc biệt, đọc yêu cầu của plugin, khả năng agent và quyền truy cập trước khi thêm.

Khi nào chuyển sang Pipeline as CodeCopy Anchor Link

Freestyle phù hợp để học luồng cơ bản hoặc duy trì một tác vụ nhỏ, ổn định. Hãy chuyển sang Pipeline as Code khi quy trình có nhiều stage như test, package và deploy; cần review thay đổi CI cùng pull request; cần điều kiện, retry, input/approval, agent theo stage hoặc tái sử dụng giữa repository.

Pipeline lưu mô tả trong Jenkinsfile, nên thay đổi có lịch sử Git và được review cùng source. Việc chuyển không tự giải quyết vấn đề bảo mật: Pipeline vẫn phải dùng credential đúng scope và chạy trên agent phù hợp. Học tiếp mô hình CI/CD tại Nền tảng CI/CD và cơ chế controller–agent tại Kiến trúc Jenkins.

Checklist hoàn thànhCopy Anchor Link

• Tôi có agent tin cậy online, có executor, Git CLI và shell/cmd.exe phù hợp.
• Tôi đã tạo freestyle-first-job bằng New Item → Freestyle project.
• Job checkout được repository, branch và revision đã xác minh.
• Tôi để Credentials là - none - cho repository public và biết không dùng token trong URL.
• Tôi đã chạy build step, thấy revision=..., build=... và Finished: SUCCESS trong Console Output.
• Tôi đã tạo một FAILURE có chủ đích, đọc lỗi đầu tiên, khôi phục lệnh và chạy xanh lại.
• Tôi biết build/report bổ sung có thể phụ thuộc plugin, toolchain và khả năng của agent.
• Tôi không chạy source không tin cậy trên controller và biết lúc nào nên chuyển quy trình sang Jenkinsfile.

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

• Using Jenkins — tạo và cấu hình các loại project/job.
• Using Git with Jenkins — checkout Git, Git plugin và Git tool trên agent.
• Managing Credentials — tạo, giới hạn và dùng credential an toàn.
• Using Jenkins Agents — chọn nơi thực thi build.
• Controller Isolation — cô lập controller khỏi workload build.
• Pipeline — khi cần mô tả quy trình bằng Jenkinsfile.
• Repository jenkins-docs/simple-java-maven-app — source công khai dùng trong lab.

Đọc tiếpCopy Anchor Link