f28f20ba56
未設時讀 config.env（行為不變）；設了讀 config.<profile>.env。 .gitignore 新增 config.*.env 但保留 config.example.env。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
146 lines
6.2 KiB
Markdown
146 lines
6.2 KiB
Markdown
# gitea-cli
|
||
|
||
一組 bash 腳本，把自架 Gitea 的常見操作封裝成單一指令；目前實作「建立 repo → init → commit → push」，其他功能（list / clone / rename / release / …）依設計文件擴充中。
|
||
|
||
## 檔案結構
|
||
|
||
```
|
||
gitea-cli/
|
||
├── SKILL.md # Claude Code skill 定義
|
||
├── README.md # 本檔
|
||
├── CLAUDE.md # 給 Claude 的 repo 內指引
|
||
├── config.example.env # 設定範本（可提交）
|
||
├── config.env # 實際設定（內含 token，.gitignore 排除）
|
||
├── .gitignore
|
||
├── docs/
|
||
│ └── superpowers/specs/ # 擴充設計文件
|
||
└── scripts/
|
||
└── publish.sh # 建 repo + 推送
|
||
```
|
||
|
||
> 以下範例用 `/path/to/gitea-cli` 代表本 skill 實際所在位置（你 clone 到哪裡就是哪裡）；也可以 symlink 到 `~/.claude/skills/gitea-cli` 讓 Claude Code 自動識別。
|
||
|
||
## 首次設定
|
||
|
||
1. **產生 Gitea access token**
|
||
登入 Gitea → 使用者設定 → Applications → Generate New Token
|
||
URL： `<你的 Gitea URL>/-/user/settings/applications`
|
||
權限至少勾選：**write:repository**
|
||
|
||
2. **複製設定檔並填入 token**
|
||
```bash
|
||
cd /path/to/gitea-cli
|
||
cp config.example.env config.env
|
||
# 用任一編輯器編輯 config.env，填入三個變數
|
||
```
|
||
|
||
`config.env` 範例（請替換為自己的值）：
|
||
```env
|
||
GITEA_URL=http://your-gitea.example.com:3000
|
||
GITEA_USER=your-username
|
||
GITEA_TOKEN=你剛才產生的_token
|
||
```
|
||
|
||
**多組 Gitea 站／帳號**：另存成 `config.<profile>.env`，執行腳本時帶 `GITEA_PROFILE=<profile>` 切換：
|
||
```bash
|
||
cp config.example.env config.work.env
|
||
# 編輯 config.work.env
|
||
|
||
GITEA_PROFILE=work bash /path/to/gitea-cli/scripts/list.sh
|
||
```
|
||
未設 `GITEA_PROFILE` 時讀 `config.env`（預設）。`config.*.env` 已被 `.gitignore` 排除。
|
||
|
||
3. （選用）讓 Claude Code 自動辨識這個 skill（兩擇一）：
|
||
|
||
**A. Symlink 本地開發目錄**（適合會持續改腳本的情境）
|
||
```bash
|
||
ln -s /path/to/gitea-cli ~/.claude/skills/gitea-cli
|
||
```
|
||
|
||
**B. 從自架 Gitea clone 到 skills 目錄**（適合多台機器、每台獨立設定 config.env）
|
||
```bash
|
||
cd ~/.claude/skills
|
||
# 若已有另一份 gitea-cli 可用，直接：
|
||
bash /path/to/existing/gitea-cli/scripts/clone.sh gitea-cli ~/.claude/skills/gitea-cli
|
||
# 否則用一般 git clone（之後會要求認證）：
|
||
git clone http://your-gitea.example.com:3000/<user>/gitea-cli.git
|
||
# clone 完成後，在 ~/.claude/skills/gitea-cli/ 底下：
|
||
cp config.example.env config.env
|
||
# 編輯 config.env 填入這台機器要用的 GITEA_URL / GITEA_USER / GITEA_TOKEN
|
||
```
|
||
|
||
不管用哪一種，下次開啟 Claude Code session 就會自動載入這個 skill。
|
||
|
||
## 使用方式
|
||
|
||
在要推送的專案目錄下執行：
|
||
|
||
```bash
|
||
# 用當前資料夾名當 repo 名，建立 public repo
|
||
bash /path/to/gitea-cli/scripts/publish.sh
|
||
|
||
# 指定 repo 名
|
||
bash /path/to/gitea-cli/scripts/publish.sh my-project
|
||
|
||
# 建立 private repo
|
||
bash /path/to/gitea-cli/scripts/publish.sh my-project private
|
||
```
|
||
|
||
| 參數 | 說明 | 預設 |
|
||
|------|------|------|
|
||
| `$1` | repo 名稱 | 當前目錄名 |
|
||
| `$2` | 可見性：`public` / `private` | `public` |
|
||
|
||
## 所有可用腳本
|
||
|
||
| 腳本 | 用法 |
|
||
|---|---|
|
||
| `publish.sh` | `publish.sh [repo] [public\|private] [-m "msg"]` — 建 repo + 推目前目錄 |
|
||
| `list.sh` | `list.sh [--private\|--public] [--format table\|tsv\|name]` — 列出自己的 repo |
|
||
| `clone.sh` | `clone.sh <repo> [target-dir]` — clone 到本地，origin 保持乾淨 URL |
|
||
| `rename.sh` | `rename.sh <old> <new>` — 改名；若 cwd origin 指到舊 repo 自動更新 |
|
||
| `visibility.sh` | `visibility.sh <repo> <public\|private>` — 切換可見性 |
|
||
| `meta.sh` | `meta.sh <repo> [--desc ...] [--topics a,b,c]` — 設定 description / topics |
|
||
| `archive.sh` | `archive.sh <repo> [--unarchive] [-y]` — archive / unarchive |
|
||
| `delete.sh` | `delete.sh <repo> [-y]` — 刪除（互動模式需重新輸入 repo 名） |
|
||
| `tag.sh` | `tag.sh <tag> [-m "msg"]` — 建 annotated tag 並 push origin |
|
||
| `release.sh` | `release.sh <tag> [--name ...] [--notes ...] [--asset PATH]... [--repo NAME]` — 建 release + 上傳 asset |
|
||
|
||
所有呼叫 API 的腳本共用 `scripts/lib/common.sh`，該 lib 負責 config 載入、API 呼叫、一次性 credential helper 注入、互動確認。
|
||
|
||
## 腳本執行步驟
|
||
|
||
1. 讀取 `config.env`，驗證三個必要環境變數都有值
|
||
2. 呼叫 Gitea API `POST /api/v1/user/repos` 建立 repo
|
||
- `201` 建立成功
|
||
- `409` repo 已存在，略過
|
||
- `401/403` 授權錯誤，提示檢查 token
|
||
3. 若當前目錄沒有 `.git` → `git init -b main`
|
||
4. 若還沒有任何 commit → 自動建 initial commit（含空 commit 以支援空目錄）
|
||
5. 若有未提交變更 → `git add -A && git commit -m "Update"`
|
||
6. 設定 `origin` 為**不含 token** 的乾淨 URL
|
||
7. 用一次性 credential helper 帶 token 執行 `git push -u origin <branch>`
|
||
|
||
## 安全設計
|
||
|
||
- **`config.env` 內含 token，`.gitignore` 已排除**，不會被提交。
|
||
- **token 不寫入 `.git/config`**：`origin` 為乾淨 URL，push 時用 `git -c credential.helper=...` 注入，結束後即消失。
|
||
- Credential helper 以變數替換方式產生 shell 片段；命令列參數會短暫出現在 `ps` 中，僅限本機使用者看到（自架 LAN Gitea 場景可接受）。
|
||
- `clone.sh` 完成後 origin 也是乾淨 URL，再次 `git pull` / `git push` 要重新帶 credential（跟 `publish.sh` 一致）。
|
||
|
||
## 常見問題
|
||
|
||
**Q：推送完之後再跑 `git push`，為什麼失敗？**
|
||
A：origin 是乾淨 URL，再次 push 會要求認證。解法二選一：
|
||
- 再用本腳本 push（會重新帶 token）
|
||
- 自行設定 git credential helper 記住帳密
|
||
|
||
**Q：Token 失效／過期？**
|
||
A：重新到 Gitea 產生 token，覆蓋 `config.env` 裡的 `GITEA_TOKEN`。
|
||
|
||
**Q：要換成另一個 Gitea 站或使用者？**
|
||
A：常駐切換就另存成 `config.<profile>.env`，執行時帶 `GITEA_PROFILE=<profile>`；只是單次替換就直接改 `config.env` 的 `GITEA_URL` / `GITEA_USER`。
|
||
|
||
**Q：可以用在非 Gitea（例如 Gitea clone 產品）嗎？**
|
||
A：本腳本用的是 Gitea API v1，Forgejo 相容，GitHub/GitLab 不相容。
|