Cấu hình dòng công việc Hành động GitHub

10 phút

Tại đây, bạn sẽ tìm hiểu một số cấu hình phổ biến trong tệp dòng công việc. Bạn cũng có thể khám phá các thể loại sự kiện, tắt và xóa dòng công việc, cũng như sử dụng các phiên bản cụ thể của một hành động để thực hành tốt nhất về bảo mật.

Lập cấu hình dòng công việc để chạy cho các sự kiện đã lên lịch

Như đã đề cập trước đó, bạn có thể cấu hình dòng công việc của mình để chạy khi hoạt động cụ thể diễn ra trên GitHub, khi một sự kiện bên ngoài GitHub xảy ra hoặc vào thời điểm đã lên lịch. Sự kiện schedule này cho phép bạn kích hoạt dòng công việc để chạy tại thời điểm UTC cụ thể bằng cách sử dụng cú pháp cron POSIX. Cú pháp cron này có năm * trường và mỗi trường đại diện cho một đơn vị thời gian.

Sơ đồ của năm trường đơn vị thời gian để lên lịch sự kiện trong tệp dòng công việc.

Ví dụ: nếu bạn muốn chạy dòng công việc 15 phút một lần, sự kiện schedule sẽ trông giống như ví dụ sau đây:

on:
  schedule:
    - cron:  '*/15 * * * *'

Và nếu bạn muốn chạy dòng công việc vào mỗi Chủ Nhật lúc 3:00 sáng, sự schedule kiện sẽ trông như thế này:

on:
  schedule:
    - cron:  '0 3 * * SUN'

Bạn cũng có thể dùng toán tử để chỉ định một phạm vi giá trị hoặc quay số vào dòng công việc đã lên lịch của bạn. Khoảng thời gian ngắn nhất bạn có thể chạy dòng công việc đã lên lịch là năm phút một lần và chúng chạy trên lần cam kết mới nhất trên nhánh mặc định hoặc cơ sở.

Lập cấu hình dòng công việc để chạy cho các sự kiện thủ công

Ngoài các sự kiện đã lên lịch, bạn có thể kích hoạt dòng công việc theo cách thủ công bằng cách sử dụng sự workflow_dispatch kiện. Sự kiện này cho phép bạn chạy dòng công việc bằng cách sử dụng API REST GitHub hoặc bằng cách chọn nút Chạy dòng công việc trong tab Hành động trong kho lưu trữ của bạn trên GitHub. Sử workflow_dispatchdụng , bạn có thể chọn nhánh nào bạn muốn dòng công việc chạy và inputs đặt tùy chọn mà GitHub trình bày dưới dạng thành phần biểu mẫu trong giao diện người dùng.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

Ngoài ra, bạn workflow_dispatchcó thể sử dụng API GitHub để kích hoạt một sự kiện webhook được gọi là repository_dispatch. Sự kiện này cho phép bạn kích hoạt dòng công việc cho hoạt động diễn ra bên ngoài GitHub. Về cơ bản nó phục vụ như một yêu cầu HTTP cho kho lưu trữ của bạn yêu cầu GitHub kích hoạt một dòng công việc tắt một hành động hoặc webhook. Sử dụng sự kiện thủ công này yêu cầu bạn thực hiện hai việc: POST gửi yêu cầu đến điểm cuối GitHub /repos/{owner}/{repo}/dispatches với tên sự kiện webhook trong nội dung yêu cầu và repository_dispatch cấu hình dòng công việc của bạn để sử dụng sự kiện.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Cấu hình dòng công việc để chạy cho các sự kiện webhook

Cuối cùng, bạn có thể cấu hình dòng công việc để chạy khi các sự kiện webhook cụ thể xảy ra trên GitHub. Bạn có thể kích hoạt hầu hết các sự kiện webhook từ nhiều hoạt động cho webhook. Nếu tồn tại nhiều hoạt động cho một webhook, bạn có thể chỉ định một loại hoạt động để kích hoạt dòng công việc. Ví dụ, bạn có thể chạy dòng công việc cho sự kiện check_run , nhưng chỉ cho các loại rerequested hoạt requested_action động hoặc.

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch là một sự kiện tùy chỉnh trong Hành động GitHub cho phép các hệ thống bên ngoài (hoặc thậm chí các dòng công việc GitHub khác) kích hoạt dòng công việc theo cách thủ công bằng cách gửi yêu cầu POST đến API GitHub. Nó cho phép tự động hóa linh hoạt và tích hợp với các công cụ bên ngoài, kịch bản hoặc hệ thống cần để bắt đầu dòng công việc trong repo của bạn.

Trường hợp sử dụng

