Khoá GitHub Actions bằng lockfile: hướng dẫn gh actions-lock

Trong bài này

• 12 phút đọc
• 10 phần
• 6 mẫu sao chép được
• 2 bảng tra cứu

Mục lục

1. Lockfile cho GitHub Actions là gì
2. Vì sao tag không an toàn
3. Lockfile so với ghim SHA
4. Hướng dẫn khoá workflow từng bước
5. Thêm job kiểm tra trong CI
6. Cập nhật phiên bản mà không phá khoá
7. Giới hạn cần biết
8. Hiểu lầm phổ biến
9. Câu hỏi thường gặp
10. Kết luận

Cách bài viết này được thực hiện: bài dựa trên thông báo chính thức của GitHub (28/10/2026), tài liệu GitHub Docs, README của công cụ gh-actions-lock và bài hướng dẫn của Hugo van Kemenade (người điều phối phát hành Python) ngày 11/11/2026, kiểm tra ngày 13/11/2026. Các file cấu hình trong bài là ví dụ để bạn chỉnh theo dự án, nên thử trên một nhánh riêng trước.

Nếu bạn để AI coding agent viết workflow GitHub Actions, rất có thể file của bạn đang có những dòng như uses: actions/checkout@v7. Gọn, dễ đọc, nhưng có một vấn đề: tag v7 có thể bị trỏ sang đoạn code khác bất cứ lúc nào. Nếu tài khoản người giữ action bị chiếm, mỗi lần workflow chạy, code độc sẽ chạy cùng với bí mật CI của bạn.

Từ ngày 28/10/2026, GitHub chính thức phát hành lockfile cho workflow GitHub Actions: bạn vẫn viết tag dễ đọc, nhưng Actions chỉ chạy đúng commit bạn đã khoá. Bài này giải thích lockfile là gì, vì sao nó tốt hơn ghim SHA kiểu cũ, và hướng dẫn từng bước khoá repo của bạn bằng gh actions-lock, kèm job kiểm tra trong CI.

Câu trả lời ngắn: Lockfile của GitHub Actions là file .github/workflows/actions.lock ghi lại commit chính xác của từng action, kể cả action mà action khác gọi tới. Cài gh extension install github/gh-actions-lock, chạy gh actions-lock trong repo, commit lockfile, rồi thêm gh actions-lock --verify vào CI là xong.

Tóm tắt nhanh

• Lockfile phát hành chính thức ngày 28/10/2026 cho gói Free, Team và Enterprise Cloud.
• Workflow giữ tag dễ đọc như v7.0.1; Actions chạy đúng commit đã ghi trong lockfile.
• Khoá cả phụ thuộc bắc cầu, ghi cả ID chủ sở hữu và ID repo để chống đổi tên giả mạo.
• Dependabot và Renovate tự cập nhật lockfile khi nâng phiên bản action.
• Lockfile chống thay đổi bất ngờ, không chứng minh action an toàn; vẫn phải xem xét trước khi khoá.

Nội dung chính:

1. Lockfile cho GitHub Actions là gì
2. Vì sao tag không an toàn
3. Lockfile so với ghim SHA
4. Hướng dẫn khoá workflow từng bước
5. Thêm job kiểm tra trong CI
6. Cập nhật phiên bản mà không phá khoá
7. Giới hạn cần biết
8. Hiểu lầm phổ biến
9. Câu hỏi thường gặp
10. Kết luận

Lockfile cho GitHub Actions là gì

Nếu bạn từng làm web với npm, bạn đã gặp package-lock.json: file package.json ghi “dùng thư viện X bản 4.x”, còn lockfile ghi chính xác bản nào đã cài. Lockfile của GitHub Actions làm điều tương tự cho các action trong workflow.

Theo thông báo của GitHub ngày 28/10/2026, tính năng workflow dependency lockfiles chuyển từ thử nghiệm công khai sang phát hành chính thức, áp dụng cho GitHub Enterprise Cloud (kể cả bản lưu trữ dữ liệu theo vùng), gói Team và gói Free. File nằm ở .github/workflows/actions.lock, do công cụ dòng lệnh tạo ra và không nên sửa tay.

