GitHub 連携

GitHub を接続すると、Clowld Space はタスク番号を使って pull request を自動的に紐づけます。タスクの詳細画面から、PR の状態、変更規模、CI の結果、マージ競合を直接確認できます。

GitHub 連携が読み取るのは、インストール時に許可されたリポジトリだけです。コード、コメント、status check を書き込むことはありません。

セルフホスト版 Clowld Space では、セルフホストの Forgejo、Gitea、GitLab インスタンスも同時に接続できます。PR の自動紐づけ、マージ時の Done への変更、CI 表示を同じように利用できます。設定 → コードから設定してください。詳しくはセルフホスト Git ホスティングを参照してください。Clowld Space にはこの項目はありません。

PR 自動完了設定、タスク単位の例外、関連付け除外は 1.2.4 以降に含まれ、対応するサーバーとクライアントが必要です。

GitHub を接続する

ワークスペースの owner または admin が接続できます。

1. 設定 → コード を開きます。
2. GitHub の行で GitHub に接続をクリックします。
3. GitHub でアカウントまたは organization を選び、すべてのリポジトリか指定したリポジトリを許可します。
4. インストールが完了したら Clowld Space に戻ります。

接続状態は同じページに表示されます。通常のメンバーは状態を確認できますが、接続、切断、スイッチの変更はできません。

機能スイッチ

設定 → コード の プルリクエストとタスク には次の設定があります。GitHub の行の ⋯ メニューで GitHub 機能を一時停止 すると、下の 3 項目は機能しなくなりますが、GitHub App の接続は解除されません。

PR をタスクに紐づける

最も簡単な方法は、タスク番号をブランチ名または PR タイトルへ入れることです。タスクが CS-123 の場合:

cs-123-fix-login-redirect

CS-123 ログイン後のリダイレクトを修正

Clowld Space は大文字と小文字を区別せず、現在のワークスペースのタスク接頭辞だけを照合します。1 つの PR を複数のタスクに紐づけることもできます。

タスク番号を PR 本文だけに書く場合は、GitHub の closing keyword を必ず使ってください。

Closes CS-123
Fixes CS-123
Resolves CS-123

本文に Related to CS-123 のような通常の参照を書いただけでは、そのタスクへまったく紐づきません。Commit message と PR コメントも紐づけの対象外です。

手動で紐づけることもできます。タスクの Pull requests セクションで + をクリックし、PR の URL を貼り付けます。PR をタスクから外すには、その行の ⋯ メニューから タスクから外す を選びます。以後、Clowld Space がタイトルやブランチから再び紐づけることはありません。

タスクから PR を確認する

紐づけが完了すると、PR がタスク詳細の Pull requests セクションに表示されます。各項目には次の情報が含まれます。

• リポジトリ、番号、タイトル、作成者
• Open、Draft、Merged、Closed の状態
• 追加行数、削除行数、変更ファイル数
• CI の状態: すべて成功した check の件数、失敗した check の名前、実行中の check の件数。check が 1 つも設定されていない PR ではこの項目を表示せず、「check なし」を成功として扱いません。
• マージ可能性: GitHub がマージ状態を clean と報告した場合だけマージ可能。ほかに競合、blocked、behind を表示します。

CI の状態とマージ可能性は、Clowld Space が GitHub API から取得したスナップショットで、互いに独立しています。マージ済みまたはクローズ済みの PR では、この 2 項目を表示しません。GitHub が一時的に利用できない場合、カードを空にせず、前回のスナップショットを古い情報として表示します。

PR リストの下には目標状態と待機中の PR を表示します。closing keyword がない、変更しない設定、目標到達済み、終了済みの場合は表示しません。

項目をクリックすると GitHub の PR が開きます。PR サイドバーを無効にしてもこのセクションが非表示になるだけで、接続は解除されません。

PR のマージで Done になる条件

設定 → コードの PR マージ後のタスクのステータス で、既定の完了、進行中・完了カテゴリの状態（カスタムを含む）、または変更しないを選びます。ブロックは対象外です。全プロバイダーで共通です。

次の条件をすべて満たした場合だけ、選択した状態へ変更します。

1. 紐づいたマージ済み PR のうち少なくとも 1 つが、タイトルか本文で Closes CS-123 のように closing keyword の直後にタスク番号を指定している。Closes login CS-123 のように間に別の単語がある形式や、ブランチ名は対象外です。
2. タスクに紐づく Open や Draft の PR が残っていない。マージせずにクローズした PR は履歴として残り、完了を妨げません。
3. タスクが受理済みで、完了・キャンセル・目標の状態ではなく、Pull requests → ⋯ → PR マージ後もステータスを変えない がオフである。

タイトルやブランチの番号だけでは紐づけしか行いません。closing keyword はマージ時点で必要です。後から追加しても状態は変わりません。マージせず閉じた PR は履歴として残り、変更を妨げません。

判定はマージ、クローズ、紐づけの追加・解除時だけです。設定の変更やタスクの再開は過去の PR に遡って適用しません。既存ワークスペースの有効・無効設定は維持されます。変更はタイムラインに記録され、エージェントを起動しません。

複数のワークスペース

