Gitea / Forgejo トークンの作成（Codeberg）

provider = "gitea" または provider = "forgejo" を指定した Git channel は、インスタンスの Gitea 互換 REST API に対して personal access token で認証し、トークンの所有者として応答します。両方のプロバイダーは 1 つの内部実装を共有しており、GitHub との唯一の実質的な違いは、アプリが存在せず、トークンと明示的な API ベース URL のみである点です。

以下の例では Codeberg（公開の Forgejo インスタンス）を使用しています。セルフホストの Gitea または Forgejo の場合は、ご自身のホストに置き換えてください。

公式ドキュメント: Forgejo の Access Token Scope はトークンスコープのアップストリームリファレンスです。Codeberg では Generating an Access Token に従ってください。Gitea インスタンスは同じトークン UI を提供します。

1. 専用のボットアカウントを使用する

トークンは別の bot アカウントで作成し、オペレーターアカウントでは作成しないでください。チャンネルは自身のアクティビティを無視します。トークンの所有者がアプリを @-mention する人間でもある場合、それらのメッセージは静かにスキップされます。専用アカウントを使うことで、bot の返信と自分のコメントを区別できます。

Codeberg では、ボット用の通常のセカンドアカウントを登録し、ターゲットリポジトリ（または組織）に書き込みアクセス権で招待します。

2. トークンを生成する

ボットアカウントとして: 設定 → アプリケーション → アクセストークンの管理 (Codeberg: https://codeberg.org/user/settings/applications)。

1. トークンに名前を付けてください（例: zeroclaw）。
2. スコープを選択してください。 チャンネルには、最低限以下が必要です：
   • read:user: チャンネルは起動時に /user から自身のボットアイデンティティを解決します。
   • Repository の読み取りと issue/PR の書き込み。Forgejo/Codeberg ではスコープは read:repository + write:repository および read:issue + write:issue にグループ化されています。UI が粗い repository / issue スコープのみを提供する場合は、それらにチェックを入れてください。
3. トークンを生成 してコピーしてください。一度だけ表示されます。

このトークンには、リポジトリの読み取りアクセスに加え、返信やリアクションのためのIssue/PRコメントの書き込みアクセスが必要です。対象リポジトリが必要とする以上の権限は付与しないでください。

3. API ベース URL を見つける

これはデフォルト値がない部分です。api_base_url が未設定の場合、チャネルは起動時にクローズ状態で失敗します。これは、すべてのリクエストがトークンをベアラー認証情報として保持しており、送信先ホストを推測しないためです。

値はインスタンスのルートに /api/v1 を付加したものです。

• Codeberg: https://codeberg.org/api/v1
• パブリック Gitea サービス: https://gitea.com/api/v1
• セルフホスト: https://git.example.org/api/v1

4. 設定にマッピングする

以下の各フィールドを、お好みのサーフェスに設定してください。アクセストークンは暗号化されたシークレットであり、専用のマスク付きウィジェットが用意されます。それ以外は通常のフィールドです。

provider: gitea は Gitea インスタンス用、forgejo は Forgejo インスタンス用（Codeberg を含む）。これらは同一に動作し、不明な値はサイレントなフォールバックではなく明確な起動エラーになります。

zeroclaw config set channels.git.<alias>.provider <value>

api_base_url: インスタンスのルートに /api/v1 を加えたもの（ステップ 3）。必須。これがないと起動はフェイルクローズで失敗します。

zeroclaw config set channels.git.<alias>.api_base_url <value>

access_token: ステップ2からのトークン。

channels.git.<alias>.access_token はシークレットです。 暗号化して保存され、平文の config.toml には決して保存されません。次のいずれかを通じて設定してください。書き込み時に暗号化されます:

zeroclaw config set channels.git.<alias>.access_token    # マスク入力のプロンプトを表示し、暗号化して保存

repos: 監視する owner/repo のリスト。空のままにすると、トークンが閲覧できるすべてのリポジトリをポーリングします。

zeroclaw config set channels.git.<alias>.repos <value>

完全なフィールドリファレンスについては、Git チャネル ページを参照してください。

5. 確認

Git チャネルは標準の配布アーティファクトに含まれますが、軽量版の Cargo デフォルトには含まれません。カスタムソースビルドでは、channel-git（デフォルト機能を無効にする場合は agent-runtime も）を含めます:

cargo build --features channel-git

channel-git は、接続済みのすべての forge プロバイダーを 1 つのビルドに取り込みます。プロバイダーごとの小さなサブセットは存在せず、channel-git なしで単体の provider-* フィーチャーをビルドしてもチャンネルは登録されません。

起動時にチャネルは /user を呼び出してボットのログインを解決し、IDENTITY OK 行をログに記録して、ポーリングを開始します。設定済みのリポジトリの issue または PR でボットを @-mention して、返信することを確認します。起動が api_base_url についてエラーで失敗する場合、ベース URL が欠落しているか空白です。イベントルーティング、ピアグループのバインディング、および運用上の注意については、Git チャネル ページを参照してください。

次のステップ

• チャンネルに戻る: イベントルーティング、ストリーミング、レート予算、および安全性については Git チャンネル。
• エージェントに到達できるユーザーを制限する: ピアグループ.
• forge イベントから自動化を駆動する: 標準運用手順 および Git SOP ファンイン。
• ZeroClaw は初めてですか？ クイックスタート と 概念。