gitea

Gitea（REST API）

通过向 $GITEA_URL/api/v1/... 发送 HTTP 请求来操作 Gitea，并使用 $GITEA_TOKEN 进行身份验证。这项技能不依赖任何 MCP 服务——所有操作都是直接调用 curl。

保持此入口文件简短。仅加载当前轮次所需的参考资料包。

始终适用的规则

0. 强制路由到相应代码托管平台。 执行任何代码托管平台操作前，先运行 git remote get-url origin 并解析主机名。如果主机名是 github.com，则此技能不适用——请使用 gh，包括用于内部 GitHub 组织。对于其他主机名，将 https://<host> 作为探测基础 URL，运行 curl -fsS --max-time 5 "https://<host>/api/v1/version"；仅当 HTTP 200 返回包含 version 字段的 JSON 时，才使用此技能。如果探测失败或超时，请询问用户；不要猜测其他代码托管平台。
1. 从命名环境变量对中解析 $GITEA_URL 和 $GITEA_TOKEN，不要向用户询问。 加载 scripts/gitea.sh，然后调用 gitea_auto，选择 URL 与当前仓库 origin 匹配的变量对；如果没有匹配项，则依次回退到未命名空间的 GITEA_URL/GITEA_TOKEN、旧版 GITEA_HOST/GITEA_ACCESS_TOKEN，最后再询问用户。$GITEA_URL 始终是基础 URL，不包含 /api 后缀。
2. 每次请求都发送 Authorization: token $GITEA_TOKEN。切勿将令牌放入查询字符串（?token=）——这会被记录到日志中。优先使用 gitea / gitea_json：它们通过文件描述符传递请求头，因此令牌不会出现在进程列表中；原始 curl "${AUTH[@]}" 示例会通过 ps 将令牌暴露给其他本地用户。
3. 优先使用 curl -s 并通过管道传给 jq，以便轻松检查结果。验证写入或删除操作是否成功时，始终包含 -o /dev/null -w '%{http_code}\n'（或 --fail-with-body）——Gitea 在 2xx 响应中会返回成功响应正文，在 4xx/5xx 响应中会返回 { "message": "...", "url": "..." } 错误信封。
4. 切勿将用户输入或自由格式文本插入内嵌 JSON。 使用 jq -n 构造请求正文并写入 mktemp 文件，然后调用 gitea_json METHOD PATH FILE；该命令会验证 JSON，并使用 --data-binary @file 发送。固定且可信的字面量请求正文可以使用 -d。
5. 谨慎处理破坏性操作。 对 /branches、/contents、/releases、/tags、标签、里程碑、软件包、机密、变量或 Wiki 页面执行任何 DELETE 都是不可逆的。请明确说明将删除的内容，并征得用户确认，除非用户已明确授权。
6. 分页： 大多数列表端点接受 ?page=N&limit=M（默认 page=1、limit=30，服务器上限通常为 50）。少数旧版端点接受 per_page= 作为别名。持续遍历页面，直到响应为空，或不存在 Link: rel="next"。
7. PUT /repos/{owner}/{repo}/contents/{path}（创建或更新文件）：content 必须经过 base64 编码。创建时省略 sha；更新时传入当前文件的 sha。
8. 端点直接返回资源——Gitea 不会将响应包装在 { success, data } 中。错误响应会附带 HTTP 4xx/5xx 状态码以及 { "message": "...", "url": "..." }。

核心工作流

环境

凭据以命名对的形式保存——GITEA_<ALIAS>_URL + GITEA_<ALIAS>_TOKEN——每个 Gitea 实例对应一对。gitea_auto 会将当前仓库的 origin 主机与其中一个 URL 匹配，并将该对凭据加载到 $GITEA_URL + $GITEA_TOKEN。完整的发现顺序和辅助代码见：setup.md。

# Example user-side ~/.bashrc:
#   export GITEA_ORGA_URL=https://git.orga.com    GITEA_ORGA_TOKEN=...
#   export GITEA_ORGB_URL=https://git.orgb.local  GITEA_ORGB_TOKEN=...
#   export GITEA_URL=https://gitea.com            GITEA_TOKEN=...

# Per-shell bootstrap; replace <gitea-skill> with this skill's directory:
source <gitea-skill>/scripts/gitea.sh
gitea_auto || { echo "no Gitea credentials (set GITEA_<ALIAS>_URL + GITEA_<ALIAS>_TOKEN, or GITEA_URL + GITEA_TOKEN)" >&2; exit 1; }

AUTH=(-H "Authorization: token $GITEA_TOKEN")
JSON=(-H 'Content-Type: application/json')

环境变量约定：

• GITEA_<ALIAS>_URL + GITEA_<ALIAS>_TOKEN——每个实例对应一对命名凭据。<ALIAS> 由大写字母、数字和下划线组成；未导出 _TOKEN 时，也可使用 GITEA_<ALIAS>_TOKEN_FILE。
• GITEA_URL + GITEA_TOKEN——未命名的单实例回退配置。$GITEA_URL 是不带 /api 后缀的基础 URL。
• GITEA_HOST + GITEA_ACCESS_TOKEN——gitea-mcp 的旧版回退配置。