Theo GitHub Docs, lockfile có hai phần: workflows (mỗi workflow dùng những phụ thuộc nào) và dependencies (mỗi tham chiếu trỏ tới commit nào). Mỗi phụ thuộc ghi ref (ví dụ một tag), commit, và hai con số owner_id, repo_id. Hai ID này giúp Actions xác nhận lúc chạy rằng repo đằng sau cái tên vẫn là repo bạn đã khoá, kể cả khi ai đó đổi tên hay tạo repo trùng tên.

Vì sao tag không an toàn

Khi workflow ghi uses: octo-org/deploy-action@v3, Actions sẽ chạy commit mà tag v3 đang trỏ tới vào đúng thời điểm chạy. Tag và nhánh có thể bị trỏ lại. Nếu tài khoản người giữ action bị chiếm, kẻ tấn công chỉ cần dời tag sang commit chứa code độc, và mọi repo dùng tag đó sẽ chạy code độc ở lần chạy kế tiếp.

Đây không phải lý thuyết. Vụ tấn công chuỗi cung ứng nhắm vào action tj-actions/changed-files, được Hugo van Kemenade dẫn lại, là ví dụ điển hình: các tag của action bị trỏ sang code độc. Workflow thường có quyền truy cập token, khoá triển khai, khoá đám mây, nên một action bị tráo là cửa vào thẳng hệ thống của bạn.

Với người vibe code, rủi ro còn cao hơn một chút: agent hay viết workflow từ trí nhớ, dùng tag chung chung như @v3, @main, và ít ai đọc lại từng dòng uses:. Mình đã phân tích một rủi ro khác của agent trong bài lộ API key qua AI coding agent; lockfile là lớp bảo vệ cho phía CI.

Lockfile so với ghim SHA

Trước đây, lời khuyên của GitHub là ghim action bên thứ ba bằng mã SHA đầy đủ của commit, kiểu uses: actions/checkout@a1b2c3.... Cách này an toàn nhưng khó đọc, khó biết đang dùng bản nào, và quan trọng: nó chỉ khoá action bạn gọi trực tiếp. Nếu action đó lại gọi action khác bằng tag, phần bên trong vẫn có thể bị tráo.

GitHub Docs nói rõ: với repo dùng lockfile, ghim SHA trong file workflow “không còn cần thiết”, và nêu ba lý do lockfile tốt hơn.

Ba cách tham chiếu action trong workflow

Tiêu chí	Chỉ dùng tag	Ghim SHA	Tag + lockfile
Dễ đọc phiên bản	Có	Không	Có
Chống tag bị dời	Không	Có	Có
Khoá phụ thuộc bắc cầu	Không	Không	Có
Ghi danh tính repo nguồn	Không	Không	Có (owner_id, repo_id)

Hướng dẫn khoá workflow từng bước

Bước 1: Cài GitHub CLI và đăng nhập

Công cụ khoá là một extension của GitHub CLI (gh). Nếu chưa có, tải tại cli.github.com, hoặc trên Windows chạy winget install --id GitHub.cli, trên macOS chạy brew install gh. Sau đó đăng nhập:

gh auth login

Lệnh này mở trình duyệt để bạn xác nhận tài khoản. Không dán token vào lệnh hay vào file trong repo.

Bước 2: Cài extension gh-actions-lock

gh extension install github/gh-actions-lock

Công cụ hỗ trợ github.com và GitHub Enterprise Cloud có lưu trữ dữ liệu theo vùng (*.ghe.com), chưa hỗ trợ GitHub Enterprise Server.

Bước 3: Chạy lệnh khoá trong repo

cd duong-dan-toi-repo
gh actions-lock

Lệnh đọc mọi workflow trong .github/workflows/, phân giải từng action (cả action bắc cầu) về commit, kiểm tra nguồn gốc, rồi ghi actions.lock. Theo Hugo van Kemenade, nếu workflow đang ghim SHA, công cụ đổi chúng sang tag dễ đọc dạng vX.Y.Z và ghi SHA vào lockfile. Nếu một action chỉ ghi tag chưa đầy đủ như @v3, công cụ sẽ cảnh báo và gợi ý bản đầy đủ mới nhất, như trong ảnh chụp màn hình ở trên. Bạn có thể khoá thử một workflow trước bằng cách thêm đường dẫn file vào cuối lệnh.

Bước 4: Xem lại rồi commit

git diff .github/workflows/
git add .github/workflows/
git commit -m "ci: khoa GitHub Actions bang lockfile"

