gitea

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gitea

Gitea is a self-hosted Git service. This skill uses the

tea

CLI to manage Gitea resources programmatically. All operations go through

tea

commands executed via Bash.

Gitea是一款自托管Git服务。本技能使用

tea

CLI以编程方式管理Gitea资源。所有操作均通过Bash执行

tea

命令完成。

Important: Before Any Operation

重要提示：操作前须知

Run

bash scripts/check-tea.sh

(from the skill directory) or manually verify:

bash

tea --version && tea logins ls

tea

is not installed, tell the user to install it (

brew install tea

on macOS, or see the tea repo). If no logins exist, guide them through

references/authentication.md

运行

bash scripts/check-tea.sh

（从技能目录执行）或手动验证：

bash

tea --version && tea logins ls

如果未安装

tea

，请告知用户进行安装（macOS系统使用

brew install tea

，或查看tea仓库获取安装方式）。如果没有已配置的登录信息，请引导用户查看

references/authentication.md

文档。

Context Detection

上下文检测

When inside a git repository,

tea

auto-detects the Gitea instance and repo from git remotes. Override with:

```
--repo owner/repo
```
to target a specific repository
```
--login name
```
to use a specific Gitea login
```
--remote name
```
to use a specific git remote

Always check context first:

bash

git remote -v 2>/dev/null
tea logins ls --output simple

当处于Git仓库目录中时，

tea

会自动从Git远程仓库信息中检测Gitea实例和仓库。可通过以下方式覆盖自动检测：

```
--repo owner/repo
```
：指定目标仓库
```
--login name
```
：使用特定的Gitea登录信息
```
--remote name
```
：使用特定的Git远程仓库

请始终先检查上下文：

bash

git remote -v 2>/dev/null
tea logins ls --output simple

Output Formatting

输出格式设置

Use

--output

(

-o

) to control format:

```
json
```
- best for parsing results programmatically
```
simple
```
- compact, one value per line
```
table
```
- human-readable (default)
```
csv
```
/
```
tsv
```
/
```
yaml
```
- for data export

When processing results in scripts, prefer

--output json

. When displaying to users, prefer

--output table

使用

--output

（缩写

-o

）控制输出格式：

```
json
```
：最适合以编程方式解析结果
```
simple
```
：紧凑格式，每行一个值
```
table
```
：适合人类阅读（默认格式）
```
csv
```
/
```
tsv
```
/
```
yaml
```
：用于数据导出

在脚本中处理结果时，优先使用

--output json

。向用户展示结果时，优先使用

--output table

。

Instructions

操作指南

Issues

议题管理

List issues:

bash

tea issues ls                          # open issues in current repo
tea issues ls --state closed           # closed issues
tea issues ls --labels bug,urgent      # filter by labels
tea issues ls --assignee username      # filter by assignee
tea issues ls --milestones "v1.0"      # filter by milestone
tea issues ls --keyword "search term"  # search by keyword
tea issues ls --fields "index,title,state,assignees,labels" --output table

Create an issue:

bash

tea issues create --title "Bug: login fails" --description "Steps to reproduce..." --labels bug --assignees user1,user2

Edit issues:

bash

tea issues edit 42 --title "New title" --add-labels enhancement --add-assignees user2
tea issues edit 42 --milestone "v2.0" --deadline 2025-12-31

Close / reopen:

bash

tea issues close 42
tea issues reopen 42

Add a comment:

bash

tea comment 42 "This is fixed in commit abc123"

列出议题：

bash

tea issues ls                          # 当前仓库中的开放议题
tea issues ls --state closed           # 已关闭的议题
tea issues ls --labels bug,urgent      # 按标签筛选
tea issues ls --assignee username      # 按经办人筛选
tea issues ls --milestones "v1.0"      # 按里程碑筛选
tea issues ls --keyword "search term"  # 按关键词搜索
tea issues ls --fields "index,title,state,assignees,labels" --output table

创建议题：

bash

tea issues create --title "Bug: login fails" --description "Steps to reproduce..." --labels bug --assignees user1,user2

编辑议题：

bash

