GitHub App を作成

このガイドでは、サーバーに独自の GitHub アイデンティティを持たせる方法を説明します。所要時間は約 2 分で、作業するのはサーバー所有者だけであり、サーバーごとに 1 回だけ行えば済みます。

不要な場合もあります

公式ビルドには GitHub のクライアントIDがすでに同梱されているため、何も登録しなくても GitHubでサインイン はそのまま動作します — デバイスフローはクライアントIDだけで認証するので、同梱しても安全です。自分で App を登録するのは、サーバー自身に動作してほしい場合（Webhook、PR のポーリング、チケット同期を、個人の資格情報ではなく App のインストール上で実行する場合）、またはソースからビルドする場合です。

その後に自分のアカウントを接続する方法については、GitHub インテグレーションを設定 を参照してください。

サーバーに独自の App が必要な理由

1 回の登録からは 2 つの異なる役割が生まれ、その両方を成立させているのが App です:

役割	何が応えるか	なぜ重要か
人がサインインする	App のクライアントID、デバイスフロー経由で	サーバー上で、すべてのデバイスで、自分自身の資格情報が得られます。貼り付けたりローテーションしたりするトークンはありません
サーバーが動作する	App の ID + 秘密鍵 → インストールトークン	Webhook、PR のポーリング、チケット同期が、誰か 1 人のトークンが有効であり続けることに依存しなくなります

この表にないものに注目してください: クライアントシークレットです。GitHub のデバイスフローは、デバイスコードの要求とトークンのポーリングの両方でクライアントIDだけで認証するため、サインインのために保管すべきシークレットはありません。

自分専用の App がなくても、前者はビルドに同梱されたクライアントIDを通じて引き続き機能します。後者はサーバー所有者の資格情報にフォールバックするため、バックグラウンド作業は最初にオンボーディングした人に乗っかります。

「Control Center の GitHub App をインストール」ボタンはありません

配布型の GitHub App は、全員のサーバーで 1 つのクライアントシークレットと 1 つのインストールを共有することを意味し、そうなると各ワークスペースのリポジトリアクセスが、そのワークスペースの誰も管理していない資格情報を通ることになります。そのため各サーバーが自身の App を持つのです — このガイドが示すのは、そのコストがいかに小さいかということです。

前提条件

• あなたがサーバー所有者であること — providerApps.* の操作はこれに制限されており、カードはほかの誰にも表示されません
• GitHub アカウント、または App を作成できる組織
• 公開アクセス可能なものは不要: サインインはデバイスフローなので、サーバーには受信ポート、トンネル、コールバックURL、ドメインのいずれも必要ありません

App を登録する

1. github.com/settings/apps/new を開きます（組織の場合: Settings → Developer settings → GitHub Apps → New GitHub App）
2. GitHub App name — 任意です。Control Center (yourname) で問題ありません。サーバーが作成するコミットやコメントに表示されます
3. Homepage URL — 任意です（例: https://github.com/your-name）
4. Callback URL — 空のままにします。デバイスフローには不要です
5. Enable Device Flow にチェックを入れます。サインインが機能するために欠かせない唯一の設定です
6. Webhook を別途設定しない限り、Webhook → Active のチェックを外します
7. Repository permissions で、少なくとも次を付与します:
   • Contents: Read and write
   • Metadata: Read-only（必須）
   • Pull requests: Read and write
   • Issues: Read and write — チケットに GitHub Issues を使う場合、およびボットが PR 会話のコメントを検索する場合（GitHub PR から Control Center に話しかける を参照）
   • Checks: Read-only — PR ページの CI 状態表示用
8. Where can this GitHub App be installed? では、適したものを選びます — 個人のサーバーには「Only on this account」が適切です
9. Create GitHub App をクリックします

3 つの値を控える

作成直後に、App のページで次の値を控えます:

値	場所
App ID	General タブの上部付近
Client ID	General タブの「Client secrets」の下
Private key	Generate a private key — .pem がダウンロードされます

秘密鍵ファイルは 1 回だけダウンロードされ、GitHub が再び表示することはありません。貼り付けるまでは保管しておいてください。新しいものはいつでも生成できます。

クライアントシークレットは省略可能で、得られるものはちょうど 1 つです: 「Expire user authorization tokens」を ON のままにした場合に、8 時間ごとに再サインインを求める代わりに、誰かのトークンを黙って更新するのがこれです。サインイン自体がこれを使うことはありません。

