描述标准工作流语法元素

已完成

GitHub Actions 工作流将 YAML 语法与定义自动化运行时间、地点和方式的特定元素配合使用。 了解这些核心语法元素对于创建有效的工作流至关重要。

基本工作流元素

顶级工作流配置

name: CI/CD Pipeline # Workflow name (optional but recommended)
on: # Event triggers
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 2 * * 1" # Weekly Monday 2 AM UTC

jobs:# Job definitions
  # Job configurations go here

介绍的核心语法元素

元素	目的	必选	Example
name	GitHub UI 中的工作流显示名称	可选	name: "Build and Test"
on	工作流执行的事件触发器	必需	on: [push, pull_request]
jobs	要执行的作业集合	必需	jobs: build: ...
runs-on	指定运行器环境	必需	runs-on: ubuntu-latest
steps	作业中的顺序操作	必需	steps: - name: ...
uses	引用预生成的操作	可选	uses: actions/checkout@v4
run	执行 shell 命令	可选	run: npm test

完整的工作流示例

name: Node.js CI/CD Pipeline

# Event configuration
on:
  push:
    branches: [main, develop]
    paths-ignore: ["docs/**", "*.md"]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

# Environment variables (workflow-level)
env:
  NODE_VERSION: "20"
  CI: true

# Job definitions
jobs:
  # Test job
  test:
    name: Run Tests
    runs-on: ubuntu-latest

    # Job-level environment variables
    env:
      DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

    # Job steps
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: "npm"

      - name: Install dependencies
        run: |
          npm ci
          npm audit --audit-level=high

      - name: Run tests
        run: |
          npm run test:coverage
          npm run test:integration
        env:
          NODE_ENV: test

      - name: Upload coverage reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-reports
          path: coverage/
          retention-days: 30

  # Build job (depends on test)
  build:
    name: Build Application
    needs: test
    runs-on: ubuntu-latest

    outputs:
      build-version: ${{ steps.version.outputs.version }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: "npm"

      - name: Install and build
        run: |
          npm ci --production
          npm run build

      - name: Generate version
        id: version
        run: |
          VERSION=$(date +%Y%m%d)-${GITHUB_SHA::8}
          echo "version=$VERSION" >> $GITHUB_OUTPUT

      - name: Save build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-${{ steps.version.outputs.version }}
          path: |
            dist/
            package.json

高级语法元素

条件执行

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main' && success()
    run: ./deploy.sh

  - name: Notify on failure
    if: failure()
    run: ./notify-failure.sh

矩阵策略

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20, 22]
        include:
          - os: ubuntu-latest
            node-version: 22
            experimental: true
      fail-fast: false
    runs-on: ${{ matrix.os }}

可重用工作流

jobs:
  call-reusable-workflow:
    uses: ./.github/workflows/reusable-tests.yml
    with:
      environment: production
      node-version: "20"
    secrets:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

工作流语法的最佳做法

结构和组织

• 对工作流、作业和步骤使用描述性名称
• 在作业中以逻辑方式对相关步骤进行分组
• 使工作流专注于特定目的（CI、CD、维护）

效率优化

• 使用 paths 和 paths-ignore 限制不必要的运行
• 使用 actions/cache 或内置缓存缓存依赖项
• 并行运行独立作业

安全注意事项

permissions:
  contents: read
  security-events: write
  pull-requests: write

env:
  # Use secrets for sensitive data
  API_KEY: ${{ secrets.API_KEY }}
  # Use variables for non-sensitive configuration
  ENVIRONMENT: ${{ vars.ENVIRONMENT }}

错误处理和调试

steps:
  - name: Debug information
    if: env.ACTIONS_STEP_DEBUG == 'true'
    run: |
      echo "Runner OS: $RUNNER_OS"
      echo "Workflow: $GITHUB_WORKFLOW"
      echo "Event: $GITHUB_EVENT_NAME"

有关全面的语法文档，请参阅 GitHub Actions 的官方工作流语法 参考。