ci: 规范项目开发与验证流程

.github/workflows/lint.yml

@@ -2,6 +2,8 @@ name: Lint
 
 on:
   push:
+    branches:
+      - main
   pull_request:
 
 permissions: {}
@@ -11,7 +13,7 @@ jobs:
     permissions:
       contents: read
     name: Run on Ubuntu
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - name: Clone the code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

.github/workflows/test-e2e.yml

@@ -2,7 +2,10 @@ name: E2E Tests
 
 on:
   push:
+    branches:
+      - main
   pull_request:
+  workflow_dispatch:
 
 permissions: {}
 
@@ -11,7 +14,7 @@ jobs:
     permissions:
       contents: read
     name: Run on Ubuntu
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - name: Clone the code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -25,14 +28,20 @@ jobs:
 
       - name: Install the latest version of kind
         run: |
-          curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-$(go env GOARCH)
+          mkdir -p ./bin
-          chmod +x ./kind
+          curl -Lo ./bin/kind https://kind.sigs.k8s.io/dl/latest/kind-linux-$(go env GOARCH)
-          sudo mv ./kind /usr/local/bin/kind
+          chmod +x ./bin/kind
 
-      - name: Verify kind installation
+      - name: Verify Docker and kind
-        run: kind version
+        run: |
+          docker info
+          ./bin/kind version
 
       - name: Running Test e2e
         run: |
           go mod tidy
-          make test-e2e
+          make test-e2e KIND=./bin/kind
+
+      - name: Clean up the Kind cluster
+        if: always()
+        run: make cleanup-test-e2e KIND=./bin/kind

.github/workflows/test.yml

@@ -2,6 +2,8 @@ name: Tests
 
 on:
   push:
+    branches:
+      - main
   pull_request:
 
 permissions: {}
@@ -11,7 +13,7 @@ jobs:
     permissions:
       contents: read
     name: Run on Ubuntu
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - name: Clone the code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -27,3 +29,6 @@ jobs:
         run: |
           go mod tidy
           make test
+
+      - name: Verify generated files and modules are current
+        run: git diff --exit-code

CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# 开发流程
+
+这个项目采用轻量的 trunk-based development。`main` 应始终处于可构建、可测试、
+可以部署到测试集群的状态。
+
+## 分支与提交
+
+日常改动从最新 `main` 创建短生命周期分支：
+
+```text
+feature/<主题>   新能力
+fix/<主题>       缺陷修复
+refactor/<主题>  不改变行为的重构
+docs/<主题>      文档
+chore/<主题>     工具、依赖和 CI
+```
+
+提交信息使用 `<类型>: <中文说明>`，例如：
+
+```text
+feat: 添加 PostgreSQLTenant 默认值校验
+fix: 保留删除中的数据库租户
+test: 覆盖 OpenBao 写入失败后的重试
+```
+
+允许的常用类型为 `feat`、`fix`、`refactor`、`test`、`docs`、`chore` 和
+`ci`。一个提交只表达一个可理解的变更；禁止提交真实数据库凭据、OpenBao Token、
+kubeconfig 或本地生成的二进制。
+
+## 开发循环
+
+1. 从最新 `main` 创建分支。
+2. 先用测试描述预期的 reconcile 行为，再实现最小改动。
+3. 修改 API type 或 Kubebuilder marker 后运行：
+
+   ```sh
+   make manifests generate
+   ```
+
+4. 提交前运行：
+
+   ```sh
+   make test
+   make lint
+   git diff --exit-code
+   ```
+
+5. 推送分支并创建 PR。PR 说明应包含动机、行为变化、验证方式，以及对数据库或
+   OpenBao 的风险。
+6. CI 通过后 squash merge，删除已合并分支。
+
+`make test-e2e` 会创建并删除名为
+`postgresql-tenant-operator-test-e2e` 的 Kind 集群，只能在隔离环境运行，不能指向
+homelab 日常集群。
+
+## CI 层次
+
+Gitea Actions 直接使用 `.github/workflows` 中兼容 GitHub Actions 语法的工作流：
+
+- `Tests`：运行生成、格式化、vet、envtest，并检查生成文件和 `go.mod`/`go.sum`
+  没有未提交漂移。
+- `Lint`：校验 golangci-lint 配置并运行静态检查。
+- `E2E Tests`：在一次性 Kind 集群中安装 CRD 和 controller，执行端到端验证。
+
+三个工作流都在 PR 上运行，并在合并进入 `main` 后再次运行；E2E 也支持手动触发。
+所有 job 固定使用集群内的 `self-hosted` Docker runner。E2E runner 必须能够访问
+Docker daemon，供 Kind 创建临时节点容器。建议在 Gitea 中保护 `main`，要求三个
+检查通过并禁止 force push。
+
+## Controller 约定
+
+- reconcile 必须幂等，以 PostgreSQL catalog 和 OpenBao 为事实来源。
+- `status` 只记录观察结果，不保存明文秘密，也不作为外部资源的事实来源。
+- 外部调用必须有超时、可重试，并区分永久错误与暂时错误。
+- 日志、Event、Condition message 和测试输出不得包含密码或管理凭据。
+- 默认删除策略是 `Retain`；任何实际销毁路径都必须有 finalizer 和独立测试。
+- controller 测试优先使用 fake PostgreSQL/OpenBao client；API 交互使用 envtest；真实
+  组件集成留给 Kind e2e。
+
+## API 变更
+
+`v1alpha1` 允许快速调整，但每次 schema 变更仍需同步修改：
+
+- Go API types 和校验 marker；
+- 生成的 CRD 与 RBAC；
+- `config/samples`；
+- 架构或用户文档；
+- conversion/defaulting 需求评估；
+- 覆盖新旧行为的测试。
+
+不要手工编辑 `PROJECT`、`zz_generated.*.go`、`config/crd/bases` 或生成的 RBAC；使用
+Kubebuilder、`make manifests` 和 `make generate` 更新它们。

README.md

@@ -37,6 +37,8 @@ spec:
 更完整的资源见 [`config/samples`](config/samples)，初始架构和安全边界见
 [`docs/architecture.md`](docs/architecture.md)。
 
+分支、提交、PR 和 CI 约定见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
+
 ## 本地开发
 
 需要 Go、Docker、`kubectl` 和一个可用于测试的 Kubernetes 集群。