github-project-automation

GitHub 项目自动化

状态：已可用于生产 ✅ 最近更新：2025-12-17 版本：2.0.0（已通过渐进式披露优化） 依赖项：无（建议使用 git 和 gh CLI） 最新版本：actions/[email protected]、actions/[email protected]、github/[email protected]

---

快速入门（15 分钟）

1. 选择框架

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

# For React/Vite projects
cp templates/workflows/ci-react.yml .github/workflows/ci.yml

# For Node.js libraries (matrix testing)
cp templates/workflows/ci-node.yml .github/workflows/ci.yml

# For Python projects
cp templates/workflows/ci-python.yml .github/workflows/ci.yml

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

# For basic projects (any framework)
cp templates/workflows/ci-basic.yml .github/workflows/ci.yml

这样做的重要性：

• 预先验证的 YAML 可防止语法错误
• 操作固定到 SHA，提升安全性
• 明确指定 Runner 版本（ubuntu-24.04）
• 预防所有 8 个 GitHub Actions 错误

2. 添加议题模板

# Create directory structure
mkdir -p .github/ISSUE_TEMPLATE

# Copy YAML templates (with validation)
cp templates/issue-templates/bug_report.yml .github/ISSUE_TEMPLATE/
cp templates/issue-templates/feature_request.yml .github/ISSUE_TEMPLATE/

为何选择 YAML 而非 Markdown：

• 验证必填字段（预防错误 #12）
• 数据结构一致
• 用户体验更好
• 不会出现不完整的议题

3. 启用安全扫描

# CodeQL for code analysis
cp templates/workflows/security-codeql.yml .github/workflows/codeql.yml

# Dependabot for dependency updates
cp templates/security/dependabot.yml .github/dependabot.yml

重要：

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

---

完整设置流程：5 个步骤

步骤 1：仓库结构

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

# Create all required directories
mkdir -p .github/{workflows,ISSUE_TEMPLATE}

# Verify structure
tree .github/
# .github/
# ├── workflows/        # GitHub Actions workflows
# ├── ISSUE_TEMPLATE/   # Issue templates
# └── dependabot.yml    # Dependabot config (root of .github/)

要点：

• workflows/ 使用复数形式
• ISSUE_TEMPLATE/ 使用单数形式（沿用旧命名）
• dependabot.yml 应放在 .github/ 中，而非 workflows/

步骤 2：选择工作流模板

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

持续集成（选择一个）：

1. ci-basic.yml - 通用测试／Lint／构建（适用于所有框架）
2. ci-node.yml - Node.js 矩阵测试（18、20、22）
3. ci-python.yml - Python 矩阵测试（3.10、3.11、3.12）
4. ci-react.yml - React／TypeScript 类型检查

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

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

复制所选模板：

# Example: React app with security
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 等），请添加密钥：

# Using gh CLI
gh secret set CLOUDFLARE_API_TOKEN
# Paste your token when prompted

# Verify
gh secret list

关键语法：

# ✅ CORRECT
env:
  API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

# ❌ WRONG - Missing double braces
env:
  API_TOKEN: $secrets.CLOUDFLARE_API_TOKEN

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

步骤 4：添加议题／PR 模板

议题模板（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/

使用不同格式的原因：

• 议题模板：使用 YAML 进行验证
• PR 模板：使用 Markdown（GitHub 的限制）

步骤 5：根据项目进行自定义

必须进行的自定义：

1. 更新用户名／电子邮件：

   # In issue templates
   assignees:
     - secondsky  # ← Change to your GitHub username
   
   # In dependabot.yml
   reviewers:
     - "secondsky"  # ← Change to your username
   

2. 调整语言（CodeQL）：

   # In security-codeql.yml
   matrix:
     language: ['javascript-typescript']  # ← Add your languages
     # Options: c-cpp, csharp, go, java-kotlin, python, ruby, swift
   

3. 更新包管理器（Dependabot）：

   # In dependabot.yml
   - package-ecosystem: "npm"  # ← Change if using yarn/pnpm/pip/etc
   

4. 设置部署 URL（Cloudflare）：

   # In ci-cloudflare-workers.yml
   echo "Worker URL: https://your-worker.your-subdomain.workers.dev"
   # ← Update with your actual Worker URL
   

---

关键规则

务必做到

✅ 将操作固定到 SHA，而非 @latest

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

# ❌ WRONG
- uses: actions/checkout@latest

✅ 明确指定 Runner 版本

# ✅ CORRECT
runs-on: ubuntu-24.04  # Locked to specific LTS

# ❌ RISKY
runs-on: ubuntu-latest  # Changes over time

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

# ✅ CORRECT
${{ secrets.API_TOKEN }}

# ❌ WRONG
$secrets.API_TOKEN

✅ 提交前验证 YAML

