名称: github-project-automation 描述: GitHub仓库自动化（CI/CD、issue模板、Dependabot、CodeQL）。用于项目设置、Actions工作流、安全扫描，或遇到YAML语法、工作流配置、模板结构错误。

关键词: github actions, github workflow, ci/cd, issue templates, pull request templates, dependabot, codeql, security scanning, yaml syntax, github automation, repository setup, workflow templates, github actions matrix, secrets management, branch protection, codeowners, github projects, continuous integration, continuous deployment, workflow syntax error, action version pinning, runner version, github context, yaml indentation error 许可证: MIT 元数据: 版本: 2.0.0 最后验证: 2025-12-17 优化日期: 2025-12-17 预防错误: 18 节省令牌: ~75% 复杂度: 8/10

GitHub项目自动化

状态: 生产就绪 ✅ 最后更新: 2025-12-17 版本: 2.0.0（优化渐进披露）依赖: 无（推荐git和gh CLI） 最新版本: actions/checkout@v4.2.2, actions/setup-node@v4.1.0, github/codeql-action@v3.27.4

快速开始（15分钟）

1. 选择您的框架

选择匹配您项目的工作流模板：

# 对于React/Vite项目
cp templates/workflows/ci-react.yml .github/workflows/ci.yml

# 对于Node.js库（矩阵测试）
cp templates/workflows/ci-node.yml .github/workflows/ci.yml

# 对于Python项目
cp templates/workflows/ci-python.yml .github/workflows/ci.yml

# 对于Cloudflare Workers
cp templates/workflows/ci-cloudflare-workers.yml .github/workflows/deploy.yml

# 对于基本项目（任何框架）
cp templates/workflows/ci-basic.yml .github/workflows/ci.yml

为什么重要:

预验证YAML防止语法错误
SHA固定的actions确保安全
明确的runner版本（ubuntu-24.04）
预防所有8个GitHub Actions错误

2. 添加issue模板

# 创建目录结构
mkdir -p .github/ISSUE_TEMPLATE

# 复制YAML模板（带验证）
cp templates/issue-templates/bug_report.yml .github/ISSUE_TEMPLATE/
cp templates/issue-templates/feature_request.yml .github/ISSUE_TEMPLATE/

为什么用YAML而非Markdown:

必需字段验证（预防错误 #12）
一致的数据结构
更好的用户体验
无未完成issue

3. 启用安全扫描

# CodeQL用于代码分析
cp templates/workflows/security-codeql.yml .github/workflows/codeql.yml

# Dependabot用于依赖更新
cp templates/security/dependabot.yml .github/dependabot.yml

关键:

CodeQL需要特定权限（security-events: write）
Dependabot每个生态系统有10个PR限制
两者必须在Dependabot PR上运行（预防错误 #13）

5步完整设置流程

步骤1: 仓库结构

创建标准GitHub自动化目录结构：

# 创建所有必需目录
mkdir -p .github/{workflows,ISSUE_TEMPLATE}

# 验证结构
tree .github/
# .github/
# ├── workflows/        # GitHub Actions工作流
# ├── ISSUE_TEMPLATE/   # issue模板
# └── dependabot.yml    # Dependabot配置（在.github/根目录）

关键点:

workflows/ 是复数
ISSUE_TEMPLATE/ 是单数（遗留命名）
dependabot.yml 放在 .github/，非 workflows/

步骤2: 选择工作流模板

根据项目需求选择工作流：

持续集成（选一个）:

ci-basic.yml - 通用测试/代码检查/构建（所有框架）
ci-node.yml - Node.js带矩阵测试（18, 20, 22）
ci-python.yml - Python带矩阵测试（3.10, 3.11, 3.12）
ci-react.yml - React/TypeScript带类型检查

部署（可选）: 5. ci-cloudflare-workers.yml - 部署到Cloudflare Workers

安全（推荐）: 6. security-codeql.yml - 代码扫描 7. dependabot.yml - 依赖更新

复制选定模板:

# 示例：React应用带安全
cp templates/workflows/ci-react.yml .github/workflows/ci.yml
cp templates/workflows/security-codeql.yml .github/workflows/codeql.yml
cp templates/security/dependabot.yml .github/dependabot.yml