Kích hoạt dòng công việc từ các công cụ CI/CD bên ngoài.
Phối hợp triển khai nhiều repo (ví dụ: Repo A kết thúc bản dựng → kích hoạt Repo B).
Bắt đầu tự động hóa dựa trên các sự kiện bên ngoài (webhooks, giám sát cảnh báo, công việc CRON bên ngoài GitHub).
Thực hiện dòng công việc chuỗi giữa các kho lưu trữ hoặc trong đơn lẻ.

Dòng công việc mẫu lắng nghe ý repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Các thành phần chính:

loại: Tùy chọn. Xác định các loại sự kiện tùy chỉnh như run-tests, deploy-to-prod, v.v.
github.event.client_payload: Truy nhập vào bất kỳ dữ liệu tùy chỉnh nào khác được truyền trong sự kiện phân phối.
github.event.action: Tên của thư event_type đã gửi.

Kích hoạt sự kiện thông qua API

Bạn phải gửi yêu cầu POST đến điểm cuối GitHub REST API v3:

POST https://api.github.com/repos/OWNER/REPO/dispatches

Phép

Yêu cầu mã thông báo truy nhập cá nhân (PAT) với phạm vi repo.
Đối với tổ chức, hãy đảm bảo thiết đặt truy nhập thích hợp cho mã thông báo của bạn.

Cấu trúc lệnh mẫu

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Cấu trúc tải trọng

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Tham số

Trường	Loại	Mô tả	Bắt buộc
`event_type`	chuỗi	Tên tùy chỉnh cho sự kiện. Tên này ánh xạ đến giá trị kiểu trong trình kích hoạt dòng công việc của bạn	Có
`client_payload`	đối tượng	Tải trọng JSON tùy ý để gửi dữ liệu tùy chỉnh cho dòng công việc (github.event.client_payload)	Không

Repository_dispatch số phân tích tham số

Khi thực hiện yêu cầu POST đến điểm cuối API GitHub, bạn phải thông qua nội dung JSON với hai tham số chính:

event_type
client_payload

event_type

Một chuỗi tùy chỉnh bắt buộc mà bạn xác định. GitHub coi giá trị này là "hành động" hoặc "loại" của công văn. Nó được sử dụng để xác định điều gì đã kích hoạt dòng công việc và dòng công việc lọc đang lắng nghe các loại cụ thể.

Định dạng:
- Loại: chuỗi
- Ví dụ: "deploy", "run-tests", "sync-db", "build-docker"
Sử dụng trong Dòng công việc: Được dùng để lắng nghe các loại sự kiện cụ thể và truy nhập giá trị bên trong dòng công việc. Điều này giúp tái sử dụng một dòng công việc cho nhiều mục đích và giúp tự động hóa được sắp xếp khoa học hơn và theo sự kiện.
Ví dụ:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

Đối tượng JSON dạng tự do cho phép bạn gửi dữ liệu tùy chỉnh cùng với công văn. Bạn xác định cấu trúc và có thể truy nhập bên trong dòng công việc.

Định dạng:
- Loại: đối tượng
- Khóa và giá trị tùy chỉnh
Sử dụng trong Dòng công việc: Đối tượng này được dùng cho việc triển khai nhiều môi trường, bản phát hành theo phiên bản hoặc chuyển ngữ cảnh từ hệ thống hoặc quy trình khác và cho phép dòng công việc được tham số hóa, tương tự như đối số đầu vào.
Ví dụ:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

Chi tiết tải trọng ví dụ

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Sử dụng từ khóa có điều kiện

Trong tệp dòng công việc của bạn, bạn có thể truy nhập thông tin ngữ cảnh và đánh giá biểu thức. Mặc dù các if biểu thức thường được sử dụng với từ khóa có điều kiện trong tệp dòng công việc để xác định xem một bước có nên chạy hay không, bạn có thể sử dụng bất kỳ ngữ cảnh và biểu thức nào được hỗ trợ để tạo ra một điều kiện. Điều quan trọng cần biết là khi sử dụng các điều kiện trong dòng công việc của mình, bạn cần dùng cú pháp cụ thể ${{ <expression> }}. Cú pháp này yêu cầu GitHub đánh giá một biểu thức thay vì coi nó như một chuỗi.

Ví dụ: dòng công việc ifgithub.ref sử dụng điều kiện để kiểm tra xem (nhánh hoặc tham chiếu thẻ đã kích hoạt chạy dòng công việc) có khớp hay không refs/heads/main. Để tiếp tục, dòng công việc sẽ trông giống như thế này:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Lưu ý rằng trong ví dụ này, cú ${{ }} pháp bị thiếu. Với một số biểu thức, như biểu if thức có điều kiện, bạn có thể bỏ qua cú pháp biểu thức. GitHub tự động đánh giá một số biểu thức phổ biến này, nhưng bạn luôn có thể đưa vào biểu thức phòng khi bạn quên biểu thức mà GitHub sẽ tự động đánh giá.

