gitea

Gitea

Gitea 是一项可自托管的 Git 服务。此技能使用 tea CLI（v0.15+）管理 Gitea 资源。所有操作都通过 Bash 执行 tea 命令完成。

重要：执行任何操作之前

运行 bash scripts/check-tea.sh（在技能目录中），或手动验证：

tea --version && tea logins ls

如果未安装 tea，请告知用户安装（macOS 上运行 brew install tea，或参阅 tea 仓库）。需要 v0.15 或更高版本。如果没有登录信息，请引导用户参考 references/authentication.md 完成设置。

上下文检测

在 Git 仓库中时，tea 会根据 Git 远程自动检测 Gitea 实例和仓库。使用以下选项覆盖：

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

务必先检查上下文：

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

输出格式

使用 --output（-o）控制格式：

• json - 最适合以编程方式解析结果
• simple - 精简格式，每行一个值
• table - 易于阅读（默认）
• csv / tsv / yaml - 用于导出数据

在脚本中处理结果时，优先使用 --output json。向用户展示时，优先使用 --output table。

使用说明

问题

列出问题：

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 --kind pulls             # PRs, with issue-list filters
tea issues ls --owner my-org           # issues across an org
tea issues ls --fields "index,title,state,assignees,labels" --output table

创建问题：

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

编辑问题：

tea issues edit 42 --title "New title" --add-labels enhancement --add-assignees user2
tea issues edit 42 --milestone "v2.0" --deadline 2025-12-31
tea issues edit 42 --set-assignees alice,bob   # replace assignees
tea issues edit 42 --remove-assignees bob

关闭 / 重新打开：

tea issues close 42
tea issues reopen 42

评论

tea comment 42 "This is fixed in commit abc123"   # historical shorthand still works
tea comments add 42 --description "Fixed in abc123"
tea comments ls 42
tea comments edit 1001 --description "Updated comment"
tea comments delete 1001

使用 tea comments ls 获取用于编辑 / 删除的评论 ID。

拉取请求

列出 / 查看：

tea pulls ls                           # open PRs
tea pulls ls --state closed --output json
tea pulls 15 --output json             # detail for one PR (not `pulls ls 15`)
tea issues ls --kind pulls --labels "needs-review"   # filter PRs by label

tea pulls ls 没有 --labels 标志。

创建 PR：

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
tea pulls create --title "WIP auth" --base main --head wip-auth --draft

对于基于分叉的 PR，使用 --head username:branch。--draft 会在标题前添加 WIP: （Gitea 会将其视为草稿）。

编辑：

tea pulls edit 15 --title "New title" --add-reviewers alice
tea pulls edit 15 --ready              # strip WIP prefix
tea pulls edit 15 --draft              # mark draft (idempotent)

审查并合并：

tea pulls review 15                    # interactive review
tea pulls approve 15                   # approve (alias: lgtm)
tea pulls reject 15 "Needs tests"      # request changes (reason required)
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"
tea pulls review-comments 15
tea pulls reply 15 1001 "Fixed"
tea pulls resolve 1001
tea pulls unresolve 1001

在本地检出 PR：

tea pulls checkout 15                  # fetches and checks out PR branch
tea pulls checkout 15 --branch         # create local branch if missing (boolean flag)
tea pulls clean 15                     # delete local+remote branches after merge

仓库

列出和搜索：

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

创建 / 编辑：

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 --template owner/template --name new-proj --owner my-org --content --labels
tea repos edit --repo owner/repo --description "Updated" --default-branch main

create-from-template 需要 --template 和 --name。它不支持 create 的 --init / --gitignores 标志。

分叉和克隆：

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

fork 不接受位置参数形式的 slug。多余的参数会被忽略，tea 会改为分叉当前仓库。

删除：

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

--repo 不是删除标志。请使用 --owner 和 --name。--force 会跳过确认提示。

从外部来源迁移：

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

--service 的值只能是以下之一：git、gitea、gitlab、gogs。没有 github 这个值；对于 GitHub，请使用 git。

发布版本

发布版本子命令接受标签名称，而不是数字 ID。

tea releases ls
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
tea releases edit v1.0.0 --title "Patch Release"
tea releases delete v1.0.0 --confirm           # --confirm is required
tea releases assets ls v1.0.0
tea releases assets create v1.0.0 ./path/to/file.zip
tea releases assets delete v1.0.0 file.zip --confirm

删除资源附件时，需提供附件的文件名，而不是数字资源 ID。

标签和里程碑

标签（更新 / 删除时使用 --id，而不是位置索引）：

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

里程碑接受标题，而不是数字 ID：

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

CI/CD 操作

工作流运行：

tea actions runs ls                        # list recent runs
tea actions runs ls --status failure --branch main
tea actions runs view 42                   # view run details
tea actions runs view 42 --jobs
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
tea actions runs delete 42 --confirm       # cancel/delete a run

密钥和变量：

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 --confirm

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

工作流：

tea actions workflows ls
tea actions workflows view ci.yml
tea actions workflows dispatch ci.yml --ref main --input env=prod
tea actions workflows enable ci.yml
tea actions workflows disable ci.yml --confirm