tea issues edit 42 --title "New title" --add-labels enhancement --add-assignees user2
tea issues edit 42 --milestone "v2.0" --deadline 2025-12-31

关闭/重新打开议题：

bash

tea issues close 42
tea issues reopen 42

添加评论：

bash

tea comment 42 "This is fixed in commit abc123"

Pull Requests

拉取请求管理

List PRs:

bash

tea pulls ls                           # open PRs
tea pulls ls --state closed --output json
tea pulls ls --labels "needs-review"

Create a PR:

bash

tea pulls create --title "Add auth module" --description "Implements OAuth2 flow" --base main --head feature-branch
tea pulls create --title "Fix #42" --base main --head fix-login --labels bugfix --assignees reviewer1

For fork-based PRs, use

--head username:branch

Review and merge:

bash

tea pulls review 15                    # interactive review
tea pulls approve 15                   # approve (alias: lgtm)
tea pulls reject 15                    # request changes
tea pulls merge 15 --style squash      # merge (styles: merge, rebase, squash, rebase-merge)
tea pulls merge 15 --style squash --title "feat: auth module (#15)" --message "Implements OAuth2"

Checkout a PR locally:

bash

tea pulls checkout 15                  # fetches and checks out PR branch
tea pulls clean 15                     # delete local+remote branches after merge

列出拉取请求：

bash

tea pulls ls                           # 开放的拉取请求
tea pulls ls --state closed --output json
tea pulls ls --labels "needs-review"

创建拉取请求：

bash

tea pulls create --title "Add auth module" --description "Implements OAuth2 flow" --base main --head feature-branch
tea pulls create --title "Fix #42" --base main --head fix-login --labels bugfix --assignees reviewer1

针对基于复刻仓库的拉取请求，使用

--head username:branch

。

审核与合并：

bash

tea pulls review 15                    # 交互式审核
tea pulls approve 15                   # 批准（别名：lgtm）
tea pulls reject 15                    # 请求修改
tea pulls merge 15 --style squash      # 合并（合并方式：merge、rebase、squash、rebase-merge）
tea pulls merge 15 --style squash --title "feat: auth module (#15)" --message "Implements OAuth2"

在本地检出拉取请求：

bash

tea pulls checkout 15                  # 获取并检出拉取请求分支
tea pulls clean 15                     # 合并后删除本地和远程分支

Repositories

仓库管理

List and search:

bash

tea repos ls                           # your repos on default login
tea repos search "keyword"             # search across instance
tea repos search "keyword" --owner org # search within org
tea repos ls --output json --limit 50

Create:

bash

tea repos create --name my-project --description "A new project" --init --gitignores Go --license MIT
tea repos create --name team-project --owner my-org --private
tea repos create-from-template --name new-proj --owner my-org   # from template repo

Fork and clone:

bash

tea repos fork owner/repo
tea repos fork owner/repo --owner my-org    # fork to org
tea clone owner/repo                        # clone (auto-detects login)

Delete:

bash

tea repos delete --repo owner/repo          # destructive - confirm with user first

Migrate from external source:

bash

tea repos migrate --name imported-repo --clone-url https://github.com/user/repo.git --service github --mirror

列出与搜索仓库：

bash

tea repos ls                           # 默认登录账号下的仓库
tea repos search "keyword"             # 在实例中搜索仓库
tea repos search "keyword" --owner org # 在指定组织内搜索
tea repos ls --output json --limit 50

创建仓库：

bash

tea repos create --name my-project --description "A new project" --init --gitignores Go --license MIT
tea repos create --name team-project --owner my-org --private
tea repos create-from-template --name new-proj --owner my-org   # 基于模板仓库创建

复刻与克隆仓库：

bash

tea repos fork owner/repo
tea repos fork owner/repo --owner my-org    # 复刻到指定组织
tea clone owner/repo                        # 克隆仓库（自动检测登录信息）

删除仓库：

bash

tea repos delete --repo owner/repo          # 破坏性操作 - 请先确认用户意图

从外部源迁移仓库：

bash

tea repos migrate --name imported-repo --clone-url https://github.com/user/repo.git --service github --mirror

Releases

版本发布管理

List releases:

bash

tea releases ls