同じ GitHub App installation を複数の Clowld Space ワークスペースへ接続できます。GitHub イベントは各ワークスペースにそれぞれ送られ、各ワークスペースのタスク接頭辞に従って照合されます。

たとえば、1 つの PR が CS-1 と ENG-2 の両方を参照している場合、異なる接頭辞を持つ 2 つのワークスペースでそれぞれ紐づけられます。ワークスペース間で相手のタスクが見えることはありません。

同じ番号が接続中の複数のワークスペースでタスクに一致する場合（接頭辞が同じときに起こり得ます）、Clowld Space はどのワークスペースでも自動では紐づけません。関係のないタスクがマージで完了しないようにするためです。正しいワークスペースで手動で紐づけてください。

接続を解除する

設定 → コード の GitHub の行で ⋯ メニューから接続解除を選ぶと、現在の Clowld Space ワークスペースと installation の関係だけが削除されます。GitHub から App がアンインストールされることはありません。既存の PR 記録は保持されますが、新しいイベントはこのワークスペースに届かなくなります。

GitHub 側のリポジトリアクセスを取り消す場合は、個人または organization の GitHub App installations ページで App をアンインストールするか、リポジトリの範囲を変更してください。App をアンインストールすると、その installation に接続していたすべての Clowld Space ワークスペースがイベントを受信しなくなります。

セルフホスト設定

Clowld Space ではこのセクションの作業は不要です。セルフホスト環境では、自分の GitHub App を先に作成します。

1. GitHub App を作成する

GitHub の Developer settings → GitHub Apps で App を作成し、次の値を入力します。

Repository permissions:

次のイベントを購読します。

• Pull request
• Workflow run。正式リリース結果をタスクへ書き戻します。
• Workflow job。プロモーション CI の単一ジョブが失敗したとき、失敗ジョブ名とジョブログへのリンク付きの通知を早期に書き戻します。
• Check suite、Check run、Status。CI とマージ可能性を更新するために使用します。

Clowld Space で CI を表示しない場合は、Checks と Commit statuses の権限、および関連イベントの購読を省略できます。ただし Contents は必須です。付与しないとスナップショットのクエリ自体が失敗し、PR カードからマージ状態も消えます。

Workflow job を購読しない場合（または Actions 権限がない場合）でも他の機能は変わりません。プロモーション失敗の通知は、従来どおり Promotion Gate の一連の実行が完了した後に書き戻されますが、ジョブ単位の早期警告は失われます。

2. 環境変数を設定する

App の公開 URL から slug を確認します。たとえば https://github.com/apps/clowld-acme の slug は clowld-acme です。

GITHUB_APP_SLUG=clowld-acme
GITHUB_WEBHOOK_SECRET=<webhook secret entered when creating the App>
FRONTEND_ORIGIN=https://clowld.example.com

GITHUB_APP_SLUG と GITHUB_WEBHOOK_SECRET のいずれかがない場合、接続ボタンは無効になり、webhook エンドポイントもイベントを拒否します。

次の 2 つの変数は、PR カードに CI の状態とマージ可能性を表示するために必要です。Clowld Space は App として認証し、スナップショットを取得します。

GITHUB_APP_ID=<numeric GitHub App ID>
GITHUB_APP_PRIVATE_KEY=<complete PEM private key, including BEGIN/END lines and newlines>

秘密鍵は GitHub App の Private keys → Generate a private key から生成します。設定しない場合も連携は安全に縮退します。PR のミラー、タスクの自動紐づけ、マージ時の Done への変更は動作しますが、PR カードに CI やマージ状態は表示されません。

3. データベースを更新して接続する

既存のデプロイをアップグレードする場合は、通常のデータベースマイグレーションを先に実行します。

make migrate-up

API サービスを再起動し、設定 → コード から接続します。

よくある問題

• 接続ボタンを使用できない: GITHUB_APP_SLUG と GITHUB_WEBHOOK_SECRET が API プロセスに設定されていることを確認します。
• Webhook が 401 を返す: GitHub App と API が同じ Webhook secret を使っていることを確認し、GitHub の Recent Deliveries から再配信します。
• PR が紐づかない: リポジトリが App の許可範囲にあること、PR の自動紐づけが有効であること、番号が現在のワークスペースのものであること、誰かがタスクから外していないかを確認します。
• 本文に番号を書いても紐づかない: Closes CS-123 を使うか、番号をブランチ名または PR タイトルに入れるか、手動で紐づけます。
• CI の状態がない: GITHUB_APP_ID と GITHUB_APP_PRIVATE_KEY が設定済みで、App に Contents、Checks、Commit statuses の read-only 権限があり、関連イベントを購読していることを確認します。Contents が欠けるとスナップショット全体が失敗し、PR カードには CI もマージ状態も表示されません。インストール済み App に権限を追加した場合は、各 installation の所有者が GitHub 上で承認するまで有効になりません。
• PR リストの下には目標状態と待機中の PR を表示します。closing keyword がない、変更しない設定、目標到達済み、終了済みの場合は表示しません。

次のステップ

• タスク — 状態遷移と PR マージによる Done への変更

• トピックリソース — エージェントが実行時に使えるリポジトリ

• 環境変数 — セルフホスト GitHub App の全設定

• 交付と失敗復旧