在 dispatch 中，--ref 和 --repo 都使用 -r。务必使用长选项。

组织

别名包括 organizations、organization、org。没有 orgs 这个别名。

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

组织名称是第一个参数。-n / --full-name 表示显示名称，而不是 slug。

Wiki

tea wiki ls
tea wiki view Home
tea wiki revisions Home
tea wiki create --title "Runbook" --content "On-call steps" --message "Add runbook"
tea wiki edit Home --content "Updated home" --message "Refresh home"
tea wiki delete OldPage --confirm

分支

tea branches ls
tea branches protect main
tea branches unprotect old-main
tea branches rename old-name new-name

时间跟踪

tea times ls '#42'                         # quote # so the shell does not treat it as a comment
tea times add 42 2h30m                     # add takes a bare issue index
tea times delete 42 1                      # delete time entry
tea times reset 42                         # reset all tracked time
tea times ls --mine --total                # your times across all repos

通知

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
tea notifications unpin 1

Webhook

创建时 URL 必须作为位置参数传入（创建时没有 --url）。更新时使用 --url。

tea webhooks ls
tea webhooks create 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 --confirm

SSH 密钥

tea ssh-keys ls
tea ssh-keys add ~/.ssh/id_ed25519.pub --title laptop
tea ssh-keys delete 12 --confirm

在浏览器中打开

tea open                    # repo home
tea open 42                 # issue or PR by index
tea open pulls              # also: issues, wiki, settings, labels, milestones

直接访问 API

对于 tea 子命令未覆盖的操作，请使用 tea api：

tea api /repos/{owner}/{repo}                                    # GET (default)
tea api --method PUT /repos/{owner}/{repo}/topics/ci             # add topic
tea api "/repos/{owner}/{repo}/commits?sha=main"                 # list commits (query string, not -f)
tea api --method DELETE /repos/{owner}/{repo}/topics/old-topic   # delete topic
tea api --method POST /repos/{owner}/{repo}/issues/42/comments -d '{"body":"Looks good"}'

-f / --field 是 JSON 请求体字段，并且除非设置了 -X，否则会强制使用 POST。GET 筛选条件请放在 URL 查询字符串中。

{owner} 和 {repo} 会根据 Git 上下文自动替换。完整的 API 参考请查阅 references/workflows.md。

管理操作

tea admin users ls                         # list all users (admin only)
tea admin users create --username bob --email [email protected] --password-stdin
tea admin users edit bob --admin
tea admin users delete bob --confirm

示例

示例 1：错误报告工作流

用户说：“为登录超时问题创建错误报告，并分配给 alice”

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

示例 2：发布版本工作流

用户说：“使用变更日志为 v2.1.0 打标签并发布”

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

示例 3：审查并合并 PR

用户说：“检查 PR 27，如果看起来不错就使用 squash 合并”

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

示例 4：Fork 贡献工作流

用户说：“Fork gitea/docs 仓库，并为我的拼写错误修正创建 PR”

tea repos fork --repo gitea/docs
tea clone yourusername/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 --repo gitea/docs

故障排除

错误：“未配置登录信息”

原因： tea 中未注册 Gitea 实例。 解决方案： 运行 tea logins add，或查看 references/authentication.md，了解包括 token、OAuth 和 SSH 身份验证在内的设置选项。

错误：“找不到仓库”或检测到错误的仓库

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

1. 检查远程地址：git remote -v
2. 明确指定：tea issues ls --repo owner/repo --login mylogin
3. 确认登录 URL 与远程地址匹配：tea logins ls

错误：“401 未授权”或“403 禁止访问”

原因： token 已过期、权限范围不足或登录信息错误。 解决方案：

1. 检查 token 是否有效：tea whoami
2. 在 Gitea 网页界面中使用所需权限范围重新生成 token
3. 更新登录信息：tea logins edit

错误：“连接被拒绝”

原因： 无法访问 Gitea 服务。 解决方案：

1. 验证服务 URL：tea logins ls
2. 检查网络/VPN 连接
3. 对于自签名 TLS：tea logins add --insecure

错误：“没有针对‘orgs’的帮助主题”/“提供了未定义的标志”

原因： 命令格式过时。常见误用：tea orgs（应使用 tea org）、tea pulls ls --labels（应使用 tea issues ls --kind pulls --labels）、tea repos delete --repo（应使用 --owner 和 --name）、tea repos fork owner/repo（应使用 --repo owner/repo）。 解决方案： 重新阅读上方对应章节，或查看 references/tea-commands.md。

命令挂起或返回空结果

原因： API 速率限制或结果集过大。 解决方案： 使用 --limit 和 --page 进行分页：

tea issues ls --limit 10 --page 1

其他参考资料

如需详细信息，请参阅以下随附的参考文件：

• references/authentication.md - 登录设置、token 权限范围、多实例管理、环境变量
• references/tea-commands.md - 每个 tea 子命令的完整标志和选项参考
• references/workflows.md - 高级多步骤工作流、tea api 模式、批量操作