GitHub Action工作流语法

📁 一、基础结构

Yaml

name: My Workflow

on:

push:

branches:

• main

jobs:

my-job:

runs-on: ubuntu-latest

steps:

• name: Checkout code

uses: actions/checkout@v3

---

📄 1. name（工作流名称）

• 用途：定义工作流的名称，显示在 GitHub Actions 界面中。
• 示例：

Yaml

name: CI Pipeline

---

🚀 2. on（触发事件）

• 用途：指定触发工作流运行的事件（如 push、pull_request 等）。
• 支持事件：
  • push
  • pull_request
  • schedule
  • workflow_dispatch（手动触发）
• 示例：

Yaml

on:

  push:

    branches:

      - main

  pull_request:

    branches:

      - dev

---

🧱 3. jobs（任务）

• 用途：定义一个或多个任务（jobs），每个任务可以独立运行或依赖于其他任务。
• 结构：

Yaml

jobs:

  job1:

    ...

  job2:

    ...

---

🖥️ 4. runs-on（运行环境）

• 用途：指定任务运行的虚拟机环境（runner）。
• 常见值：
  • ubuntu-latest
  • windows-latest
  • macos-latest
• 示例：

Yaml

runs-on: ubuntu-latest

---

🧩 5. steps（步骤）

• 用途：在任务中定义一系列操作步骤，按顺序执行。
• 每个步骤可以是：
  • 使用某个 Action（uses）
  • 执行 shell 命令（run）
• 示例：

Yaml

steps:

  - name: Checkout Repository

    uses: actions/checkout@v3

  - name: Run a script

    run: echo "Hello World"

---

🧠 6. uses（使用 Action）

• 用途：引用一个外部的 GitHub Action（可以是官方或第三方）。
• 格式：
  • owner/repo@tag
• 示例：

Yaml

uses: actions/setup-node@v3

---

🖥️ 7. run（运行命令）

• 用途：在 runner 上运行 shell 命令。
• 默认 shell：
  • Linux/macOS: bash
  • Windows: pwsh
• 示例：

Yaml

run: npm install

---

📦 8. with（传递参数）

• 用途：向某个 Action 传递参数。
• 示例：

Yaml

- name: Setup Node.js

  uses: actions/setup-node@v3

  with:

    node-version: 18.x

---

🔐 9. env（环境变量）

• 用途：定义环境变量供整个任务或步骤使用。
• 示例：

Yaml

env:

  MY_VAR: "Hello"

steps:

  - run: echo $MY_VAR

---

🔄 10. if（条件判断）

• 用途：根据条件决定是否运行某个任务或步骤。
• 支持表达式：github.event_name == 'pull_request'
• 示例：

Yaml

if: github.event_name == 'push'

---

📦 11. strategy（策略）

• 用途：定义任务的构建矩阵，用于并行运行多个配置。
• 示例：

Yaml

strategy:

  matrix:

    node-version: [14.x, 16.x, 18.x]

---

⏱️ 12. timeout-minutes（超时时间）

• 用途：设置任务或步骤的最大运行时间（分钟）。
• 示例：

Yaml

jobs:

  my-job:

    timeout-minutes: 15

---

📁 13. permissions（权限控制）

• 用途：控制工作流对 GitHub API 的访问权限。
• 示例：

Yaml

permissions:

  contents: read

  issues: write

---

🧪 14. continue-on-error（出错继续）

• 用途：即使某步骤或任务失败，也继续执行后续步骤。
• 示例：

Yaml

steps:

  - run: some-command

    continue-on-error: true

---

📌 15. needs（任务依赖）

• 用途：指定当前任务依赖于其他任务，必须在它们成功后才能运行。
• 示例：

Yaml

jobs:

  job1:

    ...

  job2:

    needs: job1

---

🧵 16. concurrency（并发控制）

• 用途：限制同时运行的工作流或任务数量，避免资源冲突。
• 示例：

Yaml

concurrency: ci-${{ github.ref }}

---

🧵 17. jobs.<job_id>.name（步骤名称）

• 用途：为某个步骤定义一个显示名称。
• 示例：

Yaml

- name: Build Application

  run: npm run build

---

📝 18. run-name（运行名称）

• 用途：定义工作流运行时显示的名称（支持变量）。
• 示例：

Yaml

name: CI

on: [push]

run-name: ${{ github.actor }} is running CI

---

🧪 19. jobs.<job_id>.if（任务级条件判断）

• 用途：根据条件决定是否运行某个任务。
• 示例：

Yaml

jobs:

  deploy:

    if: github.ref == 'refs/heads/main'

---

📦 20. jobs.<job_id>.env（任务级环境变量）

• 用途：为特定任务定义环境变量。
• 示例：

Yaml

jobs:

  build:

    env:

      ENV_NAME: value

---

🧪 21. jobs.<job_id>.steps.env（步骤级环境变量）

• 用途：为某个步骤定义局部环境变量。
• 示例：

Yaml

- name: Run Script

  run: echo $HELLO

  env:

    HELLO: Hello World

---

📦 22. jobs.<job_id>.services（服务容器）

• 用途：为任务定义一个或多个服务容器（如数据库）。
• 示例：

Yaml

services:

  redis:

    image: redis

    ports:

      - 6379

---

🧪 23. jobs.<job_id>.container（容器环境）

• 用途：指定任务运行在特定容器中。
• 示例：

Yaml

container:

  image: node:18

  env:

    NODE_ENV: development

