gitea

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gitea (REST API)

Operate Gitea by sending HTTP requests to

$GITEA_URL/api/v1/...

authenticated by

$GITEA_TOKEN

. This skill does NOT depend on any MCP server — every operation is a direct

curl

call.

Keep this entry file small. Load only the reference pack the current turn needs.

通过向

$GITEA_URL/api/v1/...

发送HTTP请求并使用

$GITEA_TOKEN

认证来操作Gitea。本技能不依赖任何MCP服务器——所有操作都是直接的

curl

调用。

保持此入口文件简洁。仅加载当前任务所需的参考包。

Always-On Rules

始终生效的规则

Forced forge routing. Before any forge work, run
```
git remote get-url origin
```
and parse the host. If the host is
```
github.com
```
, this skill does not apply — use
```
gh
```
, including for internal GitHub organizations. For any other host, treat it as a Gitea candidate: derive
```
https://<host>
```
as the probe base URL, run
```
curl -fsS --max-time 5 "https://<host>/api/v1/version"
```
, and use this skill only if HTTP 200 returns JSON with a
```
version
```
field. If the probe fails or times out, ask the user; do not guess another forge.
Resolve
$GITEA_URL
+
$GITEA_TOKEN
from named env pairs, not from the user. Each instance is exported as
```
GITEA_<ALIAS>_URL
```
+
```
GITEA_<ALIAS>_TOKEN
```
(e.g.
```
GITEA_ORGA_URL
```
+
```
GITEA_ORGA_TOKEN
```
). Call
```
gitea_auto
```
(defined in setup.md) to auto-pick the pair whose URL host matches the current repo's
```
origin
```
; falls back to the unaliased
```
GITEA_URL
```
/
```
GITEA_TOKEN
```
, then to gitea-mcp legacy
```
GITEA_HOST
```
/
```
GITEA_ACCESS_TOKEN
```
, then asks the user.
```
$GITEA_URL
```
is always the base URL without the
```
/api
```
suffix.
Send
```
Authorization: token $GITEA_TOKEN
```
on every request. Never put the token in the query string (
```
?token=
```
) — it would be logged.
Prefer
```
curl -s
```
piped to
```
jq
```
so results are easy to inspect. Always include
```
-o /dev/null -w '%{http_code}\n'
```
(or
```
--fail-with-body
```
) when verifying success on write/delete calls — Gitea returns success bodies on 2xx and a
```
{ "message": "...", "url": "..." }
```
error envelope on 4xx/5xx.
Respect destructiveness. Any
```
DELETE
```
against
```
/branches
```
,
```
/contents
```
,
```
/releases
```
,
```
/tags
```
, labels, milestones, packages, secrets, variables, or wiki pages is irreversible. State exactly what will be removed and confirm with the user unless explicitly authorized.
Pagination: most list endpoints take
```
?page=N&limit=M
```
(default
```
page=1
```
,
```
limit=30
```
, server max usually 50). A few older endpoints accept
```
per_page=
```
as an alias. Loop pages until the response is empty or
```
Link: rel="next"
```
is absent.
```
PUT /repos/{owner}/{repo}/contents/{path}
```
(create/update file):
```
content
```
must be base64-encoded. Omit
```
sha
```
to create; pass the current file
```
sha
```
to update.
Endpoint responses are the resource directly — Gitea does not wrap them in
```
{ success, data }
```
. Errors come back with HTTP 4xx/5xx plus
```
{ "message": "...", "url": "..." }
```
.