より簡単な構成は、この有効期限を OFF にすることです。そうすればシークレットはどこにも必要ありません。ON のままにする場合は、シークレットを生成し、設定 → サーバー → シングルサインオン（プロバイダーアプリカード）に貼り付けます — これ用の環境変数はなく、ビルドに埋め込まれることもないため、シークレットはあなたのサーバー上にとどまります。

自分のアカウントにインストールする

登録されただけでインストールされていない App は、人を認証できても、何も読み取れません。

1. App のページで Install App を開きます
2. 自分のアカウントまたは組織にインストールします
3. All repositories を選ぶか、このサーバーが見るべきリポジトリを選択します

Control Center に貼り付ける

1. 設定 → サーバー → シングルサインオンに移動し、プロバイダーアプリカードまでスクロールします
2. GitHub ブロックで各フィールドを設定します:
   • アプリID — 数値の App ID
   • 秘密鍵 — .pem 全体を、BEGIN 行と END 行も含めて貼り付けます
   • クライアントID — 同じページの値です
   • クライアントシークレット — 生成した場合のみ（トークン更新用）
3. テストをクリックします

鍵は保存された時点で解析されるため、切り詰められた貼り付けや形式の誤った貼り付けは、数時間後のバックグラウンドリクエストで失敗するのではなく、その場で拒否されます。テストはさらに進んで、App がどのアカウントにインストールされているかを GitHub に問い合わせます — 「保存されている」と「機能する」は別の主張であり、何かが動作することを意味するのは後者だけです。

チェックポイント: GitHub ブロックに「サーバーが自身として動作でき、人がサインインできます。」と表示され、設定 → ワークスペース → プロフィールと識別情報 → コードホスティングの下の GitHub の行に GitHubでサインイン が表示されるようになります。

代わりに環境変数で設定する

ヘッドレスまたはスクリプトによるインストールでは、サーバーは保存された値がない最初の時点で、環境から各フィールドをシードします:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

これらにコマンドラインフラグはありません — コマンドライン上のシークレットは、ホスト上のすべてのプロセスから ps で読めてしまうためです。設定できる場所は環境だけであり、環境はビルドに同梱されたものより優先されます。完全なリストは .env.template にあります。

ローカル開発では、リポジトリルートの .env が同じ値を持ち、デスクトップがそれを起動したサーバーに渡します。そこでは鍵を1 行にしてください: .env の値は 1 行であり、二重引用符内の \n は改行にデコードされます。

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID と GITHUB_APP_PRIVATE_KEY は、サンドボックスのトークンブローカーがすでに読み取っているものと同じ名前なので、きめ細かいエージェントトークンを設定済みのホストは、サインイン用のレーンをそのまま利用できます。シードはフィールドごとに 1 回行われます — その後は保存された値が優先されるため、設定画面での編集が次の再起動で取り消されることはありません。

Linear でも同じことをする

Linear にはデバイスフローがないため、そのサインインはブラウザーの往復となり、コールバックURLが必要です — プロバイダーアプリカードに、登録すべき正確な URL が表示されます。

1. linear.app/settings/api/applications/new で OAuth アプリケーションを作成します
2. Callback URL に、カードに表示される URL をそのまま設定します
3. クライアントID と クライアントシークレットを Linear ブロックに貼り付けます
4. 任意でワークスペースの APIキー を追加します — これは、誰も依頼していないときにサーバーがチケット同期に使う資格情報です

トラブルシューティング

サインインダイアログに、プロバイダーがデバイスコードを返さなかったと表示される

App で Enable Device Flow がオフになっています。General でオンにして、再試行してください。

テストで資格情報は機能すると表示されるが、App がどこにもインストールされていない

登録とインストールは別の手順です。App のページで Install App を開き、インストールしてください。

テストで秘密鍵を読み取れないと表示される

-----BEGIN 行と -----END 行も含めて、.pem ファイル全体を貼り付けてください。ed25519 や EC の鍵は使用できません — GitHub App は RSA で署名します。

メンバーがサインインしたのにリポジトリが表示されない

App が、それらを所有するアカウントにインストールされていないか、そのインストールが別のリポジトリを選択しています。本人のサインインは、App が見ることを許可されているものだけを付与します。

関連ガイド

• GitHub インテグレーションを設定
• GitHub PR から Control Center に話しかける
• コードホストを接続
• API キーを管理
• Slack インテグレーションを設定