Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@ name: CI

on:
pull_request:
branches: [dev, main]
push:
branches: [main]
branches: [dev, main]

permissions:
contents: read
Expand Down Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@
<a href="docs/deployment.md">部署</a> ·
<a href="docs/configuration.md">配置</a> ·
<a href="docs/observability.md">控制台与 API</a> ·
<a href="docs/development.md">开发</a>
<a href="docs/development.md">开发</a> ·
<a href="docs/branching.md">分支模型</a>
</p>

## 核心功能
Expand Down
60 changes: 60 additions & 0 deletions docs/branching.md
Original file line number Diff line number Diff line change
@@ -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 权限,用于规则配错时自救。
33 changes: 22 additions & 11 deletions docs/releasing.md
Original file line number Diff line number Diff line change
@@ -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 不调用真实模型供应商。
Loading