Đọc diff trước khi commit: lockfile chỉ đảm bảo không có thay đổi bất ngờ sau khi khoá, không chứng minh action đang dùng là an toàn. GitHub nhấn mạnh phải xem xét phụ thuộc trước khi khoá.

Bước 5: Khoá lại mỗi khi sửa workflow

README dặn chạy lại gh actions-lock mỗi khi thêm workflow hay đổi bất kỳ dòng uses: nào. Nếu bạn để agent sửa workflow, hãy thêm việc này vào hướng dẫn của agent. README còn gợi ý gh skill install github/gh-actions-lock để dạy agent cách dùng công cụ; xem cách skill hoạt động trong bài agent skills: viết SKILL.md một lần, dùng cho mọi agent.

Thêm job kiểm tra trong CI

Lockfile chỉ có ích nếu luôn khớp với workflow. Hugo van Kemenade thêm một job riêng chạy gh actions-lock --verify trên runner nhẹ ubuntu-slim, và ghim chính extension ở bản v0.4.1. Dựa trên cách đó, đây là một workflow mẫu, lưu thành .github/workflows/lockfile.yml:

name: Lockfile
on: [push, pull_request]

permissions:
  contents: read

jobs:
  lockfile:
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          persist-credentials: false
      - name: Kiem tra actions.lock
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh extension install github/gh-actions-lock --pin v0.4.1
          gh actions-lock --verify

Giải thích từng phần:

• permissions: contents: read chỉ cấp quyền đọc mã nguồn, đủ cho việc kiểm tra.
• persist-credentials: false không để token lại trong thư mục git sau khi checkout, giảm rủi ro bước sau dùng nhầm.
• GH_TOKEN: ${{ github.token }} cho GitHub CLI dùng token tạm do Actions cấp cho lần chạy, không phải token cá nhân của bạn.
• --pin v0.4.1 ghim phiên bản extension để CI không tự đổi; nhớ thỉnh thoảng nâng bản này.
• --verify không sửa file, chỉ kiểm tra lockfile đã cập nhật và các commit đã ghim còn khớp nguồn. Lệnh lỗi nghĩa là ai đó (hoặc agent) đã sửa workflow mà quên khoá lại.

Bản thân workflow này cũng dùng action, nên sau khi tạo file, bạn chạy lại gh actions-lock để nó được khoá luôn.

Cập nhật phiên bản mà không phá khoá

Khoá không có nghĩa là đứng yên. Theo thông báo của GitHub, khi Dependabot mở pull request nâng phiên bản một action trong workflow đã khoá, nó tự tạo lại mục tương ứng trong lockfile ngay trong pull request đó, không cần cấu hình thêm. Renovate cũng hỗ trợ lockfile. Hugo van Kemenade khuyên bật thêm “thời gian chờ” (cooldown) để không nâng lên bản vừa phát hành vài giờ, vốn là lúc bản độc dễ lọt qua nhất. Ví dụ với Dependabot, file .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 7

Mỗi tuần Dependabot kiểm tra action mới, nhưng chỉ đề xuất bản đã phát hành ít nhất 7 ngày. Khi pull request tới, bạn vẫn nên đọc thay đổi của action trước khi merge, và để job --verify chạy xanh.

Các chế độ của gh actions-lock theo README:

Các chế độ của gh actions-lock

Lệnh	Sửa file	Dùng khi
gh actions-lock	Có	Khoá lần đầu, sửa lockfile
gh actions-lock –relock	Có	Đưa tag hoặc nhánh đã dời (main, v4) về commit mới nhất
gh actions-lock –verify	Không	Kiểm tra trong CI, có kiểm nguồn gốc
gh actions-lock –verify-local	Không	Kiểm nhanh trước commit, không dùng mạng, không kiểm nguồn gốc
gh actions-lock –no-fix	Không	Chỉ xem báo cáo

README cũng có cờ --accept-moved để chấp nhận commit đã ghim không còn ở upstream, kèm lời dặn không bao giờ dùng trong tự động hoá. Ngoài ra, bạn có thể thêm công cụ kiểm tra bảo mật zizmor (bản 1.32.0 trở lên là bản đầu tiên hiểu lockfile) vào pre-commit, như Hugo van Kemenade đang làm.

Giới hạn cần biết

Lockfile không phải tấm khiên toàn năng. README và tài liệu nêu rõ các chỗ chưa được che:

