Mô tả rõ môi trường mà job CI thực sự chạy
Xác định shell, thư mục làm việc, quyền và cách truyền trạng thái giữa các bước GitHub Actions bằng một ví dụ nhỏ có thể kiểm tra.

Job CI chạy trong môi trường do workflow và cấu hình runner lựa chọn. Cần mô tả môi trường ấy trước khi xem thành công trên máy cá nhân là bằng chứng CI cũng phải thành công. Thư mục làm việc, runtime sẵn có, quyền và ranh giới tiến trình đều có thể khác terminal của người phát triển.
Nếu đang thêm kiểm tra GitHub Actions đầu tiên, bạn nên bắt đầu bằng job nhỏ có đầu ra dễ xem. Nó làm rõ giao ước thực thi mà chưa cần tải phụ thuộc hay truy cập tài khoản vận hành thật.
Bắt đầu bằng job không cần dùng token repository
Workflow minh họa đầy đủ sau tạo tệp vô hại ở một bước rồi đọc ở bước khác. Nếu muốn chạy thủ công trong repository thực hành, lưu tệp dưới .github/workflows/. Tài liệu sự kiện thủ công yêu cầu tệp workflow tồn tại trên nhánh mặc định. Các ví dụ trong bài được kiểm tra cục bộ; không tuyên bố đã chạy workflow trên runner của GitHub:
name: Inspect the job environment
on: [workflow_dispatch]
permissions: {}
jobs:
inspect:
runs-on: ubuntu-24.04
defaults:
run:
shell: bash
env:
LAB_MODE: verify
steps:
- name: Create the fixture
run: |
printf 'mode=%s\n' "$LAB_MODE"
printf 'directory=%s\n' "$PWD"
mkdir -p fixture
printf '%s\n' 'expected marker' > fixture/result.txt
- name: Read the earlier file
working-directory: fixture
run: |
test "$(cat result.txt)" = 'expected marker'
Workflow không yêu cầu quyền token repository vì không cần action đọc repository hay gọi API. Nó chỉ chạy khi được kích hoạt thủ công. Thiết lập quyền này chi phối token repository, không phải cơ chế cô lập hệ điều hành hay lệnh cấm truy cập mạng. Nhãn runner chọn họ image hệ điều hành; nó không đóng băng mọi phiên bản gói trong image đó.
Bước hai đọc được tệp vì các bước trong job dùng chung workspace của runner. Chúng không dùng một shell chạy liên tục. Biến shell thông thường gán trong bước đầu không tự trở thành biến ở bước sau.
Hệ thống tệp tồn tại giữa các bước này trên runner của job. Trạng thái riêng của shell thuộc từng tiến trình, còn biến môi trường khai báo cho job được cấp cho các tiến trình bước.
Chọn shell và thư mục có chủ đích
Lệnh được Bash diễn giải có thể khác dưới shell khác. Dấu nháy, pipeline và xử lý lỗi là một phần giao ước của trình thông dịch. Chỉ định shell khi script phụ thuộc tính năng của nó và chạy trực tiếp script trong repository thay vì duy trì bản hơi khác trong YAML.
Thư mục làm việc quyết định đường dẫn tương đối trỏ tới đâu. Lệnh như npm ci có thể lỗi vì không tìm thấy lockfile mong đợi dù runtime và mạng đều ổn. Kiểm tra thư mục dự kiến và tệp mà bước cần trước khi đổi thiết lập trình quản lý gói.
Nếu kiểm tra cần mã repository, checkout cũng là bước tường minh. Runner không nhất thiết có sẵn mã chỉ vì workflow thuộc repository ấy. Tham chiếu được checkout cũng quan trọng với pull request: kiểm tra kết quả gộp và kiểm tra đầu nhánh là hai quy trình khác nhau.
Tài liệu cú pháp workflow định nghĩa job, bước, mặc định, quyền và trường môi trường. Dựa vào các định nghĩa đó khi thiết kế thay vì suy hành vi từ một runner tình cờ chạy được.
Ghim runtime ở mức mà dự án hỗ trợ
Runner do dịch vụ cung cấp chứa nhiều công cụ, nhưng phiên bản cài sẵn có thể đổi. Dự án nên chọn runtime ngôn ngữ được hỗ trợ qua bước thiết lập phù hợp hoặc image container được kiểm soát, đồng thời báo phiên bản đã dùng khi có lỗi.
Chọn phiên bản lớn hữu ích để thử tương thích. Phiên bản chính xác hoặc digest tạo ranh giới tái lập hẹp hơn. Không lựa chọn nào đúng cho mọi trường hợp: job tương thích có thể cố ý theo cập nhật, còn build phát hành cần định danh toolchain đã được duyệt rõ ràng.
Ghi phiên bản trình quản lý gói nếu lockfile hoặc hành vi cài đặt phụ thuộc nó. Chỉ runtime chưa chắc mô tả đủ chuỗi công cụ. Cũng cần tách hệ điều hành runner khỏi container dùng cho job hoặc action: lệnh có thể chạy trong hệ thống tệp và userspace khác máy runner.
Truyền trạng thái qua kênh được khai báo
Dùng tệp hoặc đầu ra workflow có tài liệu khi bước sau cần kết quả tính toán. Cơ chế tệp môi trường của GitHub có thể cấp giá trị cho bước tiếp theo, nhưng ghi vào tệp không đổi ngược biến của shell hiện tại. Định dạng cũng cần được xử lý cẩn thận với giá trị nhiều dòng hoặc không đáng tin.
Không in toàn bộ môi trường để chẩn đoán một thiết lập thiếu. Kiểm tra cụ thể có thể báo biến bắt buộc đã có hay chưa mà không in nội dung. Workflow minh họa chỉ in chế độ vô hại đã khai báo và thư mục làm việc.
Các job khác nhau có thể chạy trên máy khác nhau. Tệp để lại trong workspace của một job không tự là đầu vào job khác. Dùng artifact, nơi lưu ngoài được định nghĩa hoặc cơ chế truyền có hỗ trợ, đồng thời định danh kết quả được chuyển. Cùng tệp workflow không đồng nghĩa dùng chung ổ đĩa cục bộ giữa các job.
Gắn lỗi với ranh giới đã thay đổi
Nếu bước không thấy tệp, xem checkout và lựa chọn thư mục. Nếu API từ chối yêu cầu, xem quyền thực tế và danh tính. Nếu lệnh hành xử khác, xem shell, runtime và phiên bản đầu vào. Các kiểm tra này cụ thể hơn việc chạy lại toàn bộ workflow cho tới khi xanh.
Hồ sơ lỗi hữu ích gồm revision workflow, môi trường runner, phiên bản công cụ và bước lỗi chính xác, không chứa secret. Với ví dụ này, thành công đơn giản là bước hai đọc đúng byte dự kiến. Khi giao ước cơ bản đã rõ, thêm từng kiểm tra ứng dụng để mỗi phụ thuộc mới có người phụ trách và lỗi quan sát được.
Quan sát bàn giao giữa hai shell mới
Thêm hai mục bước dưới đây vào cùng danh sách steps của job. Chúng chỉ dùng giá trị vô hại đã khai báo. Bước đầu export một biến shell và ghi giá trị khác vào tệp môi trường của runner. Bước sau kiểm tra trạng thái nào tới tiến trình mới và ghi đè chế độ của job riêng trong bước ấy.
- name: Publish a later-step value
run: |
export CI_LAB_LOCAL='this shell'
printf 'CI_LAB_RESULT=%s\n' 'published' >> "$GITHUB_ENV"
printf 'current result=%s\n' "${CI_LAB_RESULT-unset}"
- name: Read the runner-supplied value
env:
LAB_MODE: step-specific
run: |
test "${CI_LAB_LOCAL-unset}" = unset
test "$CI_LAB_RESULT" = published
test "$LAB_MODE" = step-specific
test "$(cat fixture/result.txt)" = 'expected marker'
printf 'later result=%s; mode=%s\n' "$CI_LAB_RESULT" "$LAB_MODE"
Với môi trường ban đầu của workflow minh họa, bước mới đầu tiên in current result=unset. Ghi văn bản vào tệp không gán biến shell. Khi bước kết thúc, runner xử lý tệp rồi cấp giá trị cho các bước sau. Bước kế in later result=published; mode=step-specific. Trong khi đó biến export riêng không có: nó sẽ được tiến trình con do chính shell ấy tạo kế thừa, không phải tiến trình bước ngang hàng mới do runner tạo.
Tài liệu tệp môi trường GitHub quy định khả năng dùng ở bước sau này. Tài liệu còn yêu cầu mã hóa phù hợp, mô tả dấu phân cách nhiều dòng và những tên biến bị hạn chế. Ví dụ chỉ ghi giá trị cố định một dòng. Không ghép chuỗi tùy ý để biến đầu vào nhiều dòng thành định dạng đó, và không source tệp môi trường không đáng tin như mã shell để giả lập runner. Phân tích dữ liệu và thực thi cú pháp shell là hai thao tác khác nhau.
Bảng tách ba cơ chế: export của tiến trình, truyền trạng thái do runner quản lý và thiết lập môi trường riêng của bước. Chế độ ghi đè chỉ áp dụng trong lúc bước đó chạy. Bước sau không có ghi đè sẽ quay lại chế độ của job, giả định không có cập nhật chủ động khác cho biến ấy. Vì vậy biết tên biến chưa đủ; phải tìm phạm vi đang cấp giá trị hiện tại.
Chú ý đường dẫn tệp tương đối ở bước cuối. Bước đọc trước dùng working-directory: fixture, nhưng thiết lập riêng ấy không làm mọi shell sau bắt đầu tại đó. Bước mới lại bắt đầu ở thư mục làm việc mặc định của job và đọc fixture/result.txt. Tương tự, cd đổi thư mục của shell hiện tại; nó không sửa thiết lập thư mục làm việc cho bước sau.
Tái lập ranh giới shell mà không coi đó là chạy GitHub
Kiểm tra cục bộ có thể tạo tiến trình Bash mới cho từng khối run, dùng một workspace tạm và cấp rõ môi trường job cùng bước. Với ví dụ này, phần bàn giao tệp môi trường có thể chỉ chấp nhận đúng khóa và giá trị cố định dự kiến rồi tạo môi trường cho tiến trình sau. Mô hình hẹp đó kiểm tra lệnh và các quan hệ tiến trình được mô tả. Nó không chạy dispatcher GitHub, image runner của dịch vụ, nơi cấp token hay toàn bộ bộ phân tích tệp môi trường.
Dùng cách gọi Bash tường minh trong tài liệu khi so hành vi lỗi. Tài liệu cú pháp GitHub ghi Bash bỏ qua tệp khởi động và dùng -e -o pipefail; Bash tương tác cục bộ có thể có thiết lập hoặc tùy biến khởi động khác. Vì vậy chạy đúng trường hợp thành công chỉ là bước đầu. Xóa fixture/result.txt trước bước đọc rồi xác minh lệnh thất bại với cách gọi đã chọn. Phân biệt lỗi đó với việc không thể khởi động shell vì thư mục làm việc chưa tồn tại.
Thử biến đổi khác: bỏ dòng ghi tệp môi trường nhưng giữ kiểm tra ở bước sau. Bước sau cần thất bại vì không còn được cấp kết quả bắt buộc. Thay dòng ghi bằng export CI_LAB_RESULT=published trong bước tạo cũng phải thất bại ở shell mới tiếp theo. Sửa đổi chỉ dùng export cho thấy export không truyền giá trị sang bước sau có shell mới. Riêng kiểm tra CI_LAB_LOCAL phải chưa được đặt sẽ phát hiện việc vô tình dùng lại shell của bước tạo. Bỏ dòng ghi vẫn để CI_LAB_RESULT chưa được đặt ngay cả trong một shell dùng chung mới khởi động; dùng lại shell không khiến toàn bộ ví dụ sau hai biến đổi này chạy qua.
Cuối cùng thêm bước thứ năm chỉ in chế độ vô hại và xác nhận marker còn tồn tại. Nó cần thấy giá trị job verify vì ghi đè env của bước trước chỉ thuộc bước đó. Nếu chuyển bước đọc sang job riêng, không kỳ vọng tệp tự đi theo. Ở ranh giới này, khai báo truyền artifact hoặc tạo lại tệp mẫu. Workflow nhỏ trở nên đáng tin khi mỗi lần truyền trạng thái có kênh rõ tên và từng kiểm tra chạy trong môi trường mà workflow thực sự yêu cầu.