辅助函数（gitea_list_aliases、gitea_use、gitea_auto、gitea 和 gitea_json）仅定义在 scripts/gitea.sh 中；每次启动新的 shell 时都要 source 该文件。对于 SSH 远程地址，无法确定 HTTPS 端口。如果多个别名的主机相同但端口不同，gitea_auto 会安全地失败，并要求使用 gitea_use <ALIAS>。

简单的单实例场景（仅导出了 GITEA_URL + GITEA_TOKEN）：完全跳过辅助函数，直接调用 curl：

curl -s -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user" | jq

两种使用方式：

• 在仓库内，未设置环境变量：gitea_auto 会解析 origin，并找到 GITEA_<ALIAS>_URL 主机与之匹配的别名。
• 在仓库外，或要指定其他实例：先执行 export GITEA_URL=https://git.aaa.com，然后 gitea_auto 会将 git.aaa.com 与已配置的别名进行匹配，并加载对应的令牌。无需记住每个主机对应哪个别名。

强制覆盖：gitea_use ORGA 会激活 ORGA 凭据对，无论 URL 是什么。

gitea 辅助函数

解析环境变量后，已 source 的脚本会提供 gitea 和 gitea_json。所有 api-*.md 示例都假定这些函数已在作用域内：

gitea GET    /version                                          # health
gitea GET    /user                                             # token identity
gitea GET   '/repos/foo/bar/issues?state=closed&limit=50'      # list with query
gitea POST   /repos/foo/bar/issues   -d '{"title":"x"}'        # write
gitea DELETE /repos/foo/bar/releases/42                        # destructive

该辅助函数会自动注入 $GITEA_URL/api/v1、身份验证标头和 Content-Type: application/json；会在 stderr 上显示 curl 传输错误和 HTTP 4xx/5xx 错误（使用 {message, url} 信封），并返回 1； 成功时会通过 jq 美化输出响应正文。

创建单个 issue 并发表评论（规范写入流程）

BODY_FILE=$(mktemp)
trap 'rm -f "$BODY_FILE"' EXIT
jq -n --arg title "$TITLE" --arg body "$BODY" \
  '{title: $title, body: $body}' > "$BODY_FILE"
ISSUE=$(gitea_json POST /repos/{owner}/{repo}/issues "$BODY_FILE") || exit 1
NUM=$(echo "$ISSUE" | jq -r '.number')

jq -n --arg body "$COMMENT" '{body: $body}' > "$BODY_FILE"
gitea_json POST "/repos/{owner}/{repo}/issues/$NUM/comments" "$BODY_FILE"

参考资料包

只加载与当前任务相关的资料包。每个资料包都会列出所有端点及其方法、路径、关键参数和 curl 示例。

• references/setup.md 环境变量、身份验证、/api/v1/version 探测、PAT 权限范围、分页、错误信封、常见问题。
• references/api-repo.md — 约 23 项操作 仓库与 fork、分支、标签、提交、仓库树、文件内容（读取 / 创建 / 更新 / 删除）、发布。
• references/api-issues-prs.md — issue + PR 端点 list/get/create/update issues、评论、issue 标签；PR list/get/diff/files/status/reviews/create/update/close/merge/update-branch/add-reviewers；提交 / 撤销评审。
• references/api-project.md — 标签、里程碑、时间跟踪、wiki 仓库与组织标签（CRUD）、里程碑（CRUD）、秒表 + 已跟踪时间条目、wiki 页面 + 修订版本。
• references/api-discovery.md — 用户、组织、搜索、通知、版本 /user、/user/orgs、/users/search、/orgs/{org}/teams/search、/repos/search、/repos/issues/search、通知列表 / 获取 / 标记为已读、/version。
• references/api-cicd.md — Actions 与软件包 工作流 + 运行 + 作业 + 日志、触发 / 取消 / 重新运行任务、仓库 / 组织 Actions 密钥 + 变量 CRUD、软件包列表 / 版本 / 获取 / 删除。

快速路由

• 连接被拒绝、401、403、缺少令牌、PAT 权限范围：references/setup.md。
• 克隆 / 派生 / 创建仓库，读取或提交文件，分支 / 标签，发布版本：references/api-repo.md。
• 创建议题、发表评论、管理 PR、请求 / 提交审查、合并：references/api-issues-prs.md。
• 标签、里程碑、时间跟踪、Wiki 页面：references/api-project.md。
• “我是谁”、搜索仓库 / 用户 / 议题、组织列表、通知：references/api-discovery.md。
• CI 运行 / 工作流、机密 / 变量、软件包：references/api-cicd.md。

提醒（规则 0）：github.com -> 使用 gh；/api/v1/version 探测失败 -> 询问用户，不要猜测其他 Forge。