本项目的 CI/CD 自动化流程完全指南
工作流是 GitHub Actions 的核心概念，是一个自动化流程的定义文件。
.github/workflows/ # 固定目录名，GitHub会自动识别
├── ci.yml # 主CI/CD工作流
└── publish-report.yml # 测试报告发布工作流
重要规则：
.github/workflows/ 目录下的 .yml 或 .yaml 文件都会被GitHub识别为工作流触发事件 (push/PR/手动)
↓
┌────────────────────────────────────────┐
│ 工作流1: C++ CI/CD Pipeline │
│ 文件: ci.yml │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Job 1: build-and-test │ │
│ │ ├─ Ubuntu 构建和测试 │ │
│ │ ├─ macOS 构建和测试 │ │
│ │ └─ Windows 构建和测试 │ │
│ └──────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Job 2: code-quality │ │
│ │ └─ 代码格式检查 │ │
│ └──────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Job 3: summary │ │
│ │ └─ 生成执行摘要 │ │
│ └──────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Job 4: release │ │
│ │ └─ 创建GitHub Release │ │
│ └──────────────────────────────────┘ │
└────────────────────────────────────────┘
↓ (完成后自动触发)
┌────────────────────────────────────────┐
│ 工作流2: Publish Test Report │
│ 文件: publish-report.yml │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Job: publish-report │ │
│ │ ├─ 下载构建产物 │ │
│ │ ├─ 生成HTML报告 │ │
│ │ └─ 发布到GitHub Pages │ │
│ └──────────────────────────────────┘ │
└────────────────────────────────────────┘
↓
用户可访问的测试报告网页
ci.yml)这是主要的CI/CD工作流，负责构建、测试和发布。
on:
push:
branches: [ main, master ] # 推送到main/master分支
pull_request:
branches: [ main, master ] # 创建PR到main/master
workflow_dispatch: # 手动触发
触发方式：
并行在3个平台上构建和测试：
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
关键步骤：
矩阵策略的优势：
fail-fast: false)代码质量检查：
clang-format 检查代码格式生成执行摘要：
needs: [build-and-test, code-quality] # 依赖前两个任务
if: always() # 即使失败也运行
自动创建Release：
if: startsWith(github.ref, 'refs/tags/v') ||
(github.event_name == 'push' && github.ref == 'refs/heads/main')
触发条件：
v 开头的tag（如 v1.0.0）功能：
.tar.gz / .zip）publish-report.yml)生成和发布精美的HTML测试报告。
on:
workflow_run:
workflows: ["C++ CI/CD Pipeline"] # 监听CI/CD工作流
types:
- completed # 完成时触发
说明：
uses: actions/download-artifact@v4
with:
run-id: $
uses: peaceiris/actions-gh-pages@v3
with:
publish_dir: ./public
输出：
https://tyk-lab.github.io/test-github-cicd/每个工作流文件都遵循相同的结构：
# 1. 工作流名称
name: 工作流名称
# 2. 触发条件
on:
push:
branches: [ main ]
workflow_dispatch:
# 3. 权限配置（可选）
permissions:
contents: write
# 4. 任务定义
jobs:
# 任务1
job-name-1:
runs-on: ubuntu-latest
steps:
- name: 步骤1
run: echo "Hello"
- name: 步骤2
uses: actions/checkout@v4
# 任务2（依赖任务1）
job-name-2:
needs: [job-name-1]
runs-on: ubuntu-latest
steps:
- name: 步骤1
run: echo "World"
完整的自动化流程，定义在 .yml 文件中。
工作流中的一个执行单元，可以包含多个步骤。
特点：
needs）任务中的具体操作。
两种类型：
run)
```yaml
uses)
```yaml
用同一套步骤在多个环境下运行。
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node: [14, 16, 18]
# 这将创建 3 × 3 = 9 个并行任务
任务之间共享的文件。
# 上传
- uses: actions/upload-artifact@v4
with:
name: my-artifact
path: build/
# 下载
- uses: actions/download-artifact@v4
with:
name: my-artifact
在 .github/workflows/ 目录下创建新的 .yml 文件：
touch .github/workflows/my-workflow.yml
name: My Custom Workflow
on:
push:
branches: [ main ]
jobs:
my-job:
runs-on: ubuntu-latest
steps:
- name: Hello World
run: echo "Hello from my workflow!"
git add .github/workflows/my-workflow.yml
git commit -m "feat: 添加自定义工作流"
git push
访问：https://github.com/你的用户名/仓库名/actions
name: Daily Report
on:
schedule:
- cron: '0 9 * * *' # 每天UTC 9:00运行
jobs:
report:
runs-on: ubuntu-latest
steps:
- run: echo "生成每日报告"
# workflow-a.yml
name: Workflow A
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: echo "Building..."
---
# workflow-b.yml
name: Workflow B
on:
workflow_run:
workflows: ["Workflow A"] # 监听Workflow A
types: [completed]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- run: echo "Deploying..."
jobs:
deploy:
runs-on: ubuntu-latest
# 只在main分支且推送事件时运行
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
steps:
- run: echo "Deploying to production"
使用 act 在本地运行工作流：
# 安装act
brew install act # macOS
choco install act # Windows
# 运行工作流
act push
- name: 调试信息
run: |
echo "当前分支: $"
echo "事件类型: $"
echo "运行ID: $"
ls -la
env | sort
- name: 进入SSH调试模式
uses: mxschmitt/action-tmate@v3
if: failure() # 失败时才进入
存储敏感信息（API密钥、密码等）：
steps:
- name: 使用Secret
run: echo "API Key: $"
env:
API_KEY: $
设置Secret：
Settings → Secrets and variables → Actions → New repository secret
env:
GLOBAL_VAR: "全局变量"
jobs:
my-job:
env:
JOB_VAR: "任务变量"
steps:
- name: 使用变量
env:
STEP_VAR: "步骤变量"
run: |
echo $GLOBAL_VAR
echo $JOB_VAR
echo $STEP_VAR
加速构建：
- name: 缓存依赖
uses: actions/cache@v3
with:
path: ~/.cache
key: $-build-$
检查清单：
.github/workflows/ 目录下.yml 或 .yamlon:
push:
paths:
- 'src/**' # 只有src目录改变时触发
- 'tests/**'
优化建议：
actions/cache)if 条件）on:
pull_request:
types: [opened, synchronize, reopened]
- name: 发送Slack通知
uses: 8398a7/action-slack@v3
with:
status: $
webhook_url: $
if: always()
GitHub默认会发送失败通知邮件到你的邮箱。
可以在个人设置中配置：
Settings → Notifications → GitHub Actions
jobs:
my-job:
timeout-minutes: 30
continue-on-error 和 if: always()@v4）本项目的工作流系统展示了：
通过学习这些工作流，你可以：
开始你的自动化之旅吧！ 🚀