GitHub Actions 详细使用指南

三、触发事件配置

3.1 常见触发事件

on:
  # 推送代码时触发
  push:
    branches:
      - main
      - 'releases/**'
    tags:
      - 'v*'
  # 拉取请求时触发
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
  # 定时触发
  schedule:
    - cron: '0 2 * * *'  # 每天 UTC 时间 2:00
  # 手动触发
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        default: 'staging'
  # 仓库事件触发
  release:
    types: [published]
  # 问题事件触发
  issues:
    types: [opened, labeled]

四、作业和步骤配置

4.1 作业的基本结构

jobs:
  test:
    runs-on: ubuntu-latest
    name: Test on Ubuntu
    env:
      NODE_ENV: test
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    needs: [lint]  # 等待 lint 作业完成
    if: github.event_name == 'pull_request'  # 条件执行
    strategy:
      matrix:
        node-version: [14, 16, 18]
        os: [ubuntu-latest, windows-latest]
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - name: Run tests
        run: |
          npm ci
          npm test -- --coverage
        continue-on-error: false  # 失败时停止

五、常用 Actions 示例

5.1 代码检查和测试

steps:
  - name: Code Checkout
    uses: actions/checkout@v3
  - name: ESLint
    uses: reviewdog/action-eslint@v1
  - name: Run Unit Tests
    uses: nick-fields/retry@v2
    with:
      timeout_minutes: 10
      max_attempts: 3
      command: npm test
  - name: Upload Coverage
    uses: codecov/codecov-action@v3
    with:
      files: ./coverage/lcov.info

5.2 构建和部署

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

5.3 Docker 构建和推送

name: Docker Build and Push
on:
  push:
    branches: [main]
    tags: ['v*']
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
      - name: Log in to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v4
        with:
          images: myorg/myapp
      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

六、环境变量和 Secrets

6.1 环境变量管理

env:
  NODE_ENV: production
  API_URL: https://api.example.com
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://myapp.com
    steps:
      - name: Use environment variables
        run: |
          echo "Database URL: ${{ secrets.DATABASE_URL }}"
          echo "API Key: ${{ secrets.API_KEY }}"

6.2 Secrets 使用

在仓库 Settings → Secrets and variables → Actions 中添加：

steps:
  - name: Use Secret
    env:
      SUPER_SECRET: ${{ secrets.MY_SECRET }}
    run: |
      echo "Secret length is ${#SUPER_SECRET}"

七、缓存和依赖管理

steps:
  - uses: actions/checkout@v3
  - name: Cache node modules
    uses: actions/cache@v3
    env:
      cache-name: cache-node-modules
    with:
      path: ~/.npm
      key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-build-${{ env.cache-name }}-
        ${{ runner.os }}-build-
        ${{ runner.os }}-
  - name: Install Dependencies
    run: npm ci

八、高级功能

8.1 工作流程复用

# .github/workflows/reusable-workflow.yml
name: Reusable Workflow
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      node-version:
        required: false
        type: string
        default: '18'
    secrets:
      api-token:
        required: true
jobs:
  reusable-job:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to ${{ inputs.environment }}"
      - run: echo "Using Node ${{ inputs.node-version }}"

8.2 自托管运行器

1. 在 Settings → Actions → Runners 中添加
2. 配置标签：

jobs:
  build:
    runs-on: [self-hosted, linux, x64, gpu]

8.3 Artifacts 上传下载

steps:
  - name: Create artifact
    run: echo "Hello World" > hello.txt
  - name: Upload artifact
    uses: actions/upload-artifact@v3
    with:
      name: my-artifact
      path: hello.txt
      retention-days: 7
  # 在其他作业中下载
  - name: Download artifact
    uses: actions/download-artifact@v3
    with:
      name: my-artifact

九、调试和监控

9.1 调试工作流

steps:
  - name: Debug info
    run: |
      echo "Event: ${{ github.event_name }}"
      echo "Ref: ${{ github.ref }}"
      echo "SHA: ${{ github.sha }}"
      echo "Actor: ${{ github.actor }}"
      echo "Workflow: ${{ github.workflow }}"

9.2 使用 tmate 实时调试

- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  if: ${{ github.event_name == 'pull_request' && failure() }}

十、最佳实践

10.1 安全性

# 最小权限原则
permissions:
  contents: read
  actions: read
  checks: write
# 使用签名验证
- name: Verify commit signature
  run: |
    if ! git verify-commit ${{ github.sha }}; then
      echo "Commit signature verification failed!"
      exit 1
    fi

10.2 性能优化

1. 使用缓存依赖
2. 并行化作业
3. 选择合适的环境
4. 及时清理 artifacts

10.3 错误处理

steps:
  - name: Try something
    run: ./script.sh
    continue-on-error: true
  - name: Check failure
    if: ${{ failure() && steps.previous-step.conclusion == 'failure' }}
    run: echo "Previous step failed"

十一、完整示例

name: Full CI/CD Pipeline
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run lint
  test:
    runs-on: ${{ matrix.os }}
    needs: lint
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [16, 18]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - uses: actions/cache@v3
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
      - run: npm ci
      - run: npm test
      - uses: actions/upload-artifact@v3
        if: ${{ success() }}
        with:
          name: test-results-${{ matrix.os }}-${{ matrix.node-version }}
          path: test-results/
  deploy:
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
    environment: production
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run build
      - name: Deploy to Production
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /var/www/myapp
            git pull
            npm ci --production
            pm2 restart myapp

十二、学习资源

1. 官方文档：https://docs.github.com/actions
2. GitHub Actions 市场：https://github.com/marketplace?type=actions
3. 社区资源：
   • GitHub Actions 官方博客
   • Awesome Actions (GitHub 仓库)
   • GitHub Skills 课程

本文涵盖了 GitHub Actions 的主要功能和最佳实践。根据具体需求，您可以选择合适的配置来优化您的自动化工作流程。