Tìm hiểu CircleCI Orbs: Tối ưu file cấu hình CI/CD

1. CircleCI Orbs là gì?

Theo trang chủ CircleCI:

Orbs are shareable packages of CircleCI configuration you can use to simplify your builds. Choose from the many partner, community, or CircleCI authored orbs in our public registry below, or create a private orb that's exclusive to your organization.

Nói ngắn gọn, Orbs là tính năng cho phép đóng gói các cấu hình CircleCI — cài đặt môi trường, cache, lệnh test, thậm chí cả executor — thành các package dùng chung.

Theo cách hiểu đơn giản của mình, bạn có thể đóng gói những cấu hình phổ biến thành package để tái sử dụng cho nhiều project khác nhau. Với người dùng phổ thông, thay vì phải tự viết các đoạn bash script cài đặt dài dòng, rối rắm (vốn khá "choáng ngợp" với những ai không quen bash script), giờ đây các thao tác đó đã được cộng đồng hoặc tổ chức đóng gói sẵn thành các alias command. Người dùng chỉ cần khai báo orb và gọi lệnh trong steps. Là một người không rành bash script, mình thấy tính năng này rất hữu ích.

Giải thích thêm — cú pháp khai báo orb: Một orb được khai báo theo dạng namespace/orb-name@version, ví dụ circleci/ruby@2.1.0. Trong đó circleci là namespace (tổ chức hoặc cá nhân publish orb), ruby là tên orb, và 2.1.0 là phiên bản theo chuẩn semantic versioning (major.minor.patch). Nên luôn ghim phiên bản cụ thể (ví dụ @2.1.0) thay vì dùng version "nổi" như @volatile hay chỉ ghi major (@2), vì orb có thể được publish version mới bất cứ lúc nào — ghim version cụ thể giúp pipeline của bạn không bị thay đổi hành vi ngoài ý muốn khi orb tác giả cập nhật.

2. Cách sử dụng

Rất đơn giản:

1. Nâng cấp file .circleci/config.yml lên version 2.1.
2. Khai báo các orb cần dùng trong mục orbs.

Danh sách các orb có sẵn được liệt kê tại CircleCI Orbs Registry.

Cập nhật: Yêu cầu "nâng cấp lên version 2.1" trong bài gốc nay còn đúng hơn trước — CircleCI đã thông báo ngừng hỗ trợ config version: 2.0 kể từ ngày 27/6/2026, tất cả pipeline bắt buộc phải dùng version: 2.1 trở lên.

Ví dụ 1: Cài đặt Chrome cho môi trường test

version: 2.1
orbs:
  browser-tools: circleci/browser-tools@2.0.0
jobs:
  build:
    docker:
      - image: cimg/ruby:3.3-browsers
    steps:
      - checkout
      - browser-tools/install_chrome:
          replace-existing: true
      - browser-tools/install_chromedriver
      - run: |
          ruby --version
          node --version
          java --version
          google-chrome --version

Kết quả:

Nếu phải tự viết script để cài đặt Chrome nhằm chuẩn bị môi trường test, bạn sẽ cần một đoạn bash script khá phức tạp và tốn không ít thời gian để chạy đúng. Với orb, việc này chỉ gói gọn trong vài dòng khai báo.

Cập nhật: Bản gốc của bài viết dùng cú pháp browser-tools@1.1.3 với step install-chrome (dấu gạch ngang) và tham số chrome-version để ghim về một phiên bản Chrome cụ thể. Kể từ browser-tools orb v2.0.0, các step đã đổi sang dạng snake_case (install_chrome, install_chromedriver), tham số chrome-version không còn được dùng để ghim phiên bản như trước — orb giờ cài Chrome kèm ChromeDriver tương ứng thông qua cơ chế Chrome for Testing. Nếu dự án của bạn vẫn đang dùng orb v1.x, cấu hình cũ trong bài vẫn hoạt động, nhưng nên cân nhắc nâng cấp lên v2.x. Ngoài ra, base image cimg/ruby:2.6.6-browsers trong bài gốc đã khá cũ; nên dùng bản Ruby còn được hỗ trợ (ví dụ cimg/ruby:3.3-browsers).

Giải thích thêm:

• Chrome for Testing là chương trình do Google phát hành riêng cho mục đích testing, đảm bảo mỗi bản Chrome luôn có ChromeDriver tương thích đi kèm — trước đây việc Chrome tự động cập nhật hay lệch phiên bản với ChromeDriver là nguyên nhân phổ biến gây lỗi trong pipeline CI.
• Tham số replace-existing: true yêu cầu orb gỡ bản Chrome có sẵn trong image (nếu có) trước khi cài bản mới, tránh xung đột phiên bản.
• cimg/ là tiền tố của convenience images — bộ Docker image chính thức do CircleCI xây dựng và bảo trì, tối ưu tốc độ pull và luôn được vá lỗi bảo mật. Đây là lựa chọn được khuyến nghị thay cho các image cũ hơn dạng circleci/<ngôn ngữ> vốn không còn được cập nhật.

Ví dụ 2: Cài đặt và cache gem cho Rails

Cách làm truyền thống, không dùng orb:

# bundle
- restore_cache:
    keys:
      - vendor-bundle-{{ checksum "Gemfile.lock" }}
- run:
    name: bundle check
    command: bundle check --path=vendor/bundle || bundle install --path=vendor/bundle --without development development_ext --jobs=4 --retry=3
- save_cache:
    key: vendor-bundle-{{ checksum "Gemfile.lock" }}
    paths:
      - vendor/bundle

Giải thích thêm — vì sao dùng checksum của Gemfile.lock làm cache key? {{ checksum "Gemfile.lock" }} tạo ra một chuỗi hash duy nhất dựa trên nội dung file Gemfile.lock. Nếu danh sách gem không đổi, hash không đổi → CircleCI tìm thấy cache cũ và restore_cache sẽ khôi phục thư mục vendor/bundle đã cài sẵn, giúp bỏ qua bước tải lại toàn bộ gem. Chỉ khi Gemfile.lock thay đổi (thêm/bớt/nâng cấp gem), hash mới thay đổi và pipeline mới cài đặt lại từ đầu rồi lưu cache mới qua save_cache. Đây chính là cơ chế mà orb ruby/install-deps đã tự động hóa ở ví dụ bên dưới.

Với orb circleci/ruby, cấu hình rút gọn lại chỉ còn:

orbs:
  ruby: circleci/ruby@2.1.0
# ...
jobs:
  build:
    docker:
      - image: cimg/ruby:3.3
    steps:
      - checkout
      - ruby/install-deps

Chế độ caching được orb xử lý mặc định (dựa trên checksum của Gemfile.lock), không cần khai báo thủ công restore_cache / save_cache như trước. Step ruby/install-deps vẫn hoạt động đúng như bài viết gốc mô tả, đây là phần thông tin không bị lỗi thời.

Lưu ý: Các image circleci/ruby:* (không có tiền tố cimg/) đã ngừng cập nhật từ cuối năm 2021. Nên dùng convenience image cimg/ruby:* để đảm bảo image luôn được vá lỗi và cập nhật phiên bản mới.

3. Lời kết

Bài viết này được chia sẻ từ góc nhìn của một Rails Developer nên nội dung còn khá sơ sài, mong bạn đọc thông cảm. Hy vọng sau bài viết ngắn này sẽ có thêm nhiều bạn đào sâu hơn về CircleCI Orbs và chia sẻ lại những kinh nghiệm chi tiết hơn.

Cảm ơn các bạn đã đọc!

Sài Gòn — Covid năm thứ 2