强制代码托管平台路由。在进行任何代码托管平台操作之前，运行
```
git remote get-url origin
```
并解析主机地址。如果主机是
```
github.com
```
，则本技能不适用——请使用
```
gh
```
工具，包括针对内部GitHub组织的操作。对于其他任何主机，将其视为Gitea候选实例：推导
```
https://<host>
```
作为探测基础URL，运行
```
curl -fsS --max-time 5 "https://<host>/api/v1/version"
```
，仅当返回HTTP 200状态码且响应JSON包含
```
version
```
字段时，才使用本技能。如果探测失败或超时，请询问用户；不要猜测其他代码托管平台。
从命名环境变量对中解析
$GITEA_URL
+
$GITEA_TOKEN
，而非向用户索要。每个实例以
```
GITEA_<ALIAS>_URL
```
+
```
GITEA_<ALIAS>_TOKEN
```
的形式导出（例如
```
GITEA_ORGA_URL
```
+
```
GITEA_ORGA_TOKEN
```
）。调用
```
gitea_auto
```
（定义于setup.md）自动选择URL主机与当前仓库
```
origin
```
匹配的变量对；如果没有匹配项，则回退到未加别名的
```
GITEA_URL
```
/
```
GITEA_TOKEN
```
，再回退到gitea-mcp旧版的
```
GITEA_HOST
```
/
```
GITEA_ACCESS_TOKEN
```
，最后询问用户。
```
$GITEA_URL
```
始终是不带
```
/api
```
后缀的基础URL。
每个请求都要发送
```
Authorization: token $GITEA_TOKEN
```
。绝不要将令牌放在查询字符串中（
```
?token=
```
）——这会被记录下来。
优先使用
```
curl -s
```
管道到
```
jq
```
，以便于检查结果。在验证写入/删除操作是否成功时，始终包含
```
-o /dev/null -w '%{http_code}\n'
```
（或
```
--fail-with-body
```
）——Gitea在2xx状态码时返回成功响应体，在4xx/5xx状态码时返回包含
```
{ "message": "...", "url": "..." }
```
的错误包。
注意破坏性操作。任何针对
```
/branches
```
、
```
/contents
```
、
```
/releases
```
、
```
/tags
```
、标签、里程碑、包、密钥、变量或维基页面的
```
DELETE
```
操作都是不可逆的。除非获得明确授权，否则要准确说明将删除的内容并与用户确认。
分页处理：大多数列表端点支持
```
?page=N&limit=M
```
参数（默认
```
page=1
```
，
```
limit=30
```
，服务器通常最大为50）。少数旧端点接受
```
per_page=
```
作为别名。循环获取页面，直到响应为空或不存在
```
Link: rel="next"
```
头部。
```
PUT /repos/{owner}/{repo}/contents/{path}
```
（创建/更新文件）：
```
content
```
必须经过base64编码。创建时省略
```
sha
```
参数；更新时传入当前文件的
```
sha
```
值。
端点响应直接返回资源——Gitea不会将其包装在
```
{ success, data }
```
中。错误会伴随HTTP 4xx/5xx状态码返回，同时包含
```
{ "message": "...", "url": "..." }
```
。

Core Workflow

核心工作流程

Environment

环境配置

Credentials live in named pairs —

GITEA_<ALIAS>_URL

GITEA_<ALIAS>_TOKEN

— one pair per Gitea instance.

gitea_auto

matches the current repo's

origin

host to one of the URLs and loads that pair into

$GITEA_URL

$GITEA_TOKEN

. Full discovery order and inline helper code: setup.md.

bash

undefined

凭证以命名变量对的形式存在——

GITEA_<ALIAS>_URL

GITEA_<ALIAS>_TOKEN

——每个Gitea实例对应一对。

gitea_auto

会将当前仓库的

origin

主机与其中一个URL匹配，并将对应的变量对加载到

$GITEA_URL

$GITEA_TOKEN

中。完整的发现顺序和内联辅助代码：setup.md。

bash

undefined

Example user-side ~/.bashrc:

用户端~/.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-session bootstrap (define the helpers from setup.md or source them):

会话引导（定义setup.md中的辅助函数或直接引入）：

gitea_list_aliases() { env | grep -oE '^GITEA_[A-Z0-9][A-Z0-9_]URL=' | sed -E 's/^GITEA(.+)URL=$/\1/' | sort -u; } gitea_use() { local a="$1" u="GITEA${1}URL" t="GITEA${1}TOKEN" f="GITEA${1}_TOKEN_FILE" [ -n "${!u:-}" ] || { echo "no $u" >&2; return 1; } if [ -n "${!t:-}" ]; then GITEA_TOKEN="${!t}" elif [ -n "${!f:-}" ] && [ -r "${!f}" ]; then GITEA_TOKEN="$(cat "${!f}")" else echo "no $t or ${t}_FILE" >&2; return 1; fi GITEA_URL="${!u}"; export GITEA_URL GITEA_TOKEN; } gitea_auto() { local src o h a u uh if [ -n "${GITEA_URL:-}" ]; then src="$GITEA_URL" else o=$(git remote get-url origin 2>/dev/null) || o=""; src="$o"; fi case "$src" in git@:) h="${src#git@}"; h="${h%%:}";; ssh://) h="${src#ssh://}"; h="${h#@}"; h="${h%%/}"; h="${h%%:}";; http*://) h="${src#http://}"; h="${h%%/}"; h="${h%%:}";; esac if [ -n "${h:-}" ]; then for a in $(gitea_list_aliases); do u="GITEA_${a}_URL"; uh="${!u#http*://}"; uh="${uh%%/}"; uh="${uh%%:}" [ "$h" = "$uh" ] && { gitea_use "$a"; return 0; } done fi [ -n "${GITEA_URL:-}" ] && [ -n "${GITEA_TOKEN:-}" ] && { export GITEA_URL GITEA_TOKEN; return 0; } [ -n "${GITEA_HOST:-}" ] && [ -n "${GITEA_ACCESS_TOKEN:-}" ] && { GITEA_URL="$GITEA_HOST"; GITEA_TOKEN="$GITEA_ACCESS_TOKEN"; export GITEA_URL GITEA_TOKEN; return 0; } return 1; }

