创建 GitHub Actions 工作流规范
为 GitHub Actions 工作流 ${input:WorkflowFile} 创建一个全面的规范。
此规范作为工作流行为、需求和约束的规范。它必须是与实现无关的，重点关注工作流做什么，而不是如何实现。
面向 AI 的需求
- 令牌效率：使用简洁的语言，同时不牺牲清晰度
- 结构化数据：利用表格、列表和图表来呈现密集信息
- 语义清晰度：始终如一地使用精确术语
- 实现抽象：避免特定的语法、命令或工具版本
- 可维护性：设计易于随工作流演变而更新
规范模板
保存为：/spec/spec-process-cicd-[工作流名称].md
---
title: CI/CD 工作流规范 - [工作流名称]
version: 1.0
date_created: [YYYY-MM-DD]
last_updated: [YYYY-MM-DD]
owner: DevOps 团队
tags: [process, cicd, github-actions, automation, [领域特定标签]]
---
## 工作流概述
**目的**：[用一句话描述工作流的主要目标]
**触发事件**：[列出触发条件]
**目标环境**：[环境范围]
## 执行流程图
```mermaid
graph TD
A[触发事件] --> B[任务 1]
B --> C[任务 2]
C --> D[任务 3]
D --> E[结束]
B --> F[并行任务]
F --> D
style A fill:#e1f5fe
style E fill:#e8f5e8
任务与依赖关系
| 任务名称 |
目的 |
依赖项 |
执行上下文 |
| 任务-1 |
[目的] |
[先决条件] |
[运行器/环境] |
| 任务-2 |
[目的] |
任务-1 |
[运行器/环境] |
需求矩阵
功能需求
| ID |
需求 |
优先级 |
验收标准 |
| REQ-001 |
[需求] |
高 |
[可测试的标准] |
| REQ-002 |
[需求] |
中 |
[可测试的标准] |
安全需求
| ID |
需求 |
实现约束 |
| SEC-001 |
[安全需求] |
[约束描述] |
性能需求
| ID |
指标 |
目标 |
测量方法 |
| PERF-001 |
[指标] |
[目标值] |
[如何测量] |
输入/输出契约
输入
ENV_VAR_1: 字符串
ENV_VAR_2: 密钥
paths: [路径过滤器列表]
branches: [分支模式列表]
输出
job_1_output: 字符串
build_artifact: 文件
密钥与变量
| 类型 |
名称 |
目的 |
范围 |
| 密钥 |
SECRET_1 |
[目的] |
工作流 |
| 变量 |
VAR_1 |
[目的] |
仓库 |
执行约束
运行时约束
- 超时时间：[最长执行时间]
- 并发：[并行执行限制]
- 资源限制：[内存/CPU 约束]
环境约束
- 运行器要求：[操作系统/硬件需求]
- 网络访问：[外部连接需求]
- 权限：[所需访问级别]
错误处理策略
| 错误类型 |
响应 |
恢复操作 |
| 构建失败 |
[响应] |
[恢复步骤] |
| 测试失败 |
[响应] |
[恢复步骤] |
| 部署失败 |
[响应] |
[恢复步骤] |
质量门禁
门禁定义
| 门禁 |
标准 |
绕过条件 |
| 代码质量 |
[标准] |
[何时允许] |
| 安全扫描 |
[阈值] |
[何时允许] |
| 测试覆盖率 |
[百分比] |
[何时允许] |
监控与可观测性
关键指标
- 成功率：[目标百分比]
- 执行时间：[目标持续时间]
- 资源使用：[监控方法]
告警
| 条件 |
严重性 |
通知目标 |
| [条件] |
[级别] |
[谁/哪里] |
集成点
外部系统
| 系统 |
集成类型 |
数据交换 |
SLA 要求 |
| [系统] |
[类型] |
[数据格式] |
[要求] |
依赖的工作流
| 工作流 |
关系 |
触发机制 |
| [工作流] |
[类型] |
[如何触发] |
合规与治理
审计要求
- 执行日志：[保留策略]
- 批准门禁：[所需批准]
- 变更控制：[更新流程]
安全控制
- 访问控制：[权限模型]
- 密钥管理：[轮换策略]
- 漏洞扫描：[扫描频率]
边缘情况与异常
场景矩阵
| 场景 |
预期行为 |
验证方法 |
| [边缘情况] |
[行为] |
[如何验证] |
验证标准
工作流验证
- VLD-001：[验证规则]
- VLD-002：[验证规则]
性能基准
- PERF-001：[基准标准]
- PERF-002：[基准标准]
变更管理
更新流程
- 规范更新：首先修改本文档
- 审查与批准：[批准流程]
- 实施：将更改应用到工作流
- 测试：[验证方法]
- 部署：[发布流程]
版本历史
| 版本 |
日期 |
更改 |
作者 |
| 1.0 |
[日期] |
初始规范 |
[作者] |
相关规范
- [链接到相关工作流规范]
- [链接到基础设施规范]
- [链接到部署规范]
## 分析说明
分析工作流文件时：
1. **提取核心目的**：识别主要业务目标
2. **映射任务流程**：创建显示执行顺序的依赖关系图
3. **识别契约**：记录输入、输出和接口
4. **捕获约束**：提取超时时间、权限和限制
5. **定义质量门禁**：识别验证和批准点
6. **记录错误路径**：映射故障场景和恢复
7. **实现抽象**：关注行为，而非语法
## Mermaid 图表指南
### 流程类型
- **顺序**：`A --> B --> C`
- **并行**：`A --> B & A --> C； B --> D & C --> D`
- **条件**：`A --> B{决策}； B -->|是| C； B -->|否| D`
### 样式
```mermaid
style 触发节点 fill：#e1f5fe
style 成功节点 fill：#e8f5e8
style 失败节点 fill：#ffebee
style 处理节点 fill：#f3e5f5
复杂工作流
对于包含 5 个以上任务的工作流，使用子图：
graph TD
subgraph “构建阶段”
A[代码检查] --> B[测试] --> C[构建]
end
subgraph “部署阶段”
D[预发布环境] --> E[生产环境]
end
C --> D
令牌优化策略
- 使用表格：以结构化格式呈现密集信息
- 一致地使用缩写：定义一次，通篇使用
- 要点列表：避免散文式段落
- 代码块：使用结构化数据而非叙述性描述
- 交叉引用：链接而非重复信息
专注于创建一个既作为文档又作为工作流更新模板的规范。
评论(0)