步骤3: 配置秘密（如部署）

对于部署工作流（Cloudflare、AWS等），添加秘密：

# 使用gh CLI
gh secret set CLOUDFLARE_API_TOKEN
# 提示时粘贴您的令牌

# 验证
gh secret list

关键语法:

# ✅ 正确
env:
  API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

# ❌ 错误 - 缺少双括号
env:
  API_TOKEN: $secrets.CLOUDFLARE_API_TOKEN

预防错误 #6（秘密语法）。

步骤4: 添加issue/PR模板

issue模板（YAML格式）:

cp templates/issue-templates/bug_report.yml .github/ISSUE_TEMPLATE/
cp templates/issue-templates/feature_request.yml .github/ISSUE_TEMPLATE/

PR模板（Markdown格式）:

cp templates/pr-templates/PULL_REQUEST_TEMPLATE.md .github/

为什么不同格式:

issue模板：YAML用于验证
PR模板：Markdown（GitHub限制）

步骤5: 为项目定制

必需定制:

更新用户名/邮箱:

# 在issue模板中
assignees:
  - secondsky  # ← 改为您的GitHub用户名

# 在dependabot.yml中
reviewers:
  - "secondsky"  # ← 改为您的用户名

调整语言（CodeQL）:

# 在security-codeql.yml中
matrix:
  language: ['javascript-typescript']  # ← 添加您的语言
  # 选项: c-cpp, csharp, go, java-kotlin, python, ruby, swift

更新包管理器（Dependabot）:

# 在dependabot.yml中
- package-ecosystem: "npm"  # ← 如使用yarn/pnpm/pip等则更改

设置部署URL（Cloudflare）:

# 在ci-cloudflare-workers.yml中
echo "Worker URL: https://your-worker.your-subdomain.workers.dev"
# ← 更新为实际Worker URL

关键规则

必须做

✅ 固定actions到SHA，非@latest

# ✅ 正确
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

# ❌ 错误
- uses: actions/checkout@latest

✅ 使用明确的runner版本

# ✅ 正确
runs-on: ubuntu-24.04  # 锁定到特定LTS

# ❌ 风险
runs-on: ubuntu-latest  # 随时间变化

✅ 包含秘密在上下文语法中

# ✅ 正确
${{ secrets.API_TOKEN }}

# ❌ 错误
$secrets.API_TOKEN

✅ 提交前验证YAML

