GitHub Copilot SDKのサーバー間認証を導入｜GitHub Appと1時間トークンの運用

GitHubは2026年10月27日、GitHub Copilot SDKのサーバー間認証をパブリックプレビューとして公開した。GitHub Appのインストールトークンを使い、サインイン中の個人がいないバックエンドサービスや常駐エージェントからCopilotを呼び出せる。利用はGitHub Appをインストールした組織へ帰属し、その組織のモデルポリシー、予算、支出制御が適用される。

対象は、Copilot SDKをCI、社内ポータル、チケット処理、コードレビュー補助などのサーバープロセスへ組み込む開発チームだ。これまでは利用者ごとの認証情報をサービスへ持ち込む設計になりやすかった。今回の方式では、GitHub Appをワークロードの主体として扱える。ただし、トークンは1時間で失効し、SDKの実行プロセスへ明示的に渡す必要がある。本稿はニュースの紹介にとどまらず、導入条件、実装、更新、課金確認、失敗時の切り分けまでを整理する。

変わったのは「誰の利用として実行するか」

サーバー間認証の中心は、個人アカウントではなく組織へインストールしたGitHub Appで利用主体を表すことだ。アプリには組織権限のCopilot Requestsを読み取り専用で付与する。実行時にはアプリのインストールアクセストークンを発行し、Copilot SDKへ渡す。GitHubはこの短命トークンからアプリとインストール先組織を識別し、Copilotの利用量を組織へ計上する。

この方式は「ユーザーの代わりに操作する」OAuthとは目的が異なる。ユーザーOAuthは対話的なアプリで利用者本人の権限を使う場合に向く。サーバー間認証は、夜間ジョブや共有サービスのように利用者セッションが存在しない処理に向く。個人アクセストークンを共有アカウントへ固定する設計から移行できる点が固有の価値になる。

方式	主な用途	利用の帰属	運用上の注意
GitHub Appのサーバー間認証	バックエンド、常駐エージェント	インストール先組織	1時間トークンの更新が必要
ユーザーOAuth	対話型アプリ	サインインした利用者	利用者ごとの同意とセッション管理
GitHub CLI・保存済み認証	ローカル開発	開発者	無人サーバーでは主体が曖昧になりやすい
GitHub ActionsのGITHUB_TOKEN	Actionsワークフロー	ワークフローを実行する組織	専用の権限宣言と組織ポリシーが必要

導入前に組織側の条件をそろえる

1. GitHub Appを作成し、対象組織へインストールする。
2. 組織権限のCopilot Requestsを読み取り専用で許可する。API上の権限名はorganization_copilot_requests: readである。
3. 組織でGitHub Copilotを利用でき、サーバー間認証を許可するポリシーが有効か確認する。
4. 利用可能なモデル、予算、支出制御を組織の運用方針に合わせる。

Copilot Requestsは、リポジトリ内容を読み書きする権限とは別に扱う。Copilotを呼ぶだけのサービスなら、不要なリポジトリ権限を追加しない。サービスがソースを取得する場合も、Copilot利用権限とリポジトリ権限を分けて設計すると、障害時にどの許可が不足しているか判定しやすい。アプリを停止またはアンインストールすれば、GitHubは以後のCopilot利用を拒否するため、運用停止の手段としても使える。

GitHub Actionsでは組み込みトークンを使う

GitHub Actions内でCopilot SDKを動かす場合、別途GitHub Appを作らず、ワークフローに用意されるGITHUB_TOKENを利用できる。権限にはcontents: readとcopilot-requests: writeを明示する。あわせて組織ポリシーで、組織へ課金されるCopilot CLIの利用を許可する必要がある。

permissions:
  contents: read
  copilot-requests: write

steps:
  - uses: actions/checkout@v4
  - name: Run Copilot SDK service
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: npm run copilot-task

組み込みトークンはワークフロー単位で発行されるため、外部サーバーへ持ち出す用途ではない。Actions外のコンテナ、クラウドジョブ、常駐APIではGitHub Appのインストールトークンを発行する。実行場所で方式を分けることが、認証経路を単純に保つ第一歩になる。

外部サービスではトークンを明示的に渡す

GitHub Appの秘密鍵などを使ってインストールアクセストークンを発行したら、その値をCopilot SDKのランタイム接続へ渡す。公式ドキュメントは、明示トークンとuseLoggedInUser: falseの併用を示している。後者を有効にすると、環境変数やGitHub CLIなどから別の利用者資格情報を自動発見しないため、意図しない個人課金を防ぎやすい。

import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk";

const token = await mintInstallationToken(installationId);

const client = new CopilotClient({
  connection: RuntimeConnection.forStdio({
    gitHubToken: token,
    useLoggedInUser: false,
  }),
});

await client.start();

上のmintInstallationTokenは説明用の抽象化であり、GitHubがその名前の関数を提供するという意味ではない。実装ではGitHub Appの認証ライブラリまたはREST APIを使い、対象組織のinstallation IDに対するトークンを取得する。秘密鍵はSDKプロセスへ広く配らず、トークン発行を担う小さなブローカーへ集約する構成が扱いやすい。

