GitHub Actions 完全指南 - Everything in Claude-Code

30 秒创建一个工作流

在项目根目录创建 .github/workflows/your-workflow.yml：

name: CI
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Run a script
      run: echo "Hello, GitHub Actions!"

推送代码后自动触发。无需服务器，无需配置。

免费资源额度

🖥️

2 核 CPU

GitHub 托管运行器默认配置，公共仓库无并发限制。

💾

7GB 内存

足够运行大多数构建、测试和打包任务。

💽

14GB SSD

存储代码、依赖和构建产物。

⏱️

2000 分钟/月

免费账户每月可用时间，公共仓库 Actions 无限制。

工作流核心结构

一个工作流由 4 层组成：Workflow → Job → Step → Action。

层级	说明	关键属性
Workflow	顶层自动化流程	`on` 触发条件、`jobs` 任务列表
Job	同一运行器内的一组步骤	`runs-on`、`needs` 依赖、`if` 条件
Step	单个命令或 Action 调用	`run` 命令、`uses` 引用、`id` 输出
Action	可复用代码模块	GitHub Marketplace、本地 `./`、远程仓库
Runner	执行作业的虚拟机/容器	ubuntu-latest、macos-latest、windows-latest

工作流生命周期

1. 初始化

读取 YAML 文件，创建工作流运行实例，解析触发事件与变量。

2. DAG 执行

根据 needs 构建有向无环图。无依赖的 Job 并行执行，有依赖的按拓扑顺序运行。

3. 步骤顺序执行

每个 Job 内的 Step 严格串行。失败即停止（可用 continue-on-error: true 覆盖）。

4. 产物与缓存

用 actions/upload-artifact 和 actions/download-artifact 跨 Job 共享文件；用 actions/cache 加速依赖安装。

5. 完成通知

最终状态：Success / Failure / Cancelled。可配置 Slack、邮件等通知。

性能优化策略

并行化

删除不必要的 needs 依赖。把代码检查、单元测试等快速步骤放在前面，构建和集成测试放在后面。

缓存依赖

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

构建产物复用

构建一次，通过 artifacts 在多个 Job 间共享，避免重复编译。

矩阵策略

用 strategy.matrix 在多个 OS / 语言版本下并行测试，用 max-parallel 控制并发数。

并发控制

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

避免同一分支多次推送导致的工作流堆积。

CI Vitals：三个核心监控指标

🏎️

WET

Workflow Execution Time。工作流执行总时间。追踪 p75 和 p90 分布，识别变慢趋势。

🎯

NFR

Noise-to-Fix Ratio。基础设施失败 vs 真实 Bug 的比例。高 NFR 意味着团队对流水线失去信任。

🗑️

POT

Pipeline Overhead Time。排队、重试、缓存未命中导致的额外耗时。优化缓存键和并发策略可降低。

诊断速查

指标下降	排查重点	快速修复
WET 高	依赖链过长、缓存未命中、重复构建	删除多余 needs、加缓存、artifact 复用
NFR 高	网络超时、外部服务不稳定、 flaky tests	加重试、设置超时、隔离外部依赖
POT 高	排队时间、重试频率、缓存命中率低	优化缓存键、合并步骤、智能并发

实战：自动构建 Docker 镜像

name: Docker CI
on:
  push:
    branches: [main]

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

    - name: Build and push
      env:
        REPO: ${{ secrets.DOCKER_REPOSITORY }}
        USER: ${{ secrets.DOCKER_USERNAME }}
        PASS: ${{ secrets.DOCKER_PASSWORD }}
      run: |
        docker login -u $USER -p $PASS
        docker build -t $REPO:${{ github.sha }} .
        docker push $REPO:${{ github.sha }}

    - name: Deploy
      run: echo "Deploy success!"

每次推送到 main 分支，自动构建并推送带 commit hash 标签的 Docker 镜像。

进阶技巧

密钥管理

敏感信息绝不硬编码。使用 GitHub Secrets + ${{ secrets.NAME }} 注入。

工作流复用

# .github/workflows/reusable.yml
on:
  workflow_call:

jobs:
  reusable_job:
    runs-on: ubuntu-latest
    steps:
      - run: echo "I'm reusable!"

# 调用方
jobs:
  call:
    uses: ./.github/workflows/reusable.yml

定时触发

on:
  schedule:
    - cron: '0 0 * * *'  # 每天零点

条件执行

if: github.ref == 'refs/heads/main' && github.event_name == 'push'

# 或基于前序结果
if: always()  # 即使失败也执行
if: failure()  # 仅失败时执行