lguidolin/init-repo-CI

仓库自动化设置

在任何仓库中搭建完整的 conventional-commits + release-please + CI 自动化栈。适用于空仓库和已有内容的仓库。

概述

左移： 尽早捕获问题。一个在 PR 时发现的错误提交信息只耗费几秒钟；同样的信息污染了发布说明则会损害可信度。将验证前置——在 PR 标题中强制提交格式，在 CI 中验证配置，在问题到达主分支前捕获它们。

更快即更安全： 更小的批次和更频繁的发布降低了风险。包含 3 个变更的发布比包含 30 个的更容易调试。自动化发布构建了对发布流程本身的信心。

此技能设置强制执行机制：PR 标题验证确保每次合并到主分支都会生成一个有意义的、可解析的提交。Release-please 将这些提交转化为带有变更日志的自动化发布。CI 在合并前捕获配置和代码问题。

何时使用

• 开始一个新仓库，需要从一开始就具备发布自动化
• 已有仓库没有自动版本管理或变更日志生成
• 从手动发布流程或其他发布工具迁移
• 仓库需要 PR 标题验证和自动标签

何时不使用

• 仓库已配置了 release-please 或等效工具（请先检查）
• 多包仓库使用了不兼容的发布工具（例如 Lerna 的独立版本管理已在工作中）
• 仓库是一个 fork，其上游控制发布流程

流程

步骤 1：收集配置

在生成任何文件之前，向用户询问以下值：

参数	默认值	描述
PROJECT_NAME	（必填）	用于文档的人类可读项目名称
INITIAL_VERSION	0.1.0	起始语义版本
RELEASE_TYPE	simple	simple（单包）或 node / python 等
REPO_LAYOUT	single	single（根目录一个包）或 monorepo（多个包）
PACKAGE_PATHS	.	对于 monorepo：逗号分隔的路径，如 packages/api,packages/ui
DEPENDABOT_ECOSYSTEMS	github-actions	逗号分隔：github-actions、npm、pip、cargo 等
DEFAULT_BRANCH	main	触发发布的分支

自动检测正确的 RELEASE_TYPE：

• 存在 package.json → 建议 node
• 存在 setup.py 或 pyproject.toml → 建议 python
• 存在 Cargo.toml → 建议 rust
• 以上皆无 → 建议 simple

步骤 2：检测现有文件

在创建任何内容之前，检查是否存在冲突：

for f in .github/workflows/pull-request.yml .github/workflows/main-branch.yml \
         .github/release-please-config.json .release-please-manifest.json \
         .github/dependabot.yml .github/pull_request_template.md docs/DEVELOPMENT.md; do
  [[ -f "$f" ]] && echo "EXISTS: $f"
done

如果文件存在，显示将要更改的差异，并在覆盖之前征求用户许可。不要静默覆盖——现有文件可能包含项目特定的自定义内容。

步骤 3：创建配置文件

按以下顺序创建文件（依赖关系自上而下）：

3a. .github/release-please-config.json

单包：

{
  "release-type": "{{RELEASE_TYPE}}",
  "bump-minor-pre-major": true,
  "bump-patch-for-minor-pre-major": false,
  "initial-version": "{{INITIAL_VERSION}}",
  "packages": {
    ".": {}
  }
}

多包： 将 packages 替换为每个路径的一个条目：

{
  "packages": {
    "packages/api": { "release-type": "node" },
    "packages/ui": { "release-type": "node" }
  }
}

每个 monorepo 包都有自己的 release-type——如果它们不同，请逐个询问用户。

3b. .release-please-manifest.json

单包：

{
  ".": "{{INITIAL_VERSION}}"
}

多包： 每个包路径一个条目，每个都有自己的版本。

3c. .github/workflows/pull-request.yml

name: Pull Request Validation

on:
  pull_request:
    types: [opened, edited, synchronize, reopened]

permissions:
  pull-requests: write
  contents: read
  statuses: write