# 使用yamllint或GitHub的工作流验证器
yamllint .github/workflows/*.yml

✅ 先在特性分支测试工作流

git checkout -b test/github-actions
# 推送并验证CI运行后再合并到main

切勿做

❌ 勿使用@latest作为action版本

actions更新时无警告中断
安全风险（自动采用未审核版本）

❌ 勿在工作流中硬编码秘密

# ❌ 绝不要做
env:
  API_TOKEN: "sk_live_abc123..."  # 秘密在仓库中暴露！

❌ 勿跳过编译语言的构建步骤（CodeQL）

# ❌ 错误 - CodeQL对Java无构建失败
- name: 执行CodeQL分析  # 无.class文件分析

# ✅ 正确 - 包括构建
- name: 构建项目
  run: ./mvnw clean install
- name: 执行CodeQL分析  # 现在有.class文件

❌ 勿在Dependabot中忽略devDependencies

DevDependencies在构建时运行，可能执行恶意代码
包括生产和非生产依赖

❌ 勿使用单个ISSUE_TEMPLATE.md文件

# ❌ 旧方式
.github/ISSUE_TEMPLATE.md

# ✅ 新方式
.github/ISSUE_TEMPLATE/
  bug_report.yml
  feature_request.yml

已知问题预防（前5个）

此技能预防18个记录的问题。以下是前5个最关键的：

问题 #1: YAML缩进错误 ⚠️ 最常见

错误: workflow file is invalid. mapping values are not allowed in this context 来源: Stack Overflow（最常见的GitHub Actions错误） 为什么发生: 空格vs制表符，冒号后缺少空格，缩进不一致预防: 使用带验证2空格缩进的技能模板影响: 工作流解析失败，CI不运行

问题 #2: Action版本固定问题 🔒 安全

错误: 工作流在action更新后意外中断来源: GitHub安全最佳实践2025 为什么发生: 使用@latest或@v4而非特定SHA 预防: 所有模板固定到SHA带版本注释影响: 意外破坏性变化，安全漏洞

问题 #3: 秘密不可用 🔑

错误: Secret not found 或空变量来源: GitHub Actions调试指南 为什么发生: 错误语法（$secrets.NAME 而非 ${{ secrets.NAME }}）预防: 模板演示正确上下文语法影响: 部署失败，CI/CD管道中断

问题 #4: CodeQL未在Dependabot PRs上运行 🛡️

错误: 安全扫描在依赖更新时跳过来源: GitHub社区讨论 #121836 为什么发生: 默认触发器限制预防: 模板包括 push: branches: [dependabot/**] 影响: 未扫描的易受攻击依赖合并

问题 #5: issue模板中缺少必需字段 📋

错误: 不完整issue，缺少关键信息来源: 社区反馈 为什么发生: Markdown模板不验证预防: YAML模板带 required: true 验证影响: 无法复现bug，浪费分流时间

完整错误文档含所有18个问题: 调试GitHub Actions问题或配置工作流时加载 references/common-errors.md。

何时加载参考

在GitHub自动化特定方面工作时加载参考文件：

常见错误 (`references/common-errors.md`)

加载当：

遇到工作流语法错误
调试失败的GitHub Actions运行
首次设置CodeQL或Dependabot
解决“Secret not found”错误
理解为何矩阵构建失败
需要任何18个记录错误的详细解决方案

工作流模式 (`references/workflow-patterns.md`)

加载当：

实现多版本测试（Node.js 18/20/22）
设置条件部署（main vs PR）
在任务间共享构建工件
集成GitHub自动化与其他技能（cloudflare-worker-base, project-planning）
优化工作流性能
需要矩阵策略、工件上传/下载示例

配置示例 (`references/configuration-examples.md`)

加载当：

从头创建dependabot.yml
为特定语言配置CodeQL
正确设置GitHub Actions秘密
需要完整工作配置文件
理解分支保护规则
创建带验证的issue/PR模板

故障排除指南 (`references/troubleshooting-guide.md`)

加载当：

工作流未触发尽管推送代码
CodeQL报告“未找到代码分析”
矩阵构建全部失败带相同错误
Dependabot PRs持续失败CI
权限错误（“资源不可由集成访问”）
需要逐步调试程序

高级配置 (`references/advanced-configurations.md`)

加载当：

设置多环境部署（暂存/生产）
创建可重用工作流或复合actions
优化CI/CD管道性能
实现高级矩阵策略
使用OIDC进行云认证（无长寿命秘密）
需要工作流优化技术

与现有技能集成

cloudflare-worker-base → 添加CI/CD

当用户创建新Worker项目：

# 用户: “创建带CI/CD的Cloudflare Worker”

# 此技能在cloudflare-worker-base后运行
cp templates/workflows/ci-cloudflare-workers.yml .github/workflows/deploy.yml

# 配置秘密
gh secret set CLOUDFLARE_API_TOKEN

结果: 新Worker带主分支推送的自动部署

project-planning → 生成自动化

当用户使用project-planning技能：

# 用户: “计划新React应用带GitHub自动化”

# project-planning生成IMPLEMENTATION_PHASES.md
# 然后此技能设置GitHub自动化
cp templates/workflows/ci-react.yml .github/workflows/ci.yml
cp templates/issue-templates/*.yml .github/ISSUE_TEMPLATE/

结果: 计划项目带完整GitHub自动化

open-source-contributions → 设置贡献者体验

当准备项目为开源：

# 用户: “准备仓库用于开源贡献”

# open-source-contributions技能处理CONTRIBUTING.md
# 此技能添加issue模板和CODEOWNERS
cp templates/issue-templates/*.yml .github/ISSUE_TEMPLATE/
cp templates/misc/CODEOWNERS .github/

结果: 贡献者友好仓库

依赖

必需:

Git 2.0+ - 版本控制
GitHub CLI (gh) 2.0+ - 秘密管理、PR创建（可选但推荐）

可选:

yamllint 1.20+ - YAML验证提交前
act（本地GitHub Actions runner） - 本地测试工作流

安装gh CLI:

# macOS
brew install gh

# Ubuntu
sudo apt install gh

# 验证
gh --version

官方文档

GitHub Actions: https://docs.github.com/en/actions
工作流语法: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
CodeQL: https://codeql.github.com/docs/
Dependabot: https://docs.github.com/en/code-security/dependabot
issue模板: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests

Context7库ID: 在Context7 MCP中搜索 /websites/github 或 /github/

完整设置清单

使用此清单验证您的GitHub自动化设置：

工作流:

[ ] 创建 .github/workflows/ 目录
[ ] 复制适当的CI工作流模板
[ ] 更新工作流文件中的用户名
[ ] 配置秘密（如部署）
[ ] SHA固定所有actions（非@latest）
[ ] 明确的runner版本（ubuntu-24.04）
[ ] 工作流触发器匹配分支（main/master）

issue模板:

[ ] 创建 .github/ISSUE_TEMPLATE/ 目录
[ ] 复制 bug_report.yml
[ ] 复制 feature_request.yml
[ ] 更新assignees为您的GitHub用户名
[ ] YAML模板使用 required: true 为关键字段

PR模板:

[ ] 复制 PULL_REQUEST_TEMPLATE.md 到 .github/
[ ] 定制清单为项目需求

安全:

[ ] 复制 security-codeql.yml
[ ] 添加正确语言到CodeQL矩阵
[ ] 设置 security-events: write 权限
[ ] 复制 dependabot.yml
[ ] 更新 package-ecosystem（npm/pip等）
[ ] 在dependabot.yml中设置reviewers

测试:

[ ] 先推送到特性分支（非main）
[ ] 验证CI成功运行
[ ] 检查Actions标签以找任何错误
[ ] 本地验证YAML语法
[ ] 测试秘密访问（如适用）

文档:

[ ] 添加徽章到README.md（可选）
[ ] 在README中记录必需秘密
[ ] 更新CONTRIBUTING.md（如开源）

问题？故障？

检查 references/common-errors.md 为所有18个错误
验证工作流YAML有效： yamllint .github/workflows/*.yml
检查GitHub Actions标签为详细错误消息
查看官方文档： https://docs.github.com/en/actions
确保秘密配置： gh secret list

最后更新: 2025-12-17 版本: 2.0.0（优化渐进披露）状态: 生产就绪

GitHub项目自动化

快速开始（15分钟）

1. 选择您的框架

2. 添加issue模板

3. 启用安全扫描

5步完整设置流程

步骤1: 仓库结构

步骤2: 选择工作流模板

步骤3: 配置秘密（如部署）

步骤4: 添加issue/PR模板

步骤5: 为项目定制

关键规则

必须做

切勿做

已知问题预防（前5个）

问题 #1: YAML缩进错误 ⚠️ 最常见

问题 #2: Action版本固定问题 🔒 安全

问题 #3: 秘密不可用 🔑

问题 #4: CodeQL未在Dependabot PRs上运行 🛡️

问题 #5: issue模板中缺少必需字段 📋

何时加载参考

常见错误 (references/common-errors.md)

工作流模式 (references/workflow-patterns.md)

配置示例 (references/configuration-examples.md)

故障排除指南 (references/troubleshooting-guide.md)

高级配置 (references/advanced-configurations.md)

与现有技能集成

cloudflare-worker-base → 添加CI/CD

project-planning → 生成自动化

open-source-contributions → 设置贡献者体验

依赖

官方文档

完整设置清单

常见错误 (`references/common-errors.md`)

工作流模式 (`references/workflow-patterns.md`)

配置示例 (`references/configuration-examples.md`)

故障排除指南 (`references/troubleshooting-guide.md`)

高级配置 (`references/advanced-configurations.md`)