Create a release:

bash

tea releases create --tag v1.0.0 --title "Release 1.0.0" --note "Release notes here" --target main
tea releases create --tag v1.0.0 --title "v1.0.0" --note-file CHANGELOG.md --asset ./dist/binary.tar.gz
tea releases create --tag v2.0.0-rc1 --prerelease --draft

Edit / delete:

bash

tea releases edit 1 --tag v1.0.1 --title "Patch Release"
tea releases delete 1                      # destructive - confirm first

Release assets:

bash

tea releases assets ls 1
tea releases assets create 1 ./path/to/file.zip
tea releases assets delete 1 asset-id

列出版本发布：

bash

tea releases ls

创建版本发布：

bash

tea releases create --tag v1.0.0 --title "Release 1.0.0" --note "Release notes here" --target main
tea releases create --tag v1.0.0 --title "v1.0.0" --note-file CHANGELOG.md --asset ./dist/binary.tar.gz
tea releases create --tag v2.0.0-rc1 --prerelease --draft

编辑/删除版本发布：

bash

tea releases edit 1 --tag v1.0.1 --title "Patch Release"
tea releases delete 1                      # 破坏性操作 - 请先确认

版本发布资产管理：

bash

tea releases assets ls 1
tea releases assets create 1 ./path/to/file.zip
tea releases assets delete 1 asset-id

Labels and Milestones

标签与里程碑管理

Labels:

bash

tea labels ls
tea labels create --name "priority:high" --color "#ff0000" --description "High priority"
tea labels update 5 --name "priority:critical" --color "#990000"
tea labels delete 5

Milestones:

bash

tea milestones ls
tea milestones create --title "v2.0" --description "Major release" --deadline 2025-06-01
tea milestones close 3
tea milestones issues 3                    # list issues in milestone

标签：

bash

tea labels ls
tea labels create --name "priority:high" --color "#ff0000" --description "High priority"
tea labels update 5 --name "priority:critical" --color "#990000"
tea labels delete 5

里程碑：

bash

tea milestones ls
tea milestones create --title "v2.0" --description "Major release" --deadline 2025-06-01
tea milestones close 3
tea milestones issues 3                    # 列出里程碑下的议题

CI/CD Actions

CI/CD操作

Workflow runs:

bash

tea actions runs ls                        # list recent runs
tea actions runs view 42                   # view run details
tea actions runs logs 42                   # view run logs
tea actions runs logs 42 --job 1           # specific job logs
tea actions runs logs 42 --follow          # stream logs in real time

Secrets and variables:

bash

tea actions secrets ls
tea actions secrets create SECRET_NAME secret_value
tea actions secrets create DB_PASSWORD --file ./secret.txt
tea actions secrets delete SECRET_NAME

tea actions variables ls
tea actions variables set VAR_NAME var_value
tea actions variables delete VAR_NAME

Workflows:

bash

tea actions workflows ls

工作流运行：

bash

tea actions runs ls                        # 列出最近的运行记录
tea actions runs view 42                   # 查看运行详情
tea actions runs logs 42                   # 查看运行日志
tea actions runs logs 42 --job 1           # 查看指定任务的日志
tea actions runs logs 42 --follow          # 实时流式查看日志

密钥与变量：

bash

tea actions secrets ls
tea actions secrets create SECRET_NAME secret_value
tea actions secrets create DB_PASSWORD --file ./secret.txt
tea actions secrets delete SECRET_NAME

tea actions variables ls
tea actions variables set VAR_NAME var_value
tea actions variables delete VAR_NAME

工作流：

bash

tea actions workflows ls

Organizations

组织管理

bash

tea orgs ls
tea orgs create --name my-org --description "My organization" --visibility public
tea orgs delete my-org                     # destructive - confirm first

bash

tea orgs ls
tea orgs create --name my-org --description "My organization" --visibility public
tea orgs delete my-org                     # 破坏性操作 - 请先确认

Time Tracking

时间跟踪

bash

tea times ls 42                            # time tracked on issue 42
tea times add 42 "2h30m"                   # log 2h30m on issue 42
tea times delete 42 1                      # delete time entry
tea times reset 42                         # reset all tracked time

