github-actions

用途

GitHub Actions 用于在 GitHub 仓库中直接自动化软件工作流。本技能适用于以下场景：为 GitHub 仓库搭建 CI/CD 流水线；自动化构建、测试与部署工作流；创建可复用的工作流组件；配置自托管运行器；管理工作流密钥与变量；调试失败的工作流运行。

前提条件

具有写权限的 GitHub 仓库
了解 YAML 语法
使用自托管运行器时：需要一台带 Docker 的服务器（可选）

工作流文件结构

工作流定义在 .github/workflows/ 目录中。示例：

name: CI Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

常见触发器

推送与拉取请求：

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'package.json'
  pull_request:
    branches: [main]

定时运行：

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

手动触发：

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

作业配置

矩阵构建：

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

作业依赖：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

环境保护：

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - run: ./deploy.sh

密钥与变量

使用密钥：

steps:
  - name: Deploy
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    run: aws s3 sync ./dist s3://my-bucket

使用变量：

steps:
  - name: Build
    env:
      API_URL: ${{ vars.API_URL }}
    run: npm run build

缓存依赖

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

制品

上传制品：

- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/
    retention-days: 5

下载制品：

- uses: actions/download-artifact@v4
  with:
    name: build-output
    path: dist/

Docker 构建

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: user/app:latest

可复用工作流

定义可复用工作流：

# .github/workflows/reusable-deploy.yml
name: Reusable Deploy

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      deploy_key:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - run: echo "Deploying to ${{ inputs.environment }}"

调用可复用工作流：

jobs:
  deploy-staging:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: staging
    secrets:
      deploy_key: ${{ secrets.STAGING_KEY }}

自托管运行器

注册运行器：

# Download runner
mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-x64.tar.gz -L https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-2.311.0.tar.gz
tar xzf actions-runner-linux-x64.tar.gz

# Configure
./config.sh --url https://github.com/OWNER/REPO --token TOKEN

# Run
./run.sh

使用自托管运行器：

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4

调试工作流

启用调试日志，设置仓库密钥：

ACTIONS_RUNNER_DEBUG: true
ACTIONS_STEP_DEBUG: true

调试步骤：

- name: Debug
  run: |
    echo "GitHub context: ${{ toJson(github) }}"
    echo "Job context: ${{ toJson(job) }}"

常见问题

问题：工作流未触发

现象：推送/拉取请求时工作流不运行
解决：检查分支过滤器、路径过滤器，并确保工作流文件位于默认分支

问题：权限被拒绝

现象：Actions 无法推送或创建 PR
解决：在工作流中配置权限或更新仓库设置

permissions:
  contents: write
  pull-requests: write

问题：缓存未恢复

现象：已有缓存但仍未命中
解决：验证缓存键完全匹配，检查运行器操作系统

最佳实践

将 action 版本固定到特定提交或标签
使用缓存加速依赖安装与构建
通过环境作用域最小化密钥暴露
使用矩阵构建进行跨平台测试
使用 continue-on-error 实现适当的错误处理
通过可复用工作流和复合 action 保持工作流 DRY

技能介绍

用途