gitea

Gitea

Gitea はセルフホスト可能な Git サービスです。このスキルでは、Gitea のリソースを管理するために tea CLI（v0.15 以降）を使用します。すべての操作は、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 - 1 行に 1 つの値を表示する簡潔な形式です
• table - 人が読みやすい形式です（デフォルト）
• csv / tsv / yaml - データのエクスポートに使用します

スクリプトで結果を処理する場合は、--output json を優先してください。ユーザーに表示する場合は、--output table を優先してください。

手順

Issues

Issue の一覧表示：

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

Issue の作成：

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

Issue の編集：

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

編集または削除するコメントの ID を取得するには、tea comments ls を使用します。

Pull Request

一覧表示／詳細確認：

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 は位置引数のスラッグを受け取りません。余分な引数は無視され、代わりに現在のリポジトリがフォークされます。

削除：

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 はスラッグではなく表示名を指定します。

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 を確認して、問題がなければスカッシュマージしてください」

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

例 4：フォークを使ったコントリビューションのワークフロー

ユーザー：「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

トラブルシューティング

エラー：「No login configured」

原因： tea に Gitea インスタンスが登録されていません。 解決策： tea logins add を実行するか、トークン、OAuth、SSH 認証などの設定方法について references/authentication.md を参照してください。

エラー：「Repository not found」または誤ったリポジトリが検出される

原因： Git のリモートが既知の Gitea ログインを指していないか、リポジトリのスラッグが誤っています。 解決策：

1. リモートを確認します：git remote -v
2. 明示的に指定します：tea issues ls --repo owner/repo --login mylogin
3. ログイン URL がリモートと一致することを確認します：tea logins ls

エラー：「401 Unauthorized」または「403 Forbidden」

原因： トークンの有効期限切れ、スコープ不足、または誤ったログインです。 解決策：

1. トークンの有効性を確認します：tea whoami
2. Gitea のウェブ UI で必要なスコープを指定してトークンを再生成します
3. ログイン情報を更新します：tea logins edit

エラー：「Connection refused」

原因： Gitea サーバーに接続できません。 解決策：

1. サーバー URL を確認します：tea logins ls
2. ネットワーク／VPN の接続を確認します
3. 自己署名 TLS を使用する場合：tea logins add --insecure

エラー：「No help topic for 'orgs'」／「flag provided but not defined」

原因： 古い形式のコマンドです。よくある間違い：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 - ログイン設定、トークンのスコープ、複数インスタンスの管理、環境変数
• references/tea-commands.md - tea の各サブコマンドに関するすべてのフラグとオプションのリファレンス
• references/workflows.md - 高度な複数ステップのワークフロー、tea api のパターン、一括操作