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

   cd /path/to/gitea-cli
   cp config.example.env config.env
   # 用任一編輯器編輯 config.env，填入三個變數
   

   config.env 範例（請替換為自己的值）：

   GITEA_URL=http://your-gitea.example.com:3000
   GITEA_USER=your-username
   GITEA_TOKEN=你剛才產生的_token
   

   多組 Gitea 站／帳號：另存成 config.<profile>.env，執行腳本時帶 GITEA_PROFILE=<profile> 切換：

   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 本地開發目錄（適合會持續改腳本的情境）

   ln -s /path/to/gitea-cli ~/.claude/skills/gitea-cli
   

   B. 從自架 Gitea clone 到 skills 目錄（適合多台機器、每台獨立設定 config.env）

   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。

使用方式

在要推送的專案目錄下執行：

# 用當前資料夾名當 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 不相容。