# Use yamllint or GitHub's workflow validator
yamllint .github/workflows/*.yml

✅ 先在功能分支上测试工作流

git checkout -b test/github-actions
# Push and verify CI runs before merging to main

绝对不要做

❌ 不要对操作版本使用 @latest

• 操作更新时可能会在没有警告的情况下失效
• 存在安全风险（自动采用未经审核的版本）

❌ 不要在工作流中硬编码密钥

# ❌ NEVER DO THIS
env:
  API_TOKEN: "sk_live_abc123..."  # Secret exposed in repo!

❌ 不要跳过已编译语言的构建步骤（CodeQL）

# ❌ WRONG - CodeQL fails for Java without build
- name: Perform CodeQL Analysis  # No .class files to analyze

# ✅ CORRECT - Include build
- name: Build project
  run: ./mvnw clean install
- name: Perform CodeQL Analysis  # Now has .class files

❌ 不要忽略 Dependabot 中的 devDependencies

• devDependencies 会在构建期间运行，可能执行恶意代码
• 应同时包含生产依赖项和开发依赖项

❌ 不要使用单个 ISSUE_TEMPLATE.md 文件

# ❌ OLD WAY
.github/ISSUE_TEMPLATE.md

# ✅ NEW WAY
.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 错误） 原因：空格与制表符混用、冒号后缺少空格、缩进不一致 预防方法：使用经过验证、采用 2 个空格缩进的技能模板 影响：工作流无法解析，CI 不会运行

问题 #2：操作版本固定问题 🔒 SECURITY

错误：操作更新后，工作流意外中断 来源：GitHub Security Best Practices 2025 原因：使用 @latest 或 @v4，而不是特定 SHA 预防措施：所有模板都固定到 SHA，并附带版本注释 影响：意外的破坏性变更、安全漏洞

问题 #3：无法获取密钥 🔑

错误：Secret not found 或变量为空 来源：GitHub Actions 调试指南 原因：语法错误（使用 $secrets.NAME 而不是 ${{ secrets.NAME }}） 预防措施：模板演示正确的上下文语法 影响：部署失败、CI/CD 工作流中断

问题 #4：CodeQL 未在 Dependabot PR 上运行 🛡️

错误：依赖项更新时跳过安全扫描 来源：GitHub Community Discussion #121836 原因：默认触发器的限制 预防措施：模板包含 push: branches: [dependabot/**] 影响：存在漏洞的依赖项未经扫描就被合并

问题 #5：问题模板缺少必填字段 📋

错误：问题信息不完整，缺少关键信息 来源：社区反馈 原因：Markdown 模板不会进行验证 预防措施：使用带有 required: true 验证的 YAML 模板 影响：无法复现 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 与 PR）
• 在作业之间共享构建产物
• 将 GitHub 自动化与其他技能集成（cloudflare-worker-base、project-planning）
• 优化工作流性能
• 需要矩阵策略、产物上传/下载示例

配置示例（references/configuration-examples.md）

在以下情况下加载：

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

故障排除指南（references/troubleshooting-guide.md）

在以下情况下加载：

• 推送代码后工作流仍未触发
• CodeQL 报告“No code found to analyze”
• 所有矩阵构建都因相同错误失败
• Dependabot PR 持续无法通过 CI
• 权限错误（“Resource not accessible by integration”）
• 需要逐步调试流程

高级配置（references/advanced-configurations.md）

在以下情况下加载：

• 设置多环境部署（staging/production）
• 创建可复用工作流或复合操作
• 优化 CI/CD 流水线性能
• 实现高级矩阵策略
• 使用 OIDC 进行云身份验证（无需长期有效的密钥）
• 需要工作流优化技巧

---

与现有技能集成

cloudflare-worker-base → 添加 CI/CD

用户创建新的 Worker 项目时：

# User: "Create Cloudflare Worker with CI/CD"

# This skill runs AFTER cloudflare-worker-base
cp templates/workflows/ci-cloudflare-workers.yml .github/workflows/deploy.yml

# Configure secrets
gh secret set CLOUDFLARE_API_TOKEN

结果：新的 Worker，可在推送到 main 时自动部署

project-planning → 生成自动化配置

用户使用 project-planning 技能时：

# User: "Plan new React app with GitHub automation"

# project-planning generates IMPLEMENTATION_PHASES.md
# Then this skill sets up GitHub automation
cp templates/workflows/ci-react.yml .github/workflows/ci.yml
cp templates/issue-templates/*.yml .github/ISSUE_TEMPLATE/

结果：已规划的项目，配备完整的 GitHub 自动化配置

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

为开源项目做准备时：

# User: "Prepare repo for open source contributions"

# open-source-contributions skill handles CONTRIBUTING.md
# This skill adds issue templates and 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 运行器）- 在本地测试工作流

安装 gh CLI：

# macOS
brew install gh

# Ubuntu
sudo apt install gh

# Verify
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 工作流模板
• 更新工作流文件中的用户名
• 配置密钥（如果需要部署）
• 为所有 Actions 固定 SHA（不要使用 @latest）
• 明确指定运行器版本（ubuntu-24.04）
• 工作流触发条件与分支匹配（main/master）

Issue 模板：

• 创建 .github/ISSUE_TEMPLATE/ 目录
• 复制 bug_report.yml
• 复制 feature_request.yml
• 将受理人更新为你的 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 中设置审阅者

测试：

• 先推送到功能分支（不要推送到 main）
• 验证 CI 成功运行
• 检查 Actions 标签页中是否有错误
• 在本地验证 YAML 语法
• 测试密钥访问（如适用）

文档：

• 在 README.md 中添加徽章（可选）
• 在 README 中记录所需密钥
• 更新 CONTRIBUTING.md（如果是开源项目）

---

有疑问？遇到问题？

1. 查看 references/common-errors.md 中的全部 18 个错误
2. 验证工作流 YAML 是否有效：yamllint .github/workflows/*.yml
3. 查看 GitHub Actions 标签页中的详细错误消息
4. 查阅官方文档：https://docs.github.com/en/actions
5. 确保已配置密钥：gh secret list

---

最后更新：2025-12-17 版本：2.0.0（通过渐进式披露进行优化） 状态：已可用于生产环境