GitHub Actions 工作流文件结构 #

.github/
└── workflows/
    ├── ci.yml
    ├── deploy.yml
    └── release.yml

# 推荐的命名方式
ci.yml              # 持续集成
cd.yml              # 持续部署
test.yml            # 测试工作流
release.yml         # 发布工作流
security-scan.yml   # 安全扫描

# 正确
jobs:
  build:
    runs-on: ubuntu-latest

# 错误 - 使用了Tab
jobs:
	build:
		runs-on: ubuntu-latest

name: My Workflow
on: push
runs-on: ubuntu-latest

on:
  - push
  - pull_request

# 或使用内联格式
on: [push, pull_request]

# 使用 | 保留换行
run: |
  echo "Line 1"
  echo "Line 2"
  echo "Line 3"

# 使用 > 折叠换行
description: 了解GitHub Actions工作流YAML文件的结构、语法和配置选项。
  This is a long
  description that
  will be folded.

# 这是单行注释

name: My Workflow  # 行尾注释

jobs:
  # 这是作业注释
  build:
    runs-on: ubuntu-latest

# 工作流名称
name: Workflow Name

# 触发器配置
on:
  push:
    branches: [main]

# 环境变量（全局）
env:
  GLOBAL_VAR: value

# 默认配置
defaults:
  run:
    shell: bash

# 并发控制
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# 作业定义
jobs:
  job1:
    # 作业配置
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello"

# 简单名称
name: CI

# 带emoji的名称
name: 🚀 Deploy

# 带描述的名称
name: "Build, Test and Deploy"

on: push

on: [push, pull_request]

# 或
on:
  - push
  - pull_request

on:
  push:
    branches:
      - main
      - 'release/**'
    paths:
      - 'src/**'
      - 'tests/**'
    paths-ignore:
      - '**.md'
      
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize

on:
  schedule:
    - cron: '0 0 * * *'     # 每天UTC 0点
    - cron: '0 0 * * 1'     # 每周一UTC 0点

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      debug:
        description: 'Enable debug mode'
        required: false
        type: boolean
        default: false

env:
  NODE_VERSION: '20'
  CI: true

jobs:
  build:
    env:
      JOB_VAR: value

steps:
  - name: Step with env
    env:
      STEP_VAR: value
    run: echo $STEP_VAR

defaults:
  run:
    shell: bash
    working-directory: ./app

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: pwd  # 在 ./app 目录执行

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  job-id:           # 作业标识符，必须以字母或_开头
    name: Job Name  # 显示名称（可选）
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building..."
  
  test:
    needs: build    # 依赖build作业
    runs-on: ubuntu-latest
    steps:
      - run: echo "Testing..."
  
  deploy:
    needs: [build, test]  # 依赖多个作业
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying..."

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production"

jobs:
  test:
    strategy:
      matrix:
        node: [16, 18, 20]
        os: [ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

steps:
  - name: Run single command
    run: echo "Hello"
  
  - name: Run multiple commands
    run: |
      echo "Line 1"
      echo "Line 2"

steps:
  - name: Checkout code
    uses: actions/checkout@v4
  
  - name: Setup Node
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

steps:
  - name: Only on main branch
    if: github.ref == 'refs/heads/main'
    run: echo "This is main branch"
  
  - name: On success
    if: success()
    run: echo "Previous steps succeeded"
  
  - name: On failure
    if: failure()
    run: echo "Previous steps failed"
  
  - name: Always run
    if: always()
    run: echo "This always runs"

steps:
  - name: With environment variables
    env:
      MY_VAR: value
      ANOTHER_VAR: another
    run: |
      echo $MY_VAR
      echo $ANOTHER_VAR

steps:
  - name: Run in specific directory
    working-directory: ./subdir
    run: pwd

steps:
  - name: Using bash
    run: echo $PATH
    shell: bash
  
  - name: Using PowerShell
    run: Write-Host "Hello"
    shell: pwsh
  
  - name: Using Python
    run: print("Hello")
    shell: python

jobs:
  build:
    outputs:
      version: ${{ steps.get_version.outputs.version }}
    steps:
      - id: get_version
        run: echo "version=1.0.0" >> $GITHUB_OUTPUT
  
  deploy:
    needs: build
    steps:
      - run: echo "Deploying version ${{ needs.build.outputs.version }}"

steps:
  - id: set_var
    run: echo "my_var=hello" >> $GITHUB_OUTPUT
  
  - name: Use output
    run: echo "The value is ${{ steps.set_var.outputs.my_var }}"

name: Complete Workflow Example

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy environment'
        required: true
        default: 'staging'
        type: choice
        options: [staging, production]

env:
  NODE_VERSION: '20'
  CI: true

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm ci
      - run: npm run lint

  test:
    needs: lint
    strategy:
      matrix:
        node: [16, 18, 20]
        os: [ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    outputs:
      artifact: ${{ steps.build.outputs.artifact }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm ci
      - run: npm run build
      - id: build
        run: echo "artifact=dist" >> $GITHUB_OUTPUT
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment || 'staging' }}
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
      - name: Deploy
        run: echo "Deploying to ${{ github.event.inputs.environment || 'staging' }}"

# 安装actionlint
go install github.com/rhysd/actionlint/cmd/actionlint@latest

# 验证工作流文件
actionlint .github/workflows/ci.yml

# 错误
jobs:
build:
runs-on: ubuntu-latest

# 正确
jobs:
  build:
    runs-on: ubuntu-latest

# 包含特殊字符时需要引号
run: echo "Hello: World"

# 普通字符串可以不加引号
run: echo Hello World

# 正确的布尔值
if: true
if: false

# 错误 - 字符串不是布尔值
if: "true"  # 这是字符串