gitea_auto || { echo "no Gitea credentials (set GITEA_<ALIAS>URL + GITEA<ALIAS>_TOKEN, or GITEA_URL + GITEA_TOKEN)" >&2; return 1; }

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


Two usage patterns:

- **Inside a repo**, no env set: `gitea_auto` parses `origin` and finds the alias whose `GITEA_<ALIAS>_URL` host matches.
- **Outside a repo, or targeting a different instance**: `export GITEA_URL=https://git.aaa.com` first, then `gitea_auto` will match `git.aaa.com` against the configured aliases and pull the right token. No need to remember which alias corresponds to which host.

Hard override: `gitea_use ORGA` activates the `ORGA` pair regardless of URL.

gitea_auto || { echo "no Gitea credentials (set GITEA_<ALIAS>URL + GITEA<ALIAS>_TOKEN, or GITEA_URL + GITEA_TOKEN)" >&2; return 1; }

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


两种使用模式：

- **在仓库内**，未设置环境变量：`gitea_auto`解析`origin`并找到`GITEA_<ALIAS>_URL`主机匹配的别名。
- **在仓库外，或针对不同实例**：先执行`export GITEA_URL=https://git.aaa.com`，然后`gitea_auto`会将`git.aaa.com`与配置的别名匹配并获取正确的令牌。无需记住哪个别名对应哪个主机。

强制覆盖：`gitea_use ORGA`会激活`ORGA`对应的变量对，无论URL如何。

gitea

helper

gitea

辅助函数

After resolving env, source the

gitea

wrapper from setup.md. Every

api-*.md

example assumes it is in scope:

bash

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

The helper auto-injects

$GITEA_URL/api/v1

, the auth header, and

Content-Type: application/json

; surfaces HTTP 4xx/5xx with the

{message, url}

envelope on stderr and returns 1; pretty-prints success bodies via

jq

解析完环境变量后，引入setup.md中的

gitea

包装器。每个

api-*.md

示例都假设该函数已在作用域内：

bash

gitea GET    /version                                          # 健康检查
gitea GET    /user                                             # 令牌身份验证
gitea GET   '/repos/foo/bar/issues?state=closed&limit=50'      # 带查询参数的列表查询
gitea POST   /repos/foo/bar/issues   -d '{"title":"x"}'        # 写入操作
gitea DELETE /repos/foo/bar/releases/42                        # 破坏性操作

该辅助函数会自动注入

$GITEA_URL/api/v1

、认证头和

Content-Type: application/json

；在stderr输出HTTP 4xx/5xx状态码对应的

{message, url}

错误包并返回1；通过

jq

格式化打印成功响应体。

Single issue create + comment (canonical write flow)

创建单个议题并添加评论（标准写入流程）

bash

ISSUE=$(gitea POST /repos/{owner}/{repo}/issues \
          -d '{"title":"fix auth bug","body":"Steps to reproduce..."}') || return 1
NUM=$(echo "$ISSUE" | jq -r '.number')

gitea POST "/repos/{owner}/{repo}/issues/$NUM/comments" \
  -d '{"body":"PR will land tomorrow"}'

bash

ISSUE=$(gitea POST /repos/{owner}/{repo}/issues \
          -d '{"title":"fix auth bug","body":"Steps to reproduce..."}') || return 1
NUM=$(echo "$ISSUE" | jq -r '.number')

gitea POST "/repos/{owner}/{repo}/issues/$NUM/comments" \
  -d '{"body":"PR will land tomorrow"}'

Reference Packs

参考包

Load only the pack that covers the task at hand. Each pack lists every endpoint with method, path, key params, and a curl example.

```
references/setup.md
```
Env vars, auth, /api/v1/version probe, PAT scopes, pagination, error envelope, common gotchas.
```
references/api-repo.md
```
— ~23 operations Repos & forks, branches, tags, commits, repo tree, file contents (read / create / update / delete), releases.

references/api-issues-prs.md

— issue + PR endpoints

list/get/create/update issues

, comments, labels-on-issue; PR

list/get/diff/files/status/reviews/create/update/close/merge/update-branch/add-reviewers

; review submit/dismiss.

```
references/api-project.md
```
— labels, milestones, time tracking, wiki Repo & org labels (CRUD), milestones (CRUD), stopwatches + tracked time entries, wiki pages + revisions.

references/api-discovery.md

— users, orgs, search, notifications, version

/user

/user/orgs

/users/search

/orgs/{org}/teams/search

/repos/search

/repos/issues/search

, notifications list/get/mark-read,

/version