• Reusable workflow ở repo khác gọi qua jobs.<id>.uses chưa được khoá. Reusable workflow được che bởi lockfile của repo nơi nó được định nghĩa.
• Action cục bộ dạng ./... không được theo dõi. Nếu action cục bộ gọi action từ xa, công cụ báo lỗi chặn, trừ khi bạn dùng cờ xử lý riêng.
• Ảnh container không được khoá; ảnh không ghi digest @sha256: sẽ bị cảnh báo.
• Lùi tag về commit cũ trong lịch sử không bị phát hiện, nên vẫn phải đọc diff của lockfile hoặc dùng tag đầy đủ.
• GitHub Enterprise Server chưa được hỗ trợ.
• Khoá theo từng workflow: workflow nào chưa khoá thì chưa được bảo vệ.

Một lưu ý nhỏ: trang khái niệm trên GitHub Docs lúc mình kiểm tra vẫn ghi tính năng đang thử nghiệm công khai, trong khi thông báo ngày 28/10/2026 nói đã phát hành chính thức. Hãy coi thông báo là mốc mới hơn và theo dõi tài liệu khi có cập nhật.

Với quản trị viên tổ chức, GitHub có chính sách “Require lockfile” ở cấp enterprise, tổ chức và repo để bắt buộc mọi repo dùng lockfile.

Hiểu lầm phổ biến

“Có lockfile thì action nào cũng an toàn.” Lockfile chống thay đổi bất ngờ, không đánh giá code. Action độc được khoá vẫn là action độc.

“Đã ghim SHA thì không cần lockfile.” Ghim SHA không khoá được action bắc cầu bên trong composite action, và không ghi danh tính repo nguồn.

“Khoá rồi thì không bao giờ được cập nhật.” Dependabot, Renovate cập nhật lockfile cùng pull request; --relock khi muốn nâng chủ động.

“Repo cá nhân nhỏ thì không cần.” Workflow của repo nhỏ vẫn có token, khoá triển khai. Kẻ tấn công không chọn repo theo số sao.

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

Lockfile có mất phí không?

Không có phí riêng. Tính năng dành cho các gói Free, Team và Enterprise Cloud theo thông báo của GitHub; extension gh-actions-lock miễn phí.

Repo có cả workflow cũ chưa khoá thì sao?

Khoá theo từng workflow. Bạn có thể khoá từng file bằng cách truyền đường dẫn workflow vào lệnh, hoặc khoá tất cả một lần. Workflow chưa khoá chạy như trước.

Tôi dùng AI agent viết workflow, cần dặn gì?

Dặn agent: dùng tag đầy đủ (v7.0.1 thay vì v7), chạy gh actions-lock sau mỗi lần đổi dòng uses:, và không dùng cờ --accept-moved. Job --verify trong CI sẽ bắt nếu agent quên.

Lockfile có thay được Dependabot không?

Không. Lockfile giữ phiên bản đứng yên; Dependabot hoặc Renovate giúp nâng phiên bản có kiểm soát. Hai thứ dùng cùng nhau.

Có cần xoá các SHA đã ghim trong workflow?

Không bắt buộc. Khi chạy gh actions-lock, công cụ có thể đổi chúng sang tag dễ đọc và chuyển SHA vào lockfile. Đọc diff trước khi commit.

Kết luận

Lockfile cho GitHub Actions là thay đổi nhỏ trong thao tác nhưng lớn về an toàn: workflow vẫn dễ đọc, còn Actions chạy đúng commit đã khoá, kể cả phụ thuộc bắc cầu. Năm phút cài gh actions-lock, khoá repo, thêm job --verify và bật Dependabot có cooldown là đủ cho phần lớn dự án cá nhân. Nhất là khi agent đang viết hộ bạn workflow, một bước kiểm tra tự động trong CI đáng giá hơn mọi lời dặn.

Bạn đã khoá workflow của mình chưa, hay gặp lỗi gì khi chạy thử? Để lại bình luận để mmo.vn cùng gỡ. Nếu quan tâm đến bảo mật khi vibe code, đừng bỏ qua bài Grok Build lộ hơn 35.000 app.

Nguồn tham khảo: GitHub Changelog, “GitHub Actions workflow lockfiles are generally available” (28/10/2026); GitHub Docs, “Workflow dependency lockfiles”; README github/gh-actions-lock; Hugo van Kemenade, “Lock your GitHub Actions” (hugovk.dev, 11/11/2026).