docs: plan manual actions entry

2026-10-13 14:34:39 +08:00
parent 4a70b85353
commit 5e01e4344b
1 changed files with 91 additions and 0 deletions
@@ -0,0 +1,91 @@
+# Olons Server Manual Actions Entry Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让 Gitea 在 `olons_server` 仓库的 Actions 页面识别 `dev` 分支现有的手动部署工作流。
+
+**Architecture:** 不复制或修改工作流文件，不触发部署；仅将仓库默认分支从初始化用的 `main` 改为实际开发与部署分支 `dev`。通过 Gitea API 在变更前后验证默认分支、工作流识别结果和 Actions 运行数量。
+
+**Tech Stack:** Gitea 1.27 API、Gitea Actions、Git
+
+---
+
+### Task 1: 验证变更前状态
+
+**Files:**
+- Verify: `.gitea/workflows/deploy.yml`
+
+- [ ] **Step 1: 确认远端 `dev` 包含手动部署工作流**
+
+Run:
+
+```bash
+git show origin/dev:.gitea/workflows/deploy.yml | grep -F 'workflow_dispatch:'
+```
+
+Expected: 输出 `workflow_dispatch:`。
+
+- [ ] **Step 2: 运行远端契约断言并确认其按预期失败**
+
+使用现有 Gitea 登录态读取仓库与 Actions API，断言：
+
+```python
+assert repository["default_branch"] == "dev"
+assert any(item["path"] == ".gitea/workflows/deploy.yml" and item["state"] == "active" for item in workflows["workflows"])
+```
+
+Expected: FAIL；变更前默认分支为 `main`，识别到的工作流数量为 0。
+
+### Task 2: 修改默认分支
+
+**Files:**
+- Modify: Gitea repository setting `im_team/olons_server.default_branch`
+
+- [ ] **Step 1: 通过 Gitea API 将默认分支改为 `dev`**
+
+Run:
+
+```bash
+credential_data=$(printf 'protocol=https\nhost=git.118im.com\n\n' | git credential fill)
+gitea_user=$(printf '%s\n' "$credential_data" | sed -n 's/^username=//p')
+gitea_password=$(printf '%s\n' "$credential_data" | sed -n 's/^password=//p')
+curl -u "$gitea_user:$gitea_password" \
+  -X PATCH https://git.118im.com/api/v1/repos/im_team/olons_server \
+  -H 'Content-Type: application/json' \
+  --data '{"default_branch":"dev"}'
+unset credential_data gitea_user gitea_password
+```
+
+认证信息仅从本机现有 Git credential helper 注入进程，不写入文件、不输出到日志。
+
+Expected: HTTP 200，响应中的 `default_branch` 为 `dev`。
+
+### Task 3: 验证手动入口并记录结果
+
+**Files:**
+- Create: `/Users/aa/.codex/memories/extensions/ad_hoc/notes/2026-10-13T14-34-07-olons-server-manual-actions.md`
+
+- [ ] **Step 1: 重新运行远端契约断言**
+
+Expected: PASS；默认分支为 `dev`，`.gitea/workflows/deploy.yml` 状态为 `active`。
+
+- [ ] **Step 2: 确认没有因默认分支变更产生新的部署运行**
+
+Run: 调用 `GET /api/v1/repos/im_team/olons_server/actions/runs?limit=5`。
+
+Expected: 运行数量与变更前相同；本任务不触发 `workflow_dispatch`。
+
+- [ ] **Step 3: 推送设计与计划提交**
+
+Run:
+
+```bash
+git push origin dev
+```
+
+Expected: 本地 `dev` 与 `origin/dev` 一致。
+
+- [ ] **Step 4: 更新记忆扩展说明**
+
+记录默认分支变更、工作流可见性验证、未触发部署以及后续手动运行入口；不得记录凭据值。
+