```
references/api-cicd.md
```
— actions & packages Workflows + runs + jobs + logs, dispatch/cancel/rerun runs, repo/org Actions secrets + variables CRUD, packages list/versions/get/delete.

仅加载与当前任务相关的参考包。每个包都列出了所有端点的方法、路径、关键参数和curl示例。

```
references/setup.md
```
环境变量、认证、/api/v1/version探测、PAT权限范围、分页、错误包、常见注意事项。
```
references/api-repo.md
```
— 约23项操作 仓库与复刻、分支、标签、提交、仓库目录、文件内容（读取/创建/更新/删除）、发布版本。
```
references/api-issues-prs.md
```
— 议题 + PR端点 议题的列表/获取/创建/更新、评论、议题标签；PR的列表/获取/差异/文件/状态/评审/创建/更新/关闭/合并/更新分支/添加评审人；评审提交/驳回。
```
references/api-project.md
```
— 标签、里程碑、时间跟踪、维基 仓库与组织标签（增删改查）、里程碑（增删改查）、计时器 + 跟踪时间条目、维基页面 + 修订版本。

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密钥 + 变量增删改查、包列表/版本/获取/删除。

Quick Routing

快速路由指引

Connection refused, 401, 403, missing token, PAT scopes:
```
references/setup.md
```
.
Clone / fork / create repo, read or commit a file, branch / tag, release:
```
references/api-repo.md
```
.
File issues, comment, manage PRs, request/submit reviews, merge:
```
references/api-issues-prs.md
```
.
Labels, milestones, time tracking, wiki pages:
```
references/api-project.md
```
.
"Who am I", search repos/users/issues, org list, notifications:
```
references/api-discovery.md
```
.
CI runs/workflows, secrets/variables, packages:
```
references/api-cicd.md
```
.

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

When to Use Another Forge

何时使用其他代码托管平台工具

```
git remote get-url origin
```
host is
```
github.com
```
-> use
```
gh
```
instead; this skill does not apply.
```
/api/v1/version
```
probe fails -> the host is probably not a Gitea instance. Ask the user; do not guess another forge.

```
git remote get-url origin
```
的主机是
```
github.com
```
-> 改用
```
gh
```
工具；本技能不适用。
```
/api/v1/version
```
探测失败 -> 该主机可能不是Gitea实例。请询问用户；不要猜测其他代码托管平台。

gitea

Original

Translation

Gitea (REST API)

Gitea (REST API)

Always-On Rules

始终生效的规则

Core Workflow

核心工作流程

Environment

环境配置

Example user-side ~/.bashrc:

用户端~/.bashrc示例：

export GITEA_ORGA_URL=https://git.orga.com GITEA_ORGA_TOKEN=...

export GITEA_ORGA_URL=https://git.orga.com GITEA_ORGA_TOKEN=...

export GITEA_ORGB_URL=https://git.orgb.local GITEA_ORGB_TOKEN=...

export GITEA_ORGB_URL=https://git.orgb.local GITEA_ORGB_TOKEN=...

export GITEA_URL=https://gitea.com GITEA_TOKEN=...

export GITEA_URL=https://gitea.com GITEA_TOKEN=...

Per-session bootstrap (define the helpers from setup.md or source them):

会话引导（定义setup.md中的辅助函数或直接引入）：

`gitea`
helper

`gitea`
辅助函数

Single issue create + comment (canonical write flow)

创建单个议题并添加评论（标准写入流程）

Reference Packs

参考包

Quick Routing

快速路由指引

When to Use Another Forge

何时使用其他代码托管平台工具

gitea

Original

Translation

Gitea (REST API)

Gitea (REST API)

Always-On Rules

始终生效的规则

Core Workflow

核心工作流程

Environment

环境配置

Example user-side ~/.bashrc:

用户端~/.bashrc示例：

export GITEA_ORGA_URL=https://git.orga.com GITEA_ORGA_TOKEN=...

export GITEA_ORGA_URL=https://git.orga.com GITEA_ORGA_TOKEN=...

export GITEA_ORGB_URL=https://git.orgb.local GITEA_ORGB_TOKEN=...

export GITEA_ORGB_URL=https://git.orgb.local GITEA_ORGB_TOKEN=...

export GITEA_URL=https://gitea.com GITEA_TOKEN=...

export GITEA_URL=https://gitea.com GITEA_TOKEN=...

Per-session bootstrap (define the helpers from setup.md or source them):

会话引导（定义setup.md中的辅助函数或直接引入）：

gitea helper

gitea辅助函数

Single issue create + comment (canonical write flow)

创建单个议题并添加评论（标准写入流程）

Reference Packs

参考包

Quick Routing

快速路由指引

When to Use Another Forge

何时使用其他代码托管平台工具

`gitea`
helper

`gitea`
辅助函数