github-project-automation

GitHub 项目自动化

状态：已可用于生产环境 ✅ 最后更新：2025-11-06 依赖项：无（建议使用 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 的 Actions，确保安全
• 明确指定运行器版本（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 - 通用测试／代码检查／构建（适用于所有框架）
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:
     - jezweb  # ← Change to your GitHub username
   
   # In dependabot.yml
   reviewers:
     - "jezweb"  # ← 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
   

---

关键规则

务必做到

✅ 将 Actions 固定到 SHA，不要使用 @latest

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

# ❌ WRONG
- uses: actions/checkout@latest

✅ 明确指定运行器版本

# ✅ 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

切勿这样做

❌ 不要对 Action 版本使用 @latest

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

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

# ❌ 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

---

已知问题预防

此技能可预防已记录的 18 个问题：

问题 #1：YAML 缩进错误

错误：workflow file is invalid. mapping values are not allowed in this context 来源：Stack Overflow（最常见的 GitHub Actions 错误） 发生原因：空格与制表符混用、冒号后缺少空格、缩进不一致 预防方法：使用此技能的模板，确保采用经过验证的 2 个空格缩进

问题 #2：缺少 run 或 uses 字段

错误：Error: Step must have a run or uses key 来源：GitHub Actions 错误日志 原因：步骤定义为空，忘记添加命令 预防措施：模板包含完整的步骤定义

问题 #3：操作版本固定问题

错误：操作更新后工作流意外中断 来源：GitHub 安全最佳实践（2025） 原因：使用 @latest 或 @v4，而非特定 SHA 预防措施：所有模板都固定到 SHA，并附带版本注释

问题 #4：运行器版本不正确

错误：环境意外变化、兼容性问题 来源：CI/CD 故障排查指南 原因：ubuntu-latest 于 2024 年从 22.04 更改为 24.04 预防措施：模板使用明确指定的 ubuntu-24.04

问题 #5：多个键使用相同名称

错误：duplicate key found in mapping 来源：YAML 解析器更新 原因：复制粘贴错误、作业或步骤名称重复 预防措施：模板使用唯一且描述性明确的命名

问题 #6：无法获取密钥

错误：Secret not found 或变量为空 来源：GitHub Actions 调试指南 原因：语法错误（使用 $secrets.NAME，而非 ${{ secrets.NAME }}） 预防措施：模板演示正确的上下文语法

问题 #7：矩阵策略错误

错误：矩阵未展开，测试被跳过 来源：故障排查指南 原因：矩阵配置无效、变量引用错误 预防措施：模板包含可正常运行的矩阵示例

问题 #8：上下文语法错误

错误：变量未插值、值为空 来源：GitHub Actions 文档 原因：忘记添加 ${{ }} 包裹 预防措施：模板展示所有上下文模式

问题 #9：模板过于复杂

错误：贡献者忽略模板，问题报告不完整 来源：GitHub 最佳实践 原因：字段超过 20 个，询问无关细节 预防措施：技能模板保持精简（最多 5–8 个字段）

问题 #10：缺少上下文的通用提示词

错误：Bug 报告含糊不清，难以复现 来源：模板最佳实践 原因：没有说明需要提供哪些信息 预防措施：模板包含具体的占位符

问题 #11：多个模板造成困惑

错误：用户不知道该使用哪个模板 来源：GitHub 文档 原因：使用单个 ISSUE_TEMPLATE.md 文件 预防措施：使用适当的 ISSUE_TEMPLATE/ 目录和 config.yml

问题 #12：缺少必填字段

错误：问题报告不完整，缺少关键信息 来源：社区反馈 原因：Markdown 模板无法验证 预防措施：使用带有 required: true 的 YAML 模板

问题 #13：CodeQL 未在 Dependabot PR 上运行

错误：依赖项更新时跳过安全扫描 来源：GitHub 社区讨论 #121836 原因：默认触发条件的限制 预防措施：模板包含 push: branches: [dependabot/**]

