GitHub Enterprise Cloudの管理者は、Visual Studio Subscription（VSS）の割当をREST APIで管理できるようになった。追加された処理は、Enterprise内の割当一覧取得、VSSとGitHubユーザーの手動照合、誤った照合の解除である。UPN形式とSCIM IDが一致せず、これまで管理画面で個別修正していた組織にとって自動化余地が大きい。
何が変わったか
公式Changelogでは、EnterpriseのVSS割当を取得するGET、UPNとGitHubハンドルを照合するPUT、手動照合を解除するDELETEが案内された。現行のAPIドキュメントでは、一覧取得にEnterprise Licensingのread権限、追加・更新・削除にwrite権限が必要とされる。
一覧APIは未照合だけを絞り込むパラメータを持つ。照合APIではVisual Studio管理ポータル由来のSubscription IDと、GitHubハンドルまたは検証済みメールアドレスを使う。これにより、HR・IdP・Visual Studio・GitHubの間でクロスウォークを作り、定期同期できる。
期待できる効果
大量の未照合ユーザーを画面で修正する作業を減らし、入社、異動、改姓、メールドメイン変更、アカウント統合に追従しやすくなる。ライセンス割当の可視性が上がれば、未使用席や誤割当の検出、請求確認も自動化できる。
ただし、API化は誤操作の影響範囲も広げる。誤ったクロスウォークを一括適用すると、別人へのライセンス紐付けや正しい手動照合の上書きにつながる。SCIMの存在確認だけで同一人物と判断せず、従業員ID、検証済みメール、雇用状態など複数の属性を使うべきである。
実装設計
同期処理は「取得」「候補生成」「承認」「適用」「再取得による確認」に分ける。最初からPUTやDELETEを実行せず、dry-runレポートとして、Subscription ID、VSSメール、候補GitHubユーザー、照合根拠、現在状態、変更内容を出力する。
書き込み権限を持つGitHub Appまたは実行主体は専用化し、通常の管理者トークンをCIへ埋め込まない。秘密は短期資格情報または安全なSecret管理を使い、操作ログを保持する。削除は特に慎重に扱い、退職者、重複アカウント、誤照合など理由コードを必須にする。
検証方法
少数の既知ユーザーで試行し、一覧取得、照合、再取得、解除、再照合を一巡させる。照合後にライセンス状態が期待どおり反映されるまでの時間も測定する。APIの200応答だけを成功条件にせず、GitHub側の最終状態とVisual Studio管理側の表示を照合する。
異常系では、存在しないSubscription ID、未検証メール、同姓同名、改姓前メール、停止済みGitHubユーザー、ページネーション、レート制限、部分失敗を試す。バッチは冪等にし、再実行で別ユーザーへ切り替わらないようにする。
ロールバック
変更前の割当一覧をスナップショット保存する。誤照合が判明した場合はDELETEで手動照合を解除し、正しいユーザーへ再照合する。ただし、解除中に利用権や請求へどのような影響が出るかは、自社契約と実環境で確認する。大量変更は小さなバッチに分け、問題発生時に影響範囲を限定する。
実務チェックリスト
- VSS UPN、GitHubハンドル、従業員IDの対応表を作る
- Enterprise Licensingのread/write権限を分離する
- dry-runと二者承認を必須にする
- 変更前後の割当スナップショットを保存する
- 部分失敗、再試行、ページネーションを試験する
- 誤照合解除と正しい再照合の手順を用意する
編集部の見解
API追加の価値は単なる作業時間削減ではない。人手で曖昧に処理していたID照合を、根拠付きの再現可能なプロセスへ変えられる点にある。一方で、権限と照合ロジックを誤ると大量誤割当を短時間で作る。書き込み自動化より先に、候補生成と承認の品質を固めるべきだ。