---

🧪 24. jobs.<job_id>.outputs（任务输出）

• 用途：定义任务的输出值，供后续任务使用。
• 示例：

Yaml

outputs:

  result: ${{ steps.step1.outputs.some_value }}

---

🧪 25. jobs.<job_id>.steps.outputs（步骤输出）

• 用途：为某个步骤定义输出值，供后续步骤或任务使用。
• 示例：

Yaml

- id: step1

  run: echo "some_value=Hello" >> $GITHUB_OUTPUT

---

🧪 26. jobs.<job_id>.steps.id（步骤 ID）

• 用途：为步骤定义一个 ID，用于引用输出或条件判断。
• 示例：

Yaml

- id: build

  run: make build

---

🧪 27. jobs.<job_id>.steps.run（运行命令）

• 用途：在 runner 上执行 shell 命令。
• 支持多行命令：

Yaml

run: |

  npm install

  npm run build

---

🧪 28. jobs.<job_id>.steps.shell（自定义 Shell）

• 用途：指定运行命令使用的 shell。
• 示例：

Yaml

shell: bash

run: echo "Hello"

---

🧪 29. jobs.<job_id>.steps.timeout-minutes（步骤超时）

• 用途：为单个步骤设置最大运行时间。
• 示例：

Yaml

- run: long-command

  timeout-minutes: 5

---

🧪 30. jobs.<job_id>.steps.continue-on-error（步骤出错继续）

• 用途：即使某个步骤失败，也继续执行后续步骤。
• 示例：

Yaml

- run: might-fail

  continue-on-error: true

---

🧪 31. jobs.<job_id>.steps.working-directory（工作目录）

• 用途：为某个步骤指定工作目录。
• 示例：

Yaml

• name: Run in subdir

run: ls

working-directory: subdirectory

---

🧪 32. jobs.<job_id>.steps.uses（使用 Action）

• 用途：调用一个已封装好的 Action。
• 示例：

Yaml

uses: actions/setup-python@v4

---

🧪 33. jobs.<job_id>.steps.with（Action 参数）

• 用途：传递 Action 所需的参数。
• 示例：

Yaml

with:

python-version: 3.10

---

🧪 34. jobs.<job_id>.steps.env（Action 环境变量）

• 用途：为 Action 设置环境变量。
• 示例：

Yaml

env:

API_KEY: ${{ secrets.API_KEY }}

---

📁 35. jobs.<job_id>.steps.id（Action ID）

• 用途：为步骤命名 ID，用于引用其输出。
• 示例：

Yaml

• id: fetch

uses: some-action

• run: echo ${{ steps.fetch.outputs.result }}

---

🧪 36. jobs.<job_id>.steps.if（步骤条件判断）

• 用途：根据条件决定是否运行该步骤。
• 示例：

Yaml

if: ${{ github.event_name == 'push' }}

---

🧪 37. jobs.<job_id>.steps.name（步骤名称）

• 用途：为步骤命名，便于识别。
• 示例：

Yaml

• name: Install Dependencies

run: npm install

---

🧪 38. jobs.<job_id>.steps.run（运行脚本）

• 用途：执行任意 shell 命令。
• 示例：

Yaml

run: make test

---

🧪 39. jobs.<job_id>.steps.continue-on-error（继续执行）

• 用途：即使该步骤失败也继续执行。
• 示例：

Yaml

continue-on-error: true

---

🧪 40. jobs.<job_id>.steps.timeout-minutes（步骤超时）

• 用途：为某个步骤设置最大执行时间。
• 示例：

Yaml

timeout-minutes: 10

---

🧪 41. jobs.<job_id>.steps.working-directory（运行目录）

• 用途：为某个步骤指定运行目录。
• 示例：

Yaml

working-directory: src/

---

🧪 42. jobs.<job_id>.steps.shell（自定义 Shell）

• 用途：为某个步骤指定 shell。
• 示例：

Yaml

shell: pwsh

run: Write-Host "Hello"

---

🧪 43. jobs.<job_id>.steps.env（设置环境变量）

• 用途：为步骤设置局部环境变量。
• 示例：

Yaml

env:

DEBUG: true

---

🧪 44. jobs.<job_id>.steps.uses（调用 Action）

• 用途：调用一个封装好的 Action。
• 示例：

Yaml

uses: actions/upload-artifact@v3

---

🧪 45. jobs.<job_id>.steps.with（Action 参数）

• 用途：为 Action 传递参数。
• 示例：

Yaml

with:

name: my-artifact

path: dist/

---

📁 46. jobs.<job_id>.steps.id（步骤 ID）

• 用途：为该步骤指定一个 ID，用于后续引用。
• 示例：

Yaml

id: test

---

🧪 47. jobs.<job_id>.steps.run（运行命令）

• 用途：在 runner 上运行命令。
• 示例：

Yaml

run: echo "Build complete"

---

🧪 48. jobs.<job_id>.steps.env（环境变量）

• 用途：为步骤设置环境变量。
• 示例：

Yaml

env:

PORT: 8080

---

🧪 49. jobs.<job_id>.steps.if（条件运行）

• 用途：根据表达式判断是否运行该步骤。
• 示例：

Yaml

if: ${{ github.actor == 'dependabot[bot]' }}

---

🧪 50. jobs.<job_id>.steps.name（步骤名称）

• 用途：为步骤命名，显示在 GitHub 界面中。
• 示例：

Yaml

name: Run Tests