diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fbcc131..b3cfdbb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,9 @@ name: CI on: pull_request: + branches: [dev, main] push: - branches: [main] + branches: [dev, main] permissions: contents: read @@ -36,7 +37,10 @@ jobs: - name: Check for committed API keys run: '! git grep -nE "sk-[A-Za-z0-9_-]{20,}" -- . ":(exclude)docs/opencode-go-native-report.md"' + # 三个镜像的构建最贵,只在 PR(含晋升 PR)和 main 上跑; + # dev 的日常 push 只需快速反馈,交给上面的 test job。 containers: + if: github.event_name == 'pull_request' || github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6d4655a..14cc2a1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,6 +15,17 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + fetch-depth: 0 + # main 是唯一的发布分支:tag 只允许打在 main 的提交上。 + # 防止误在 dev/功能分支的提交上打 tag 而发布未晋升的代码。 + - name: Ensure the tag is on main + run: | + git fetch --no-tags origin main + if ! git merge-base --is-ancestor "$GITHUB_SHA" FETCH_HEAD; then + echo "::error::tag ${GITHUB_REF_NAME} is not contained in origin/main; release only from main" + exit 1 + fi - uses: actions/setup-go@v5 with: go-version-file: go.mod diff --git a/README.md b/README.md index 132f5fa..eb68294 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ 部署 · 配置 · 控制台与 API · - 开发 + 开发 · + 分支模型

## 核心功能 diff --git a/docs/branching.md b/docs/branching.md new file mode 100644 index 0000000..e538779 --- /dev/null +++ b/docs/branching.md @@ -0,0 +1,60 @@ +# 分支模型 + +仓库使用「双分支晋升」模型:`dev` 是主干,`main` 是发布账本。 + +```text +feature/* ──PR(squash)──▶ dev ──晋升 PR(merge commit)──▶ main ──tag──▶ 镜像发布 +``` + +## 分支职责 + +| 分支 | 角色 | 变更方式 | +| --- | --- | --- | +| `dev` | 默认分支、主干。所有开发都合入这里。 | 只能通过 PR(squash) | +| `main` | 发布分支。只接受来自 `dev` 的晋升 PR,tag 只打在这里。 | 只能通过 PR(merge commit) | + +`dev` 是仓库默认分支,因此新 clone 和新建 PR 的 base 默认都落在它上面。 + +## 日常开发 + +```bash +git switch dev && git pull +git switch -c feat/my-change +# ... 提交 ... +git push -u origin feat/my-change +gh pr create --base dev +``` + +PR 合并后源分支会被自动删除。这是仓库设置 `delete_branch_on_merge` 的行为,不是 +workflow:fork 来的 PR 源分支在对方仓库,不会被删。 + +合入 `dev` 使用 **squash**,一个 PR 对应 `dev` 上的一个提交。 + +## 发布:先晋升,再打 tag + +1. 开一个 `dev → main` 的晋升 PR,用 **merge commit** 合并(不要 squash)。 + 于是 `main` 上「一个提交 = 一次发布」,可审计。 +2. 在该 merge commit 上打 annotated tag,见[发布](releasing.md)。 + +> `main` 会因为晋升产生 merge commit,所以分支保护**不要**开启 +> "Require linear history",否则晋升 PR 永远合不进去。 + +## 紧急修复 + +走正常路径(`dev` → 晋升)需要两个 PR,会拉长恢复时间。允许直接向 `main` 提 hotfix +PR,但**合入后必须立刻把 `main` 合回 `dev`**,否则下一次晋升会把这个修复覆盖掉: + +```bash +git switch dev && git pull +git merge --no-ff origin/main -m "chore: back-merge hotfix from main" +git push +``` + +## CI 与保护规则 + +- `.github/workflows/ci.yml`:`test` 在 PR 及 `dev`/`main` 的 push 上运行; + `containers` 只在 PR 和 `main` 上运行(三个镜像构建最贵,`dev` 的日常 push 不需要)。 +- `.github/workflows/release.yml`:仅由 `v*` tag 触发,且第一步校验该 tag 是 `main` + 的祖先,避免误发布未经晋升的代码。 +- `dev` 与 `main` 均配置了 ruleset:禁止删除、禁止 force push、必须走 PR、必须通过 + `test` + `containers` 状态检查。仓库管理员保留 bypass 权限,用于规则配错时自救。 diff --git a/docs/releasing.md b/docs/releasing.md index 9e7e62f..3d086aa 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -1,17 +1,28 @@ # 发布 -普通 push 和 pull request 运行 `.github/workflows/ci.yml`:Go、前端、三个容器构建及 -发布 Compose 校验。CI 不调用真实模型供应商。 +分支模型见[分支模型](branching.md):`dev` 是主干,`main` 是发布分支,tag 只能打在 +`main` 上。 -发布使用语义版本 tag: +## 流程 -```bash -git tag v0.1.0 -git push origin v0.1.0 -``` +1. 确认要发布的改动都已合入 `dev` 且 CI 通过。 +2. 开 `dev → main` 晋升 PR,用 **merge commit** 合并。 +3. 切到 `main` 拉取最新代码,在晋升 merge commit 上打语义化版本 tag: -`.github/workflows/release.yml` 会为 gateway、new-api、console 构建 -`linux/amd64` 和 `linux/arm64` 镜像并推送到 GHCR,同时生成 SBOM 和 provenance。 + ```bash + git switch main && git pull + git tag -a v0.1.8 -m "v0.1.8" + git push origin v0.1.8 + ``` -发布标签包括完整版本、major/minor、major、commit SHA 和 `latest`。发布前必须保证 -工作树已提交且 CI 通过;真实供应商 Key 永远不进入 GitHub Actions。 +`.github/workflows/release.yml` 先校验该 tag 是 `main` 的祖先(否则直接失败),再为 +gateway、new-api、console 构建 `linux/amd64` 和 `linux/arm64` 镜像并推送到 GHCR, +同时生成 SBOM 和 provenance。 + +发布标签包括完整版本、major/minor、major、commit SHA 和 `latest`;tag 名含 `-` +(如 `v0.2.0-rc.1`)时不会打 `latest`。真实供应商 Key 永远不进入 GitHub Actions。 + +## CI + +`.github/workflows/ci.yml` 在 PR 以及 `dev`/`main` 的 push 上运行 Go 测试和前端构建; +在 PR 和 `main` 上额外执行三个容器构建与发布 Compose 校验。CI 不调用真实模型供应商。