mcpField
G
gitea

gitea

github.com/halfwhey开发375 次安装17 周前更新
代码仓库

关于 gitea

Gitea 命令行技能，使用 extea 管理代码仓库、问题、拉取请求、发布和项目看板。适用于需要通过命令行或 API 操作 Gitea 的开发者，并补充 tea 不包含的看板管理命令。

主要功能

  1. 01仓库创建与管理
  2. 02问题和拉取请求操作
  3. 03标签、里程碑与发布管理
  4. 04项目看板与列操作
  5. 05原始 API 端点访问
  6. 06支持看板数据 JSON 输出

适用场景

  1. 01从命令行创建仓库并推送代码
  2. 02维护问题、拉取请求及其审查
  3. 03管理项目看板与任务列
  4. 04通过 API 执行未提供专用命令的操作

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/halfwhey/extea --skill gitea

安装后在 Claude Code 中输入/gitea确认已加载。

详细介绍

Gitea

使用 extea 与 Gitea 实例交互。extea 是 tea 的即插即用替代品，并新增了项目看板（看板式）管理功能。

身份验证

  • 所有命令都使用 --login <name>（或 -l <name>）选择登录配置。
  • 看板密码与登录信息一起存储在 ~/.config/tea/config.yml 中。也可以通过 GITEA_PASSWORD 环境变量设置。
  • 对于通过 HTTP 进行的 git 推送/拉取，请将令牌嵌入 URL：http://user:TOKEN@<host>/owner/repo.git
  • 运行 extea login add 创建登录配置（API 令牌 + 可选的看板密码）。

仓库

extea repos list -l <login>
extea repos create --name <name> --description "<desc>" -l <login>
extea repos delete --name <name> --owner <owner> --force -l <login>

创建计划推送现有本地仓库的仓库时，请勿使用 --init。

问题

extea issues list -l <login> -r owner/repo
extea issues list -l <login> -r owner/repo --state all    # open + closed
extea issues create -l <login> -r owner/repo \
  --title "<title>" --description "<desc>" \
  --labels "<label1>,<label2>" --milestone "<milestone title>" --assignees "<user>"
extea issues close   -l <login> -r owner/repo <number>
extea issues reopen  -l <login> -r owner/repo <number>

拉取请求

extea pulls list -l <login> -r owner/repo
extea pulls list -l <login> -r owner/repo --state all     # open + merged + closed
extea pulls create -l <login> -r owner/repo \
  --title "<title>" --description "<desc>" \
  --head <branch> --base main \
  --labels "<labels>" --milestone "<ms>"
extea pulls close -l <login> -r owner/repo <number>
合并 PR

如果 PR 已合并，extea pulls merge 可能会静默失败。建议使用 API：

extea api -l <login> -X POST "/repos/owner/repo/pulls/<number>/merge" \
  -f Do=merge \
  -f MergeMessageField="<commit message>"
# Do= options: merge | rebase | squash | manually-merged

标签

extea labels list   -l <login> -r owner/repo
extea labels create -l <login> -r owner/repo --name "<name>" --color "#hexcolor" --description "<desc>"
extea labels delete -l <login> -r owner/repo <id>

里程碑

extea milestones list   -l <login> -r owner/repo
extea milestones list   -l <login> -r owner/repo --state all
extea milestones create -l <login> -r owner/repo --title "<title>" --description "<desc>" --deadline "<YYYY-MM-DD>"
extea milestones close  -l <login> -r owner/repo "<title>"   # close by title string

发布

extea releases list   -l <login> -r owner/repo
extea releases create -l <login> -r owner/repo --tag <tag> --title "<title>" --note "<body>"

创建发布前，标签必须已存在于仓库中：

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
extea releases create -l <login> -r owner/repo --tag v1.0.0 --title "v1.0.0" --note "..."

评论

extea comment -l <login> -r owner/repo <issue-or-pr-number> "<comment text>"

PR 和问题共用同一套编号；以 PR 编号发表评论的方式相同。

通知

extea notifications -l <login> -r owner/repo

始终传入 -r owner/repo——即使在 git 目录中运行，extea notifications 也需要仓库上下文。

API（原始端点访问）

对于命名命令未涵盖的操作（PR 合并、wiki 等），请使用此方式：

extea api -l <login> <endpoint>                            # GET
extea api -l <login> -X POST <endpoint> -f key=value       # POST with form fields
extea api -l <login> -X PATCH <endpoint> -f key=value      # PATCH
extea api -l <login> -X DELETE <endpoint>                  # DELETE

将 JSON 输出传递给 python3 -c "import sys,json; d=json.load(sys.stdin); print(...)" 以提取字段。

项目看板

看板命令使用 Web 会话身份验证（密码存储在配置中或 GITEA_PASSWORD 环境变量中），因为 Gitea 没有用于项目看板的 REST API。

项目（projects、project、p）
# List projects
extea projects ls -l <login> -r owner/repo
extea projects ls --state all -l <login> -r owner/repo    # open + closed

# View kanban board (shows all columns and their issues)
extea projects view <id> -l <login> -r owner/repo