bash

tea times ls 42                            # 查看议题42的跟踪时间
tea times add 42 "2h30m"                   # 为议题42记录2小时30分钟
tea times delete 42 1                      # 删除时间条目
tea times reset 42                         # 重置所有跟踪时间

Notifications

通知管理

bash

tea notifications ls                       # unread + pinned
tea notifications ls --mine --states unread # across all repos
tea notifications read 1                   # mark as read
tea notifications unread 1                 # mark as unread
tea notifications pin 1                    # pin notification

bash

tea notifications ls                       # 未读与已固定的通知
tea notifications ls --mine --states unread # 所有仓库中的未读通知
tea notifications read 1                   # 标记为已读
tea notifications unread 1                 # 标记为未读
tea notifications pin 1                    # 固定通知

Webhooks

Webhook管理

bash

tea webhooks ls
tea webhooks create --url https://example.com/hook --events push,pull_request --secret mysecret
tea webhooks update 1 --url https://new-url.com --events push
tea webhooks delete 1

bash

tea webhooks ls
tea webhooks create --url https://example.com/hook --events push,pull_request --secret mysecret
tea webhooks update 1 --url https://new-url.com --events push
tea webhooks delete 1

Direct API Access

直接API访问

For operations not covered by tea subcommands, use

tea api

bash

tea api /repos/{owner}/{repo}                                    # GET (default)
tea api --method POST /repos/{owner}/{repo}/topics -f topic=ci   # add topic
tea api /repos/{owner}/{repo}/commits --field sha=main           # list commits
tea api --method DELETE /repos/{owner}/{repo}/topics/old-topic   # delete topic

{owner}

and

{repo}

are auto-replaced from git context. For full API reference, consult

references/workflows.md

对于

tea

子命令未覆盖的操作，使用

tea api

：

bash

tea api /repos/{owner}/{repo}                                    # GET请求（默认）
tea api --method POST /repos/{owner}/{repo}/topics -f topic=ci   # 添加主题
tea api /repos/{owner}/{repo}/commits --field sha=main           # 列出提交记录
tea api --method DELETE /repos/{owner}/{repo}/topics/old-topic   # 删除主题

{owner}

和

{repo}

会自动从Git上下文替换。如需完整API参考，请查阅

references/workflows.md

。

Admin Operations

管理员操作

bash

tea admin users ls                         # list all users (admin only)

bash

tea admin users ls                         # 列出所有用户（仅管理员可用）

Examples

示例

Example 1: Bug report workflow

示例1：Bug报告流程

User says: "Create a bug report for the login timeout issue and assign it to alice"

bash

tea issues create --title "Bug: Login times out after 30s on slow connections" \
  --description "## Steps to reproduce\n1. Connect via slow network\n2. Attempt login\n3. Observe timeout after 30s\n\n## Expected\nGraceful retry or extended timeout\n\n## Actual\nConnection dropped with no error message" \
  --labels bug \
  --assignees alice

用户需求："为登录超时问题创建Bug报告并分配给alice"

bash

tea issues create --title "Bug: Login times out after 30s on slow connections" \
  --description "## 复现步骤\n1. 通过慢速网络连接\n2. 尝试登录\n3. 观察30秒后超时\n\n## 预期结果\n优雅重试或延长超时时间\n\n## 实际结果\n连接断开且无错误提示" \
  --labels bug \
  --assignees alice

Example 2: Release workflow

示例2：版本发布流程

User says: "Tag and release v2.1.0 with the changelog"

bash

tea releases create --tag v2.1.0 --title "v2.1.0" --note-file CHANGELOG.md --target main

用户需求："标记并发布v2.1.0版本，附带变更日志"

bash

tea releases create --tag v2.1.0 --title "v2.1.0" --note-file CHANGELOG.md --target main

Example 3: PR review and merge

示例3：拉取请求审核与合并

User says: "Check PR 27 and squash merge it if it looks good"

bash

tea pulls ls 27 --output json              # inspect PR details
tea pulls approve 27                       # approve
tea pulls merge 27 --style squash          # squash merge

用户需求："检查PR 27，如果没问题就压缩合并"