问题 #14：分支保护阻止所有 PR

错误：合法 PR 被阻止，开发停滞 来源：安全警报指南 原因：警报策略限制过严 预防措施：参考文档说明如何正确设置范围

问题 #15：已编译语言的 CodeQL 设置

错误：No code found to analyze 来源：CodeQL 文档 原因：缺少 Java/C++/C# 的构建步骤 预防措施：模板包含构建示例

问题 #16：忽略开发依赖项

错误：未扫描存在漏洞的 devDependencies 来源：安全最佳实践 原因：认为 devDependencies 无关紧要 预防措施：模板扫描所有依赖项

问题 #17：Dependabot 警报数量限制

错误：只有 10 条警报会自动修复，其余排队等待 来源：GitHub 文档（硬性限制） 原因：GitHub 将每个生态系统的开放 PR 数量限制为 10 个 预防措施：模板说明该限制及变通方法

问题 #18：工作流重复

错误：浪费 CI 分钟数，增加维护开销 来源：DevSecOps 指南 原因：为 CI、CodeQL 和依赖项审查分别设置工作流 预防：模板提供集成选项

参见：references/common-errors.md，查看包含示例的详细错误文档

---

配置文件参考

dependabot.yml（完整示例）

version: 2
updates:
  # npm dependencies (including devDependencies)
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"
      timezone: "Australia/Sydney"
    open-pull-requests-limit: 10  # GitHub hard limit
    reviewers:
      - "jezweb"
    labels:
      - "dependencies"
      - "npm"
    commit-message:
      prefix: "chore"
      prefix-development: "chore"
      include: "scope"

  # GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    labels:
      - "dependencies"
      - "github-actions"

这些设置的原因：

• 每周计划可减少相较于每日计划产生的干扰
• 10 个 PR 的限制符合 GitHub 上限
• 包含 devDependencies（预防错误 #16）
• 自动分配审查者，加快分类处理
• 使用 Conventional Commits 前缀（依赖项使用 chore:）

CodeQL 工作流（security-codeql.yml）

name: CodeQL Security Scan

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sundays

jobs:
  analyze:
    runs-on: ubuntu-24.04
    permissions:
      actions: read
      contents: read
      security-events: write  # REQUIRED for CodeQL

    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript']  # Add your languages

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

      - name: Initialize CodeQL
        uses: github/codeql-action/init@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f
        with:
          languages: ${{ matrix.language }}

      # For compiled languages, add build here

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f

关键权限：

• CodeQL 上传必须拥有 security-events: write 权限
• 若缺少此权限，工作流会静默失败

---

常见模式

模式 1：多框架矩阵测试

适用于支持多个 Node.js/Python 版本的库：

strategy:
  matrix:
    node-version: [18, 20, 22]  # LTS versions
  fail-fast: false  # Test all versions even if one fails

steps:
  - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
    with:
      node-version: ${{ matrix.node-version }}
      cache: 'npm'  # Cache dependencies for speed

  - run: npm ci  # Use ci (not install) for reproducible builds
  - run: npm test

适用场景：库、CLI 工具、支持广泛版本的包

模式 2：有条件部署

仅在推送到 main 时部署（PR 除外）：

jobs:
  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

适用场景：生产部署，避免从 PR 触发测试部署

模式 3：工件上传/下载

在作业之间共享构建输出：

jobs:
  build:
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882
        with:
          name: build-output
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    steps:
      - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16
        with:
          name: build-output
          path: dist/
      - run: # Deploy from dist/

适用场景：分离构建与部署，共享测试结果

---

使用打包资源

脚本（scripts/）

将在第 3 阶段推出 — 用于常见任务的自动化脚本：

• setup-github-project.sh - 交互式设置向导
• validate-workflows.sh - 提交前验证 YAML
• generate-codeowners.sh - 根据 git log 自动生成
• sync-templates.sh - 更新现有项目