# Create (templates: kanban, triage, none)
extea projects create -t "<title>" --template kanban -l <login> -r owner/repo

# Edit title
extea projects edit <id> -t "<new title>" -l <login> -r owner/repo

# Close / reopen / delete
extea projects close  <id> -l <login> -r owner/repo
extea projects open   <id> -l <login> -r owner/repo
extea projects delete <id> -l <login> -r owner/repo

# Assign issues to a project (can pass multiple -i flags)
extea projects assign <project-id> -i <issue-num> -i <issue-num> -l <login> -r owner/repo

# Remove issues from a project
extea projects unassign -i <issue-num> -l <login> -r owner/repo

# Move issues between columns
extea projects move <project-id> --column <col-id> -i <issue-num> -l <login> -r owner/repo
列（columns、column、col）
# List columns in a project
extea columns ls -p <project-id> -l <login> -r owner/repo

# Create a column (--color is optional)
extea columns create -p <project-id> -t "<title>" --color "#hexcolor" -l <login> -r owner/repo

# Edit a column title
extea columns edit -p <project-id> -c <col-id> -t "<new title>" -l <login> -r owner/repo

# Delete a column (issues move to default column)
extea columns delete -p <project-id> -c <col-id> -l <login> -r owner/repo

# Set default column (new issues land here)
extea columns default -p <project-id> -c <col-id> -l <login> -r owner/repo

# Reorder columns (pass all column IDs in desired order)
extea columns move -p <project-id> --order <id1>,<id2>,<id3> -l <login> -r owner/repo
JSON 输出

在 projects list、projects view 或 columns list 中添加 --output json / -o json，即可获得机器可读的输出。可用于提取 ID：

extea projects ls -l <login> -r owner/repo -o json | python3 -c "import sys,json; [print(p['id'], p['title']) for p in json.load(sys.stdin)]"
extea columns ls -p <id> -l <login> -r owner/repo -o json | python3 -c "import sys,json; [print(c['id'], c['title']) for c in json.load(sys.stdin)]"

Wiki

wiki 是位于 http://<host>/owner/repo.wiki.git 的独立 git 仓库。

在创建第一个页面之前，wiki 仓库并不存在。 尝试克隆前，请先通过 API 初始化：

# Initialize wiki with a Home page (required before git clone works)
extea api -l <login> -X POST "/repos/owner/repo/wiki/new" \
  -f title="Home" \
  -f content_base64="$(echo '# Home page content' | base64)" \
  -f message="init: create wiki home page"

# Create additional pages
extea api -l <login> -X POST "/repos/owner/repo/wiki/new" \
  -f title="Page Title" \
  -f content_base64="$(printf '%s' "$CONTENT" | base64)" \
  -f message="docs: add page"

# List all wiki pages
extea api -l <login> "/repos/owner/repo/wiki/pages"

始终在 /tmp 中操作 wiki，以免污染当前工作目录。

# Clone wiki (only works after at least one page has been created)
if [ ! -d /tmp/repo-wiki ]; then
  git clone "http://user:${TOKEN}@<host>/owner/repo.wiki.git" /tmp/repo-wiki
fi

cd /tmp/repo-wiki
git config user.name "yourname"
git config user.email "you@host"   # Must match the Gitea account's registered email or history links won't be clickable
                                    # Check with: extea api -l <login> "/users/<username>" | python3 -c "import sys,json; print(json.load(sys.stdin)['email'])"

# Pages are markdown files: Home.md, Page-Name.md (hyphens for spaces)
# Edit files, then:
git add -A && git commit -m "Update wiki"
git push

典型工作流

# 1. Create repo and push code
extea repos create --name myrepo --description "..." -l mylogin
cd /tmp/myrepo && git init && git remote add origin "http://user:TOKEN@host/user/myrepo.git"
git push -u origin main

# 2. Set up labels and milestones
extea labels create -l mylogin -r user/myrepo --name "bug" --color "#d73a4a"
extea milestones create -l mylogin -r user/myrepo --title "v1.0" --deadline "2026-06-01"

# 3. File issues
extea issues create -l mylogin -r user/myrepo --title "Fix the thing" --labels "bug" --milestone "v1.0"

# 4. Branch, commit, PR
git checkout -b fix/the-thing && git commit -m "fix: the thing" && git push origin fix/the-thing
extea pulls create -l mylogin -r user/myrepo --title "fix: the thing" --head fix/the-thing --base main

# 5. Comment, merge
extea comment -l mylogin -r user/myrepo 1 "LGTM"
extea api -l mylogin -X POST "/repos/user/myrepo/pulls/1/merge" -f Do=merge -f MergeMessageField="fix: the thing"