bash

tea pulls ls 27 --output json              # 检查PR详情
tea pulls approve 27                       # 批准PR
tea pulls merge 27 --style squash          # 压缩合并

Example 4: Fork contribution workflow

示例4：复刻贡献流程

User says: "Fork the gitea/docs repo and create a PR for my typo fix"

bash

tea repos fork gitea/docs
tea clone gitea/docs
cd docs
git checkout -b fix-typo

用户需求："复刻gitea/docs仓库并为我的错别字修复创建PR"

bash

tea repos fork gitea/docs
tea clone gitea/docs
cd docs
git checkout -b fix-typo

... user makes changes ...

... 用户进行修改 ...

git add -A && git commit -m "Fix typo in installation guide" git push origin fix-typo tea pulls create --title "Fix typo in installation guide" --base main --head yourusername:fix-typo

undefined

git add -A && git commit -m "Fix typo in installation guide" git push origin fix-typo tea pulls create --title "Fix typo in installation guide" --base main --head yourusername:fix-typo

undefined

Troubleshooting

故障排除

Error: "No login configured"

错误："No login configured"

Cause: No Gitea instance registered with tea. Solution: Run

tea logins add

or see

references/authentication.md

for setup options including token, OAuth, and SSH authentication.

原因： 未向tea注册Gitea实例。 解决方案： 运行

tea logins add

，或查看

references/authentication.md

获取包括令牌、OAuth和SSH认证在内的设置选项。

Error: "Repository not found" or wrong repo detected

错误："Repository not found"或检测到错误仓库

Cause: Git remote doesn't point to a known Gitea login, or repo slug is wrong. Solution:

Check remotes:
```
git remote -v
```

Specify explicitly:

tea issues ls --repo owner/repo --login mylogin

Verify login URL matches remote:
```
tea logins ls
```

原因： Git远程仓库未指向已知的Gitea登录信息，或仓库标识错误。 解决方案：

检查远程仓库：
```
git remote -v
```

明确指定：

tea issues ls --repo owner/repo --login mylogin

验证登录URL与远程仓库匹配：
```
tea logins ls
```

Error: "401 Unauthorized" or "403 Forbidden"

错误："401 Unauthorized"或"403 Forbidden"

Cause: Token expired, insufficient scopes, or wrong login. Solution:

Check token validity:
```
tea whoami
```
Regenerate token with required scopes in Gitea web UI
Update login:
```
tea logins edit
```

原因： 令牌过期、权限不足或登录信息错误。 解决方案：

检查令牌有效性：
```
tea whoami
```
在Gitea网页UI中重新生成具有所需权限的令牌
更新登录信息：
```
tea logins edit
```

Error: "Connection refused"

错误："Connection refused"

Cause: Gitea server unreachable. Solution:

Verify server URL:
```
tea logins ls
```
Check network/VPN connectivity
For self-signed TLS:
```
tea logins add --insecure
```

原因： 无法连接到Gitea服务器。 解决方案：

验证服务器URL：
```
tea logins ls
```
检查网络/VPN连接
对于自签名TLS证书：
```
tea logins add --insecure
```

Commands hang or return empty

命令挂起或返回空结果

Cause: API rate limiting or large result sets. Solution: Use

--limit

and

--page

for pagination:

bash

tea issues ls --limit 10 --page 1

原因： API速率限制或结果集过大。 解决方案： 使用

--limit

和

--page

进行分页：

bash

tea issues ls --limit 10 --page 1

Additional References

额外参考

For detailed information, consult these bundled reference files:

```
references/authentication.md
```
- Login setup, token scopes, multi-instance management, environment variables
```
references/tea-commands.md
```
- Complete flag and option reference for every tea subcommand
```
references/workflows.md
```
- Advanced multi-step workflows, tea api patterns, bulk operations

如需详细信息，请查阅以下附带的参考文档：

```
references/authentication.md
```
- 登录设置、令牌权限、多实例管理、环境变量
```
references/tea-commands.md
```
- 所有tea子命令的完整参数和选项参考
```
references/workflows.md
```
- 高级多步骤流程、tea api模式、批量操作