GitHub Actions 简介

GitHub Actions 是 GitHub 提供的持续集成和持续部署（CI/CD）平台，允许你在 GitHub 仓库中自动构建、测试和部署代码。

核心概念

概念	说明
Workflow	整个自动化流程，定义在 .github/workflows/*.yml 文件中
Job	一个_job_是你同意在同一运行器上执行的一组步骤
Step	步骤，可以执行命令或使用 Action
Action	可复用的动作单元，是 Workflow 的基本构建块

Workflow 文件结构

name: CI Workflow

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

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

触发条件（on）

# 推送时触发
on: push

# 指定分支
on:
  push:
    branches:
      - main
      - develop

# PR 时触发
on: pull_request

# 定时触发 (cron 格式，UTC 时间)
on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨2点

# 手动触发
on:
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        default: 'staging'

# 仓库事件触发
on:
  repository_dispatch:
    types: [deploy-production]

jobs 与 runs-on

jobs:
  build:
    runs-on: ubuntu-latest  # GitHub 托管的运行器
    # runs-on: self-hosted   # 自托管运行器

  test:
    runs-on: ubuntu-latest
    needs: build  # 依赖 build job

  deploy:
    runs-on: ubuntu-latest
    needs: [build, test]  # 依赖多个 job

steps 与 uses / run

steps:
  # 使用 Action
  - uses: actions/checkout@v4

  # 使用 Action 并设置参数
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  # 执行命令
  - name: Install dependencies
    run: npm ci

  # 多行命令
  - name: Build
    run: |
      npm run lint
      npm run build

  # 设置输出供后续 step 使用
  - id: version
    run: echo "VERSION=$(npm pkg get version)" >> $GITHUB_OUTPUT

环境变量与 Secrets

环境变量

env:
  NODE_ENV: production
  API_URL: https://api.example.com

jobs:
  build:
    env:
      NODE_ENV: development
    steps:
      - run: echo ${{ env.NODE_ENV }}

Secrets

在仓库 Settings → Secrets and variables → Actions 中配置敏感信息。

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
        run: |
          curl -X POST https://api.example.com/deploy \
            -H "Authorization: Bearer $API_TOKEN"

条件执行

if 条件判断

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # 仅在 main 分支推送时执行
      - name: Deploy to production
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        run: npm run deploy:prod

      # 仅在 PR 时执行
      - name: Preview deploy
        if: github.event_name == 'pull_request'
        run: npm run deploy:preview

      # 基于步骤结果执行
      - name: Notify
        if: failure()
        run: echo "Job failed!"

matrix 并行矩阵

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

  # 失败时停止其他 job
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: [12, 14, 16]
      fail-fast: true

缓存优化

actions/cache

steps:
  - uses: actions/checkout@v4

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

npm/pnpm 依赖缓存

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'  # 自动缓存 node_modules

  - run: npm ci

# pnpm
- uses: pnpm/action-setup@v3
  with:
    version: 8

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'

- run: pnpm install --frozen-lockfile

常用 Action

actions/checkout

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 完整克隆， 用于 git 操作
    token: ${{ secrets.GITHUB_TOKEN }}  # 自动获得

actions/setup-node

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # npm/pnpm/yarn
    cache-dependency-path: '**/package-lock.json'

actions/cache

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

peaceiris/actions-gh-pages

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist
    publish_branch: gh-pages

前端项目完整 CI 流程示例

name: Frontend CI

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

env:
  NODE_VERSION: '20'

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

  test:
    name: Test
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage

  build:
    name: Build
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist
          retention-days: 7

  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

进阶技巧

复用 Action

workflow_dispatch（手动触发）

on:
  workflow_dispatch:
    inputs:
      tag:
        description: '镜像版本'
        required: true
        type: string
      environment:
        description: '部署环境'
        required: true
        type: choice
        options:
          - staging
          - production

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: |
          echo "Deploying ${{ github.event.inputs.tag }} to ${{ github.event.inputs.environment }}"

触发方式：

gh workflow run deploy.yml -f tag=v1.0.0 -f environment=production

repository_dispatch（外部触发）

on:
  repository_dispatch:
    types: [deploy-request]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: echo "Deploying..."

外部触发（需 GitHub Token）：

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/dispatches \
  -d '{"event_type":"deploy-request","client_payload":{"environment":"prod"}}'

并行任务优化

jobs:
  # 独立的并行任务
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint

  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run type-check

  # 依赖检查可以并行运行
  dependency-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm audit

  # 只有所有检查通过后才构建
  build:
    runs-on: ubuntu-latest
    needs: [lint, type-check, dependency-audit]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build

使用 Concurrency 避免重复运行

on:
  push:
    branches: [main]

# 同一分支的新 push 会取消之前的 workflow
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # ...

贡献者: Ra1n

上一页Jenkins CI/CD

下一页Docker