# 6. Project board
extea projects create -t "Sprint 1" --template kanban -l mylogin -r user/myrepo
PROJECT_ID=$(extea projects ls -l mylogin -r user/myrepo -o json | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")
extea projects assign $PROJECT_ID -i 1 -l mylogin -r user/myrepo
# Get column IDs, then move issues
extea columns ls -p $PROJECT_ID -l mylogin -r user/myrepo -o json
extea projects move $PROJECT_ID --column <col-id> -i 1 -l mylogin -r user/myrepo

# 7. Release
git tag -a v1.0.0 -m "Release v1.0.0" && git push origin v1.0.0
extea releases create -l mylogin -r user/myrepo --tag v1.0.0 --title "v1.0.0" --note "..."

# 8. Wiki
extea api -l mylogin -X POST "/repos/user/myrepo/wiki/new" \
  -f title="Home" -f content_base64="$(echo '# Docs' | base64)" -f message="init wiki"
git clone "http://user:TOKEN@host/user/myrepo.wiki.git" /tmp/myrepo-wiki

带行内行评论的 PR 评审

extea pulls review 仅支持交互式操作。要通过脚本添加行内评论，请使用 curl 和 API：

# Get the head commit SHA first
HEAD_SHA=$(extea api -l <login> "/repos/owner/repo/pulls/<number>" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

# Post a review with inline comments
curl -s -X POST "http://<host>/api/v1/repos/owner/repo/pulls/<number>/reviews" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"COMMENT\",
    \"body\": \"Overall review comment\",
    \"comments\": [
      { \"path\": \"main.py\", \"new_position\": 4,  \"body\": \"Comment on new file line 4\" },
      { \"path\": \"main.py\", \"old_position\": 3, \"body\": \"Comment on a deleted line\" }
    ]
  }"
  • new_position — 文件新版本中的行号（从 1 开始计数）
  • old_position — 文件旧版本中的行号（用于评论已删除的行）
  • event 选项：COMMENT | APPROVE | REQUEST_CHANGES（不能对自己的 PR 使用 REQUEST_CHANGES）
  • extea api -f 不支持嵌套 JSON 数组——创建评审时始终使用 curl
  • 响应中的 original_position 字段始终为 0（Gitea 错误）；请检查响应中的 diff_hunk，确认评论锚定成功

获取评审的行内评论：

extea api -l <login> "/repos/owner/repo/pulls/<number>/reviews/<review-id>/comments"

其他评审操作：

extea pulls approve -l <login> -r owner/repo <number>           # approve
extea pulls reject  -l <login> -r owner/repo <number>           # request changes (not your own PR)
extea api -l <login> "/repos/owner/repo/pulls/<number>/reviews" # list all reviews

图片

问题 / PR 附件

上传文件，并在 Markdown 中嵌入返回的 URL：

# Upload attachment to an issue
curl -s -X POST "http://<host>/api/v1/repos/owner/repo/issues/<number>/assets" \
  -H "Authorization: token $TOKEN" \
  -F "attachment=@/path/to/image.jpg" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['browser_download_url'])"
# Returns: http://<host>/attachments/<uuid>

# Embed in a comment
extea comment -l <login> -r owner/repo <number> "![alt](http://<host>/attachments/<uuid>)"
Wiki 图片

将图片文件直接提交到 wiki git 仓库，与 .md 文件放在一起。在 Markdown 中使用相对路径引用图片——Gitea 会自动解析。

cd /tmp/repo-wiki
cp /path/to/image.jpg ./image.jpg
echo '![caption](image.jpg)' >> Page.md
git add image.jpg Page.md
git commit -m "docs: add image"
git push

图片的访问地址：

http://<host>/owner/repo/wiki/raw/branch/master/<filename>

图片以扁平文件的形式存储在 wiki 仓库中，与 .md 文件位于同一层级，并且不会列为 wiki 页面。请从容易发现的位置（例如 Home.md）链接到包含这些图片的页面。

链接到提交和文件行

这些是嵌入在问题／PR 正文和评论中的 Markdown 链接，并非命令行命令。

提交引用——粘贴短 SHA 或完整 SHA；Gitea 会自动创建链接：

cdc9af8
owner/repo@cdc9af8    ← cross-repo form

文件 + 行号（分支引用）——文件变更后链接位置可能会偏移：

http://<host>/owner/repo/src/branch/main/file.py#L10
http://<host>/owner/repo/src/branch/main/file.py#L10-L15   ← line range

文件 + 行号（提交永久链接）——永久稳定，不会因重构而偏移：

http://<host>/owner/repo/src/commit/<sha>/file.py#L10
http://<host>/owner/repo/src/commit/<sha>/file.py#L10-L15

提交差异页面：

http://<host>/owner/repo/commit/<sha>

提交错误报告时，优先使用提交永久链接形式（/src/commit/<sha>/）——基于分支的链接会在文件移动或重构后失效。

说明

  • extea 会根据 $PWD 中的 Git 远程地址自动检测仓库，但务必显式传入 -l <login> 和 -r owner/repo，以避免歧义。
  • 看板命令需要密码（通过 extea login add 存储在配置中，或使用 GITEA_PASSWORD 环境变量）。标准 tea 命令仅使用 API 令牌。
  • PR 和问题在同一仓库中共用编号序列——打开为 #6 的 PR 可以使用 extea comment ... 6 添加评论。
  • extea milestones close 接受字符串形式的里程碑标题，而非 ID。
  • 对已合并的 PR 执行 extea pulls merge 可能会静默失败——为确保可靠性，请始终使用 API 形式。

评论

支持 Markdown