gitea

Gitea（REST API）

$GITEA_TOKEN で認証して、$GITEA_URL/api/v1/... に HTTP リクエストを送信し、Gitea を操作します。このスキルは MCP サーバーに一切依存しません。すべての操作は直接 curl を呼び出して行います。

このエントリーファイルは小さく保ちます。現在のターンで必要なリファレンスパックだけを読み込みます。

常時適用されるルール

0. 接続先の強制判定。 Forge に関する操作の前に、git remote get-url origin を実行し、ホストを解析します。ホストが github.com の場合、このスキルは適用されません。内部の GitHub 組織も含めて、gh を使用します。それ以外のホストは Gitea の候補として扱います。プローブのベース URL として https://<host> を導出し、curl -fsS --max-time 5 "https://<host>/api/v1/version" を実行します。HTTP 200 が返り、version フィールドを含む JSON が得られた場合に限り、このスキルを使用します。プローブに失敗するかタイムアウトした場合はユーザーに確認し、別の Forge を推測してはいけません。
1. ユーザーに尋ねず、名前付き環境変数ペアから $GITEA_URL と $GITEA_TOKEN を解決します。 scripts/gitea.sh を読み込んでから gitea_auto を呼び出し、現在のリポジトリの origin と URL が一致するペアを選択します。一致するペアがない場合は、エイリアスなしの GITEA_URL／GITEA_TOKEN、次に従来の GITEA_HOST／GITEA_ACCESS_TOKEN を使用し、それでも見つからない場合はユーザーに確認します。$GITEA_URL は常に /api サフィックスのないベース URL です。
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 インスタンスごとに1組設定します。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 — インスタンスごとに名前付きペアを1組設定します。<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 にのみあります。新しいシェルを起動するたびに、そのファイルを読み込んでください。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

使用パターンは2つあります。

• リポジトリ内で環境変数が未設定の場合：gitea_auto が origin を解析し、ホストが GITEA_<ALIAS>_URL と一致するエイリアスを探します。
• リポジトリ外、または別のインスタンスを対象にする場合：最初に export GITEA_URL=https://git.aaa.com を実行します。その後 gitea_auto が git.aaa.com を設定済みのエイリアスと照合し、対応するトークンを読み込みます。どのエイリアスがどのホストに対応するか覚えておく必要はありません。

強制的な上書き：gitea_use ORGA を実行すると、URL に関係なく ORGA のペアが有効になります。

gitea ヘルパー

環境変数の解決後、読み込んだスクリプトによって 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 を自動的に付加します。curl の通信エラーと HTTP 4xx/5xx（{message, url} エンベロープ）を stderr に出力し、1を返します。成功時のレスポンス本文は jq で整形して出力します。

単一の課題の作成とコメント追加（標準的な書き込みフロー）

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件の操作 リポジトリとフォーク、ブランチ、タグ、コミット、リポジトリツリー、ファイルの内容（読み取り／作成／更新／削除）、リリース。
• references/api-issues-prs.md — 課題と PR のエンドポイント list/get/create/update issues、コメント、課題のラベル。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 を推測せず、ユーザーに確認してください。