Để biết thêm thông tin về cú pháp và biểu thức dòng công việc, hãy xem cú pháp Dòng công việc cho Hành động GitHub.

Tắt và xóa dòng công việc

Sau khi thêm dòng công việc vào kho lưu trữ của mình, bạn có thể thấy tình huống bạn muốn tạm thời tắt dòng công việc. Bạn có thể ngăn dòng công việc được kích hoạt mà không cần phải xóa tệp khỏi kho lưu trữ, trên GitHub hoặc thông qua API REST GitHub. Khi bạn muốn bật lại dòng công việc, bạn có thể dễ dàng thực hiện nó bằng cách sử dụng cùng một phương pháp.

Ảnh chụp màn hình về việc tắt dòng công việc trên GitHub.

Tắt dòng công việc có thể hữu ích trong một số trường hợp sau:

Lỗi trên dòng công việc đang tạo ra quá nhiều yêu cầu hoặc sai ảnh hưởng tiêu cực đến dịch vụ bên ngoài.
Bạn muốn tạm thời tạm dừng dòng công việc không quan trọng và mất quá nhiều phút trên tài khoản của mình.
Bạn muốn tạm dừng dòng công việc đang gửi yêu cầu đến dịch vụ bị sdừng.
Bạn đang làm việc trên một cái bút và bạn không cần tất cả chức năng của một số dòng công việc mà nó bao gồm (chẳng hạn như dòng công việc đã lên lịch).

Bạn cũng có thể hủy bỏ chạy dòng công việc đang diễn ra trong giao diện người dùng GitHub từ tab Hành động hoặc bằng cách sử dụng điểm cuối API DELETE /repos/{owner}/{repo}/actions/runs/{run_id}GitHub. Hãy nhớ rằng khi bạn hủy bỏ chạy dòng công việc, GitHub sẽ hủy bỏ tất cả các công việc và các bước trong quy trình chạy đó.

Dùng dòng công việc được mẫu của tổ chức

Nếu bạn có một dòng công việc mà nhiều nhóm sử dụng trong một tổ chức, bạn không cần phải tạo lại cùng một dòng công việc cho mỗi kho. Thay vào đó, bạn có thể tăng cường tính nhất quán trong tổ chức của mình bằng cách sử dụng mẫu dòng công việc được xác định trong .github kho lưu trữ của tổ chức. Bất kỳ thành viên nào trong tổ chức đều có thể sử dụng dòng công việc mẫu tổ chức và bất kỳ kho lưu trữ nào trong tổ chức đó đều có quyền truy nhập vào các dòng công việc mẫu đó.

Bạn có thể tìm thấy các dòng công việc này bằng cách dẫn hướng đến tab Hành động của một kho chứa trong tổ chức, chọn Dòng công việc mới, rồi tìm phần mẫu dòng công việc của tổ chức có tiêu đề "Dòng công việc được tạo bởi tên tổ chức". Ví dụ: tổ chức tên là Mona có dòng công việc mẫu như minh họa ở đây.

Ảnh chụp màn hình dòng công việc tổ chức mẫu được Mona gọi là lời chào và phân loại.

Sử dụng các phiên bản cụ thể của một hành động

Khi tham chiếu các hành động trong dòng công việc của bạn, chúng tôi khuyên bạn nên tham chiếu đến một phiên bản cụ thể của hành động đó thay vì chỉ tham chiếu đến chính hành động đó. Bằng cách tham chiếu đến một phiên bản cụ thể, bạn đang bảo vệ khỏi những thay đổi không mong muốn được đẩy sang hành động có khả năng phá vỡ dòng công việc của bạn. Dưới đây là một số cách bạn có thể tham chiếu đến một phiên bản hành động cụ thể:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Một số tham chiếu an toàn hơn các tham chiếu khác. Ví dụ: tham chiếu đến một nhánh cụ thể sẽ chạy hành động loại bỏ các thay đổi mới nhất từ nhánh đó mà bạn có thể muốn hoặc không muốn. Bằng cách tham chiếu một số phiên bản cụ thể hoặc cam kết hàm băm SHA, bạn sẽ cụ thể hơn về phiên bản hành động bạn đang chạy. Để có thêm sự ổn định và bảo mật, chúng tôi khuyên bạn nên sử dụng cam kết SHA của hành động đã phát hành trong dòng công việc của bạn.

Phản hồi

Trang này có hữu ích không?