1時間の失効を前提にプロセスを更新する

インストールアクセストークンは1時間で失効する。公式手順では、期限前に新しいトークンを発行し、SDKの子プロセスまたはランタイムを再起動して差し替える。長時間接続を維持したままトークンだけを上書きできると仮定しない。ジョブ単位でSDKクライアントを起動する構成なら、各ジョブの開始時に発行すればよい。常駐サービスなら、期限の数分前に新クライアントを立ち上げ、準備完了後に新規処理を切り替え、旧クライアントを終了する。

更新失敗時には、期限切れクライアントへ処理を流し続けず、新規受付を止めて再発行を試す。トークン値そのものをログへ出さず、installation ID、app client ID、発行時刻、失効予定、再起動結果だけを監査ログに残す。複数組織を扱うサービスでは、要求されたテナントとinstallation IDの対応をサーバー側で固定し、クライアントから渡された組織名だけで発行先を選ばない。

認証経路の優先順位をテストする

Copilot SDKは、明示したgitHubTokenを最優先し、続いて直接API向け環境変数、COPILOT_GITHUB_TOKEN、GH_TOKEN、GITHUB_TOKEN、保存済みOAuth、GitHub CLIの順に認証情報を探す。開発端末で成功し、コンテナで失敗する場合は、この探索順の差が原因になり得る。サーバー間認証の試験ではuseLoggedInUser: falseを設定し、明示トークンを外したときに必ず失敗することも確認する。

• 正常系：対象組織のトークンでセッションを開始し、許可モデルへ要求できる。
• 期限切れ：古いトークンで401となり、再発行後の新プロセスで回復する。
• 権限不足：Copilot Requestsを外すと403となり、リポジトリ権限の追加では直らない。
• 別組織：組織Aの要求を組織Bのinstallation IDで実行しない。
• ポリシー：許可されていないモデルを指定したとき、代替モデルへ黙って切り替えずエラーを記録する。

課金と利用主体はCSVで確認する

組織所有のIDに切り替える目的は、認証だけでなく費用と利用主体を一致させることにある。組織所有者はAI利用レポートのCSVでapp_client_idを確認できる。公開前にテスト用GitHub Appで少量の要求を実行し、想定した組織へ記録され、対象アプリのclient IDが残るかを確認する。予算超過時や利用停止時の挙動も、組織の支出制御と合わせて試験する。

リクエスト数だけでなく、処理種別、呼び出し元サービス、成功・失敗、利用モデルを自社側のメトリクスへ記録すると、GitHubの集計と照合しやすい。プロンプト本文や生成内容を無条件にログへ残す必要はない。費用配賦には、アプリを用途別に分けるか、単一アプリ内のサービス識別子を自社メトリクスへ持たせるかを先に決める。

401・403・モデルエラーを順番に切り分ける

症状	最初に確認する項目	対応
401	トークンの有効期限と発行先	対象installationで再発行し、SDKプロセスを再起動
403・機能無効	組織がサーバー間認証を許可しているか	組織設定と利用資格を確認
403・権限不足	Copilot Requests権限	GitHub AppまたはActionsの権限宣言を修正
モデルを利用できない	組織のモデルポリシーとSDK指定	許可モデルへ明示的に変更
別アカウントへ計上	使用したinstallation ID	テナント対応表と発行経路を修正

401を受けたときに個人のGH_TOKENへ自動フォールバックさせると、障害が隠れて課金先も変わる。サーバーでは明示トークン以外の探索を止め、認証失敗を運用アラートへ上げる。403では、機能の有効化、Copilot Requests権限、モデルポリシーを分けて確認する。GitHub Appのリポジトリ権限を広げても、Copilot利用権限の不足は解消しない。

段階導入とパブリックプレビューの限界

まず非本番の組織と専用GitHub Appで、短時間ジョブを1つ移行する。次にトークン更新、権限削除、アプリ停止、予算制御を試す。利用CSVの反映と自社メトリクスが一致したら、常駐サービスへ広げる。個人認証をすぐ削除せず、利用経路が残っていないことをログで確認してから撤去する。

2026年10月28日時点で本機能はパブリックプレビューである。提供条件、SDKのオプション、組織設定は一般提供までに変わる可能性がある。大規模展開では、利用中のSDKバージョンに対応する公式ドキュメントを固定してレビューし、変更履歴を追う。個人アカウントを介さず、組織単位の課金と停止を必要とするサービスには適合しやすい。一方、利用者本人の権限や同意が必要な対話型アプリは、ユーザーOAuthを選ぶ方が自然である。

関連記事

• GitHub CopilotのMCPを棚卸しする｜既定ポリシーと利用メトリクスの運用設計
• GitHub CLIが短命OAuthトークンに対応｜移行前にスクリプトとGit認証を点検

参考資料

• GitHub Changelog：GitHub Copilot supports server-to-server authentication
• GitHub Docs：Authenticating with GitHub Copilot SDK
• GitHub Docs：Authenticating to GitHub Copilot SDK with server-to-server tokens