jobs:
  validate-pr-title:
    name: Validate PR Title
    runs-on: ubuntu-latest
    steps:
      - uses: amannn/action-semantic-pull-request@v6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          types: |
            feat
            fix
            docs
            chore
            refactor
            test
            ci
          requireScope: false
          subjectPattern: ^[a-z].+$
          subjectPatternError: |
            The subject "{subject}" found in the pull request title "{title}"
            didn't match the configured pattern. Please ensure that the subject
            starts with a lowercase character (per conventional commits).

  auto-label:
    name: Auto Label PR
    runs-on: ubuntu-latest
    steps:
      - name: Label based on PR title
        uses: actions/github-script@v8
        with:
          script: |
            const title = context.payload.pull_request.title;
            const labelMap = {
              'feat': 'enhancement',
              'fix': 'bug',
              'docs': 'documentation',
              'chore': 'chore',
              'refactor': 'refactor',
              'test': 'test',
              'ci': 'ci'
            };
            for (const [type, label] of Object.entries(labelMap)) {
              if (title.startsWith(`${type}:`) || title.startsWith(`${type}(`)) {
                await github.rest.issues.addLabels({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: context.payload.pull_request.number,
                  labels: [label]
                });
                break;
              }
            }

  no-ai-attribution:
    name: No AI Attribution
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Scan commit messages and PR body
        env:
          PR_BODY: ${{ github.event.pull_request.body }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          # Trailer/footer forms only: a commit that merely mentions Claude or
          # Anthropic in prose is fine. Human Co-authored-by trailers are fine.
          PAT='^[[:space:]]*Co-authored-by:.*(Claude|Anthropic|noreply@anthropic)|Generated with \[?(Claude|Anthropic)'
          fail=0
          if git log --format='%B' "$BASE_SHA..$HEAD_SHA" | grep -Eiq "$PAT"; then
            echo "::error::AI attribution found in a commit message on this branch"
            fail=1
          fi
          if printf '%s' "$PR_BODY" | grep -Eiq "$PAT"; then
            echo "::error::AI attribution found in the PR description"
            fail=1
          fi
          [ "$fail" -eq 0 ] && echo "No AI attribution found."
          exit $fail

  ci-checks:
    name: CI Checks
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - uses: actions/checkout@v6
      - name: Validate YAML syntax
        run: |
          sudo apt-get update && sudo apt-get install -y yamllint
          find . -name "*.yml" -o -name "*.yaml" | while read file; do
            echo "Checking $file"
            yamllint -d "{extends: default, rules: {line-length: disable}}" "$file" || true
          done

No AI Attribution 从第一天起就启用阻止功能——它没有误报空间（仅匹配尾部/页脚形式，而非散文），因此不需要下面的逐步启用路径。

CI 检查逐步启用路径：

1. 使用 continue-on-error: true 部署（仅信息性，非阻塞）
2. 在 3-5 个真实 PR 上验证检查通过
3. 移除 continue-on-error 并将其添加到分支保护必需检查中
4. 随着代码库增长添加特定于项目的检查（lint、测试、构建）

没有门可以跳过。 如果 lint 失败，修复 lint——不要禁用规则。如果测试失败，修复代码——不要跳过测试。当 CI 失败时，将失败输出提供给您的代理并在再次推送之前修复它。

3d. .github/workflows/main-branch.yml

name: Release Automation

on:
  push:
    branches:
      - {{DEFAULT_BRANCH}}

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    name: Release Please
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          config-file: .github/release-please-config.json
          manifest-file: .release-please-manifest.json

  update-major-tag:
    name: Update Major Version Tag
    needs: release-please
    if: ${{ needs.release-please.outputs.release_created == 'true' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ needs.release-please.outputs.tag_name }}
      - name: Update major version tag
        env:
          TAG_NAME: ${{ needs.release-please.outputs.tag_name }}
        run: |
          MAJOR_TAG=$(echo "$TAG_NAME" | sed 's/^\(v[0-9]*\).*/\1/')
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git tag -fa "$MAJOR_TAG" -m "Update $MAJOR_TAG tag to $TAG_NAME"
          git push origin "$MAJOR_TAG" --force

3e. .github/dependabot.yml

为每个生态系统生成一个 updates 条目：

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    labels:
      - "dependencies"
    commit-message:
      prefix: "chore"
      include: "scope"

commit-message 配置确保 Dependabot PR 自动符合 conventional commits（例如 chore(deps): bump actions/checkout from v5 to v6）。

3f. .github/pull_request_template.md

## 变更内容

[详细描述变更——这将进入变更日志]

## 原因

[变更的背景和动机]

## 检查清单

- [ ] PR 标题遵循 conventional commits 格式（`type: description`）
- [ ] 描述解释了变更内容和原因（不仅仅是内容）
- [ ] 代码、日志或版本控制中没有机密信息
- [ ] 测试在本地通过

“原因”部分至关重要——仅说明内容的 PR 描述与差异冗余。原因提供了上下文，使未来的 git-blame 更有用。

3g. .gitignore（如果缺失）

检查是否存在 .gitignore。如果不存在，创建一个适合项目的文件：

# 依赖项
node_modules/

# 构建输出
dist/
build/
.next/

# 环境
.env
.env.local
*.pem

# IDE
.idea/

# 操作系统
.DS_Store
Thumbs.db

适应检测到的技术栈。永远不要提交 node_modules/、.env 或构建产物。

3h. docs/DEVELOPMENT.md

生成一份开发指南，涵盖：

• 分支工作流——基于主干开发：短期特性分支（1-3 天），快速合并回去。分支命名：feature/<desc>、fix/<desc>、chore/<desc>。
• 提交纪律——在分支内自由提交（任何格式）。只有 PR 标题很重要——它成为主分支上的 squash 合并提交信息，并出现在变更日志中。
• PR 标题格式——类型表格：feat、fix、docs、chore、refactor、test、ci。破坏性变更：feat!: 或正文中的 BREAKING CHANGE:。
• 变更规模——目标每个 PR 约 100 行。单个逻辑变更约 300 行可以接受。1000 行以上必须拆分。将重构与特性工作分开——它们是不同的变更。
• PR 描述——第一行：简短、祈使、独立。正文：正在变更什么以及为什么。反模式：“修复错误”、“更新文件”、“阶段 1”。
• 自动检查——PR 标题验证（必需，阻止合并）、自动标签（信息性）、CI 检查（最初非阻塞，逐步提升为必需）。
• 发布流程——release-please 创建发布 PR → 合并 → GitHub 发布 + 标签 + 变更日志。版本演进：pre-1.0（feat → minor，fix → patch）与 post-1.0（feat → minor，fix → patch，BREAKING CHANGE → major）对比。
• 故障排除——常见问题：PR 标题验证失败（编辑标题）、CI 检查失败、合并被阻止（检查必需的状态）。

在标题中使用 {{PROJECT_NAME}}。

步骤 4：分支保护建议

创建文件后，将这些作为手动步骤呈现（不自动应用）：

推荐为 {{DEFAULT_BRANCH}} 设置的 GitHub 分支保护：
  ✓ 合并前要求拉取请求
  ✓ 要求状态检查：“Validate PR Title”
  ✓ 要求分支保持最新
  ✓ 仅允许 squash 合并
  ✓ 要求线性历史

为什么使用 squash 合并： 分支历史（WIP 提交、修复、实验）保留在 PR 中。主分支获得一个干净、有意义、线性的日志，其中每次提交都是 conventional commit。这使得 release-please 和 git log --oneline 变得有用。

步骤 5：启用工作流权限

Release-please 需要权限才能通过 GitHub Actions 创建拉取请求。这在新仓库上默认是禁用的，会导致“发布自动化”工作流失败并显示：

GitHub Actions is not permitted to create or approve pull requests.

指示用户启用此设置：

GitHub 仓库 → Settings → Actions → General → Workflow permissions:
  ✓ 读写权限（release-please 推送更新日志提交所必需）
  ✓ 允许 GitHub Actions 创建和批准拉取请求（发布 PR 所必需）

此步骤必须在第一次推送到 {{DEFAULT_BRANCH}} 之前完成，否则 release-please 将在每次推送时失败，直到启用。

步骤 6：验证

# 验证 YAML 语法
yamllint .github/workflows/*.yml .github/dependabot.yml

# 验证 JSON
python3 -c "import json; ...

[已截断以供翻译]