跳到主要内容

代码托管：模板、标签、评审、分支保护

代码托管不是把代码放上去就完事了。一个能协作的仓库，需要几层"规矩"。这些都是开关式的配置，一次配好长期用。

一、Issue 模板：让提问的人自己填完整​

有人提 Bug，正文只有一句"用不了"。解决方法是模板。

在默认分支的 .cnb/ISSUE_TEMPLATE/ 目录下放置模板文件：

.cnb/
└── ISSUE_TEMPLATE/
    ├── config.yml          # 可选：模板选择页配置
    ├── bug-report.yml      # YAML 表单模板（推荐）
    └── feature-request.md  # Markdown 模板

限制：单文件最大 256KB，最多识别 10 个模板。

YAML 模板由一堆"组件"拼成表单，支持五种：

type用途
input单行输入
textarea多行（默认 Markdown 编辑器，render: text 变纯文本）
markdown只读说明文字
dropdown下拉（multiple: true 多选）
checkboxes勾选清单

一个实用的 Bug 模板：

.cnb/ISSUE_TEMPLATE/bug-report.yml
name: Bug 反馈
description: 用于提交 Bug 的模板
title: "[Bug] "
labels: ["bug"]
body:
  - type: input
    attributes:
      label: 版本号
      placeholder: 例如 1.0.0
    validations:
      required: true
  - type: textarea
    attributes:
      label: 复现步骤
      placeholder: 请描述完整的复现步骤
    validations:
      required: true
  - type: textarea
    attributes:
      label: 报错日志
      render: text
      placeholder: 粘贴完整报错日志
  - type: checkboxes
    attributes:
      label: 提交前检查
      options:
        - label: 已复现问题
          required: true
        - label: 已确认无敏感信息

config.yml 里还能关掉空白 Issue：

.cnb/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: 使用帮助
    url: https://docs.cnb.cool
    about: 使用过程中遇到的问题，可以在这里获取帮助

二、分类标签：直接抄别人的​

标签体系不用自己设计。进标签管理页点「导入」，粘贴一个公开仓库地址（比如 https://cnb.cool/cnb/docs），它的标签会增量导入进来，不覆盖已有的。

三、PR 评审​

PR 是 CNB 的强项：支持逐行对比、逐行评论，合并时还能自动指派评审人。

评审流程上有两个值得配的东西：

1. 自动指派评审人

.cnb.yml
main:
  pull_request:
    - stages:
        - name: 随机添加一位评审人
          type: git:reviewer
          options:
            type: add-reviewer-from-repo-members
          exports:
            reviewersForAt: REVIEWERS_FOR_AT
        - name: 通知
          script: 'echo "please review: $REVIEWERS_FOR_AT"'

2. 评审通过后自动合并

见后面"自动化"那篇，用 pull_request.mergeable + git:auto-merge。

四、分支保护：让 main 不能乱推​

进仓库 设置 → 分支保护，为 main 加上规则：

  • 需要评审人批准
  • 需要通过状态检查（CI 必须绿）
  • 禁止直接 push

这三条打开之后，pull_request.mergeable 事件才有意义——它只在"保护分支 + 可合并 + 评审通过"三个条件同时满足时触发。

五、提交签名（GPG）​

要给"这个提交确实是我提交的、且没被改过"做背书时用 GPG：

# 生成密钥对
gpg --full-generate-key

# 查看密钥 ID（sec 行 rsa4096/ 后面那串）
gpg --list-secret-keys --keyid-format=long

# 导出公钥，粘贴到 个人设置 → GPG 公钥
gpg --armor --export <你的密钥ID>

# 配置 Git 使用该密钥
git config --global user.signingkey <你的密钥ID>
git commit -S -m "your message"

:::warning 邮箱必须匹配 签名密钥关联的邮箱，必须和提交里 committer 的邮箱一致，且已在账号中验证。否则不显示「已验证」。 :::

有意思的是，在 CNB 网页上直接产生的提交（在线编辑文件、合并 PR）默认就带平台签名，显示为已验证。所以纯网页工作流，签名这件事是免配的。

六、元数据：给 Tag 和 Commit 挂信息​

Tag 和 Commit 都能存 key: value 元数据，用于记录发布说明、构建号、审批人。

.cnb.yml
main:
  push:
    - stages:
        - name: 写入元数据
          image: cnbcool/annotations:latest
          settings:
            type: ADD
            data: |
              build-id=$CNB_BUILD_ID
              commit=$CNB_COMMIT_SHORT

push 事件写进当前 Commit，tag_push 写进对应 Tag。页面上只能看，改要通过插件/API。