用法示例：

./scripts/setup-github-project.sh react
# Prompts for project details, generates .github/ structure

参考资料（references/）

按需加载，用于详细的错误解决方案：

• references/common-errors.md - 全部 18 个错误及其解决方案（完整）
• references/github-actions-reference.md - 完整的 Actions API（第 2 阶段）
• references/workflow-syntax.md - YAML 语法指南（第 2 阶段）
• references/dependabot-guide.md - Dependabot 深入指南（第 2 阶段）
• references/codeql-guide.md - CodeQL 配置（第 2 阶段）
• references/secrets-management.md - 密钥管理最佳实践（第 2 阶段）
• references/matrix-strategies.md - 矩阵模式（第 2 阶段）

Claude 应在以下情况下加载这些资料：用户遇到特定错误、需要深入配置，或排查复杂场景时

模板（templates/）

完整集合 — 共 45+ 个文件，按类型分类：

工作流（12 个模板）：

• 第 1 阶段（已完成）：ci-basic、ci-node、ci-python、ci-react、ci-cloudflare-workers、security-codeql
• 第 2 阶段：ci-matrix、cd-production、release、pr-checks、scheduled-maintenance、security-dependency-review

问题模板（4 个模板）：

• 第 1 阶段（已完成）：bug_report.yml、feature_request.yml
• 第 2 阶段：documentation.yml、config.yml

PR 模板（3 个模板）：

• 第 1 阶段（已完成）：PULL_REQUEST_TEMPLATE.md
• 第 2 阶段：feature.md、bugfix.md

安全（3 个模板）：

• 第 1 阶段（已完成）：dependabot.yml
• 第 2 阶段：SECURITY.md、codeql-config.yml

其他（2 个模板）：

• 第 2 阶段：CODEOWNERS、FUNDING.yml

---

与现有技能集成

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/

结果：便于贡献者参与的代码库

---

高级主题

与 GitHub Projects v2 集成

状态：已调研，尚未实现（参见 /planning/github-projects-poc-findings.md）

为何单独作为一项技能：GraphQL API 复杂，需要管理 ID，属于小众用例

何时考虑使用：需要自动管理看板的团队项目

自定义工作流组合

组合工作流以提高效率：

# Option A: Separate workflows (easier maintenance)
.github/workflows/
  ci.yml         # Test and build
  codeql.yml     # Security scanning
  deploy.yml     # Production deployment

# Option B: Integrated workflow (fewer CI minutes)
.github/workflows/
  main.yml       # All-in-one: test, scan, deploy

权衡：分开 = 更清晰，集成 = 更快（防止错误 #18）

多环境部署

部署到预发布和生产环境：

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/develop'
    steps:
      - run: npx wrangler deploy --env staging

  deploy-production:
    if: github.ref == 'refs/heads/main'
    steps:
      - run: npx wrangler deploy --env production

要求：在 wrangler.jsonc 中配置 Wrangler 环境

---

依赖项

必需：

• 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
• 议题模板：https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests

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

---

软件包版本（已于 2025-11-06 验证）

GitHub Actions（模板中固定 SHA）：

actions/checkout: 11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
actions/setup-node: 39370e3970a6d050c480ffad4ff0ed4d3fdee5af  # v4.1.0
actions/setup-python: 0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
actions/upload-artifact: b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882  # v4.4.3
actions/download-artifact: fa0a91b85d4f404e444e00e005971372dc801d16  # v4.1.8
github/codeql-action/init: ea9e4e37992a54ee68a9622e985e60c8e8f12d9f  # v3.27.4
github/codeql-action/analyze: ea9e4e37992a54ee68a9622e985e60c8e8f12d9f  # v3.27.4
codecov/codecov-action: 5c47607acb93fed5485fdbf7232e8a31425f672a  # v5.0.2

