GitHub Actions Checkout Action: actions/checkout

Vấn đề nó giải quyết

Một GitHub Actions runner khởi động trong trạng thái trống — repository của bạn không có sẵn trên đó. Trước khi chạy test hay build, phải có thứ gì đó lấy code về, thiết lập credential để `git push` hoạt động, và dọn workspace giữa các lần chạy. Làm việc đó thủ công bằng `git clone` nghĩa là bạn phải tự xoay xở với `GITHUB_TOKEN`, trạng thái detached-HEAD và dọn dẹp sau job. Action này ra đời để biến bước đầu tiên đó thành một dòng.

Đây là gì?

GitHub Actions checkout action là action chính thức (actions/checkout) clone repository của bạn vào một workflow runner dưới `$GITHUB_WORKSPACE`, để các step sau có thể truy cập code. Mặc định nó chỉ lấy một commit duy nhất — ref hoặc SHA đã kích hoạt workflow — và giữ một auth token trong git config cục bộ để script của bạn chạy được các lệnh git có xác thực; token đó được xóa trong bước dọn dẹp sau job. Nó viết bằng TypeScript, giấy phép MIT, và do chính GitHub bảo trì.

Vì sao đang được chú ý

Nói trending thì không bằng nói nền tảng — với 8.4k sao, actions/checkout là một trong những GitHub Actions được dùng nhiều nhất, nằm ở đầu gần như mọi file workflow. Chuyển động gần đây xoay quanh bảo mật: README nói v7 giờ mặc định từ chối checkout code của fork pull request dưới `pull_request_target` và `workflow_run` (một vector 'pwn request' phổ biến), v6 chuyển credential được lưu ra khỏi `.git/config` vào `$RUNNER_TEMP`, và v5 chuyển sang runtime node24.

Tính năng chính

• ✓Điều khiển độ sâu fetch: `fetch-depth: 0` kéo toàn bộ lịch sử cho mọi nhánh và tag; mặc định là 1 chỉ lấy commit đã kích hoạt
• ✓Hỗ trợ submodule qua `submodules: true` hoặc `recursive` để checkout các repo lồng nhau
• ✓Sparse checkout qua `sparse-checkout` (với cone mode) và partial clone qua `filter`, để chỉ lấy những đường dẫn bạn cần
• ✓Hỗ trợ Git-LFS với `lfs: true` cho các file lớn
• ✓Xác thực bằng token và SSH: giữ `GITHUB_TOKEN` (hoặc một PAT, hoặc một `ssh-key`) trong git config cho các lệnh có xác thực, rồi xóa sau job
• ✓Checkout nhiều repo dùng `path` và `repository` để đặt nhiều repository cạnh nhau hoặc lồng nhau trên runner
• ✓Input `ref` để checkout bất kỳ nhánh, tag hay SHA nào thay vì ref mặc định của sự kiện

Trường hợp dùng tốt nhất

• •Step đầu tiên của gần như mọi job CI — đưa code lên runner trước khi build, test hay lint
• •Lấy toàn bộ lịch sử git với `fetch-depth: 0` cho các công cụ cần nó, như semantic-release hay `git describe`
• •Checkout một repository thứ hai (công cụ riêng tư, config dùng chung) cạnh repo chính trong cùng một workflow
• •Sparse checkout hoặc checkout một file để tăng tốc các job chỉ chạm vào một phần của monorepo lớn
• •Đẩy một commit ngược lại từ workflow bằng token có sẵn — ví dụ một bot tạo và commit file

Cách cài đặt / dùng thử

Không có gì để cài — đây là một GitHub Action được tham chiếu trực tiếp trong file workflow YAML. Thêm một step với `uses: actions/checkout@v4`, ghim theo tag major-version (hoặc một commit SHA đầy đủ để an toàn hơn về chuỗi cung ứng). GitHub Actions checkout action có giấy phép MIT và do GitHub bảo trì; v7 là major hiện tại, dù `@v4` vẫn được ghim rộng rãi nhất. Nó chạy trên runner do GitHub host lẫn self-hosted.

Cách sử dụng

Trong một file workflow, step checkout đặt ở đầu tiên: ```yaml - uses: actions/checkout@v4 ``` Dòng đó clone ref đã kích hoạt lần chạy. Để lấy toàn bộ lịch sử và tag: ```yaml - uses: actions/checkout@v4 with: fetch-depth: 0 ``` Để checkout một repository thứ hai vào một thư mục con: ```yaml - uses: actions/checkout@v4 with: repository: my-org/my-tools path: my-tools ``` README khuyến nghị đặt `permissions: contents: read` cho `GITHUB_TOKEN` trừ khi bạn cung cấp `token` hoặc `ssh-key` riêng.

Lựa chọn thay thế

Ai nên thử — và ai nên bỏ qua

Bất kỳ ai viết một GitHub Actions workflow. Nếu job của bạn có chạm tới code của repository — build, test, lint, release — thì checkout action chính là step đưa code lên runner. Những người duy nhất bỏ qua nó là những ai chạy một job thực sự không cần code nguồn (một lệnh gọi API thuần túy, hoặc một container image đã sẵn code), hoặc có lý do cụ thể để tự viết `git clone` bằng tay.

Câu hỏi thường gặp