---
id: cicd-circleci
title: "CircleCI"
shortTitle: "CircleCI"
track: cicd
trackTitle: "CI/CD"
order: 6
level: normal
status: published
estimatedMinutes: 25
prerequisites:
  - cicd-secrets-oidc
next: cicd-cloud-build
reviewedAgainst: 2026-10-12
sources:
  - title: "CircleCI configuration reference"
    url: https://circleci.com/docs/configuration-reference/
  - title: "Sample config.yml"
    url: https://circleci.com/docs/sample-config/
---

# CircleCI

CircleCI đọc `.circleci/config.yml`. Bài này đủ để nhận ra file và không trộn khóa với GitHub Actions.

## Để làm gì

Bạn đọc một config version 2.1, chỉ ra job nào chạy trong workflow, và biết orb là gói bước có sẵn.

## Gồm những gì

- `version: 2.1`, `jobs`, `workflows`.
- Executor `docker` với `image`.
- Orb: nhận tên và version. Đừng thêm orb lạ vào repo thật khi đang đọc bài.

Đừng đăng ký project trên circleci.com cho bài này.

## Dùng khi nào

Repo đã có thư mục `.circleci`. Pipeline mới thì ở lại GitHub Actions. Đừng chạy cả hai cho cùng một bộ test nếu không ai xem bên CircleCI.

## Kiến thức cốt lõi

File nằm ở `.circleci/config.yml`, không phải gốc repo. `version: 2.1` là bản config còn trong tài liệu hiện tại. Job khai báo executor. Khối `docker` nhận `image`, ví dụ `cimg/node:24.4`. `steps` gồm `checkout` và `run`.

`workflows` gọi job và đặt `requires` nếu job sau phải đợi job trước. Không có workflow thì không có đường chạy, dù job đã viết.

Orb là namespace của người khác, dạng `orb: node@5`. Pin version. Orb không rõ nguồn thì đừng đưa vào, vì nó chạy trong job của bạn.

Context và project env giữ biến. Đừng viết token vào `run`.

## Lệnh và code mẫu

`.circleci/config.yml`:

```yaml
version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:24.4
    steps:
      - checkout
      - run: node -e "console.log('ok')"
workflows:
  build:
    jobs:
      - test
```

## Thực hành

1. Chỉ đường dẫn file đúng.
2. Chỉ image executor.
3. Không tạo tài khoản CircleCI.

## Kết quả mong đợi

File là `.circleci/config.yml`. Image là `cimg/node:24.4`. Workflow `build` gọi job `test`.

## Checklist

- [ ] Không commit token vào `run`.
- [ ] Orb có version.
- [ ] Một hệ CI chính, file này chỉ để đọc nếu repo đã dùng.

## Lỗi thường gặp

**Để file ở `.github/circle.yml`.** CircleCI không đọc. Đúng chỗ là `.circleci/config.yml`.

**Job không nằm trong `workflows`.** Config hợp lệ nhưng không chạy job đó. Thêm tên job vào workflow.

## Nguồn

1. [Configuration reference](https://circleci.com/docs/configuration-reference/) — `jobs`, `workflows`, orb.
2. [Sample config.yml](https://circleci.com/docs/sample-config/) — bố cục file 2.1.

## Tiếp theo

[Cloud Build](./08-cloud-build.md)