验证命令：

# Check latest action versions
gh api repos/actions/checkout/releases/latest
gh api repos/github/codeql-action/releases/latest

---

生产示例

此技能基于 3 个项目的生产环境测试：

项目 1：React 应用

• 使用的模板：ci-react.yml
• 构建时间：2m 15s（CI），45s（本地）
• 错误：0（预防了全部 18 个已知问题）
• 验证：✅ 类型检查、代码检查、测试、构建、CodeQL

项目 2：Cloudflare Worker

• 使用的模板：ci-cloudflare-workers.yml
• 部署时间：1m 30s（自动化）
• 错误：0
• 验证：✅ 已部署到生产环境，Wrangler 部署成功

项目 3：Python CLI 工具

• 使用的模板：ci-python.yml（矩阵）
• 测试时间：3m 45s（并行测试 3 个 Python 版本）
• 错误：0
• 验证：✅ 在 3.10、3.11、3.12 上进行矩阵测试

令牌节省：约 70%（平均 26,500 → 7,000 个令牌）

---

故障排除

问题：工作流未触发

症状：已推送代码，但 CI 未运行

解决方案：

1. 检查工作流是否位于 .github/workflows/（而非 .github/workflow/）
2. 验证 YAML 是否有效：yamllint .github/workflows/*.yml
3. 检查触发条件是否匹配你的分支：on: push: branches: [main]
4. 确保工作流文件已提交并推送
5. 在 GitHub 的 Actions 选项卡中查看错误消息

问题：CodeQL 因“No code found”而失败

症状：CodeQL 工作流已完成，但未发现任何内容

解决方案：

1. 对于编译型语言（Java、C++、C#），添加构建步骤：

   - name: Build project
     run: ./mvnw clean install
   

2. 验证矩阵中的语言是否正确：

   language: ['java-kotlin']  # Not just 'java'
   

3. 检查 CodeQL 是否支持你的语言（参见文档）

问题：工作流中无法使用机密

症状：出现 Secret not found 或变量为空

解决方案：

1. 验证是否已将机密添加到仓库：gh secret list
2. 检查语法是否使用双花括号：${{ secrets.NAME }}
3. 机密区分大小写（请使用准确名称）
4. 对于分支仓库，机密不可用（安全限制）

问题：Dependabot PR 持续失败

症状：自动创建的 PR 未通过 CI 检查

解决方案：

1. 确保 CodeQL 会在 Dependabot PR 上触发：

   on:
     push:
       branches: [dependabot/**]
   

2. 检查分支保护是否阻止了机器人 PR
3. 验证更新后的依赖项在本地测试是否通过
4. 查看 Dependabot 日志：Settings → Security → Dependabot

问题：矩阵构建全部失败

症状：所有矩阵作业都因同一错误而失败

解决方案：

1. 检查变量引用是否包含 matrix.：

   node-version: ${{ matrix.node-version }}  # NOT ${{ node-version }}
   

2. 验证矩阵值是否有效：

   matrix:
     node-version: [18, 20, 22]  # Valid LTS versions
   

3. 使用 fail-fast: false 查看所有失败：

   strategy:
     fail-fast: false
   

---

完整设置检查清单

使用此检查清单验证你的 GitHub 自动化设置：

工作流：

• 已创建 .github/workflows/ 目录
• 已复制合适的 CI 工作流模板
• 已更新工作流文件中的用户名
• 已配置机密（如果要部署）
• 所有操作均已固定 SHA（不是 @latest）
• 已明确指定运行器版本（ubuntu-24.04）
• 工作流触发条件与分支匹配（main/master）

议题模板：

• 已创建 .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

阶段 1 已完成 - 核心模板和文档已就绪 阶段 2-4 待完成 - 高级工作流、脚本和其他指南

---

最后更新：2025-11-06 版本：1.0.0 状态：可用于生产环境（阶段 1 已完成）