カスタム プロパティと外部システムの統合

GitHub Appを使用して、組織のリポジトリのカスタム プロパティに外部メタデータを書き込みます。

この記事で

メモ

外部カスタム プロパティは パブリック プレビュー であり、変更される可能性があります。

ソフトウェア カタログや内部開発者ポータルなどの外部システムから、 GitHubのリポジトリ カスタム プロパティにメタデータを自動的に書き込むことができます。 これにより、外部システムがこれらのプロパティの信頼できるソースになり、所有権、サービス レベル、コンプライアンスの状態などのビジネス コンテキストをリポジトリ内で最新の状態に保つことができます。 外部プロパティは、 GitHubで管理されるカスタム プロパティと同じ場所で使用できます。

この自動化を設定するには、外部システムからのデータを使用して外部プロパティGitHub Appの API エンドポイントを呼び出すGitHubをインストールします。

  • 統合パートナー の Port は、外部カスタム プロパティの統合を開発しました。 ポートからメタデータを同期するために必要なすべての手順については、「ポート」ドキュメントの 「外部カスタム プロパティを GitHub するポート プロパティの同期 」を参照してください。 GitHub 今後、プロバイダーの追加に取り組む予定です。
  • 組織が別の 外部システムを使用している場合、または GitHubとの統合を作成する外部システムの代表である場合は、独自の GitHub App と自動化を作成する必要があります。 このガイドを読み続けます。

前提条件

このプロセスでは、複数の異なるユーザーが必要になる場合があります。 以下が必要です。

  • 本人の個人アカウント、または本人が所有者である組織またはエンタープライズ アカウントのいずれかでGitHub Appを設定する人
  • GitHub 上の 1 人以上の組織所有者が、必要な各組織にアプリをインストールし、必要に応じてアプリの表示名を登録すること

このガイドの範囲外では、自動化を作成して実行できるユーザーも必要です。外部システムと、自動化を実行するサーバーに適切にアクセスできます。

1. 表示名を選択する

組織内のすべての外部カスタム プロパティ キーの前に表示名が付けられます。 たとえば、 port.environmentと指定します。 これは名前空間として機能し、 GitHub またはその他の外部プロバイダーで管理されるカスタム プロパティとの競合を回避するのに役立ちます。

各表示名のスコープは、組織内の 1 つの GitHub App インストールに設定されます。 アプリでカスタム プロパティを GitHubに書き込む前に、アプリのインストールを表示名で登録する必要があります。 これは、アプリ自体または組織管理者が実行できる 1 回限りのプロセスです。 アプリのインストールは 1 回のみ登録でき、後で表示名を変更することはできません。

競合を回避し、ユーザーが外部システムからカスタム プロパティを識別するのに役立つ名前を選択します。 サード パーティのシステムに代わってアプリを発行する場合は、競合に対応するか、システムのセットアップ フローの一部としてユーザーが独自の表示名を選択できるようにする必要があります。

表示名は 1 ~ 15 文字で、文字と数字のみを含む必要があります。 すべての要件については、REST API の 外部プロパティ エンドポイントのアプリ インストールの登録に関 するページを参照してください。

2. GitHub App を登録します

GitHub Appは、API を呼び出して外部カスタム プロパティを管理する ID です。 また、GitHub で発生するイベントの Webhook を受信することもできます。

内部プロセス用のアプリを作成する場合は、組織またはエンタープライズ アカウントでアプリを作成することをお勧めします。 その後、必要な数の組織にアプリをインストールできるようになります。 サード パーティのシステムの担当者である場合は、他の企業がアプリをインストールできるように、アプリを GitHub Marketplace に発行する可能性があります。

手順については、GitHub アプリの登録 を参照してください。

アクセス許可の選択

[ 組織のアクセス許可] で、 リポジトリの外部カスタム プロパティ のアクセス許可を有効にして、アプリが外部プロパティ API にデータを書き込むことができるようにします。 必要なアクセス レベルは、アプリで実行する必要がある内容によって異なります。

  • アプリがインストール アクセス トークンを使用して独自の表示名を登録する場合は、[ 管理者アクセス] を選択します。 これは、多くの組織にインストールされるセルフサービス アプリに適したモデルです。
  • アプリがカスタム プロパティをGitHubにのみ書き込む必要がある場合は、[読み取り/書き込みアクセス] を選択します。 組織の管理者は、インストールの表示名を登録する必要があります。

読み取り専用 アクセスは、このタスクのオプションではありません。 このレベルのアクセス権を持つアプリは、独自の外部カスタム プロパティ定義のみを読み取ります。

webhook イベントをサブスクライブする場合は、追加のアクセス許可を有効にする必要がある場合があります。

詳細については、「GitHub Apps に必要なアクセス許可」を参照してください。

Webhook の選択

Webhook で、外部システムからのデータ転送をトリガーする必要がある GitHub のイベントをサブスクライブできるようにします。

例えば次が挙げられます。

  • アプリが組織にインストールされている場合 (created アクションを含むinstallation イベント)、外部システムから組織のリポジトリへの最初の同期をトリガーできます。 このイベントは、既定ですべての GitHub Apps に送信されます。
  • 組織内に新しいリポジトリ (created アクションを含むrepository イベント) が作成されると、リポジトリにメタデータを自動的に設定できます。 このイベントには、 メタデータ リポジトリのアクセス許可への読み取りアクセスが必要です。

自動化をスケジュールに従って実行するだけの場合は、Webhook は必要ありません。

詳細については、「GitHub Apps での Webhook の使用」を参照してください。

インストール スコープの選択

[このGitHubアプリをインストールできる場所] で、アプリが必要なすべての組織にインストールできることを確認します。

3. 自動化を作成する

ヒント

実装例については、 external-custom-properties-sample リポジトリを参照してください。

自動化はスケジュールに従って実行することも、イベントをリッスンすることもできます。 アプリ用に選択した Webhook によって、Webhook URL に転送される GitHub イベントが決まります。 また、メタデータ値の変更など、サードパーティ システム上のイベントに応答することもできます。

自動化では、 GitHub App はインストール アクセス トークンを取得し、トークンを使用して外部システムから GitHubの外部プロパティ API エンドポイントにデータを送信する必要があります。 「GitHub App インストールとしての認証」を参照してください。

REST API の次のエンドポイントを参照してください。 要求サイズの制限と、自動化で考慮する必要があるエラー コードに関する情報が表示されます。

4. アプリをインストールする

必要な組織に GitHub App をインストールし、必要なアクセス許可を承認します。 「独自のGitHub アプリのインストール」を参照してください。

外部カスタム プロパティのアクセス許可は組織スコープであるため、既定では、すべてのリポジトリへのアクセス権を持つアプリがインストールされます。 アプリにリポジトリ レベルのアクセス許可がない限り、個々のリポジトリを選択するオプションは表示されません。

アプリが表示名を自動的に登録しない場合、または 管理者 アクセスを承認できない場合、組織の管理者はインストールの表示名を登録する必要があります。 これは、組織の所有者、または organization_external_properties_for_repos:admin の詳細なアクセス許可を持つユーザーである場合があります。 外部カスタム プロパティについては、「アプリのインストールを登録する」を参照してください。

5. データ転送を検証する

自動化が実行されたら、外部プロパティが組織のリポジトリと同期されていることを検証します。 これらは、組織またはそのリポジトリのカスタム プロパティ設定で確認できる必要があります。 プロパティ キーの前に外部表示名が付き、値は アイコンで示されます。 「Organization 内リポジトリのカスタム プロパティの管理」を参照してください。

外部プロパティ 値 は、リポジトリ REST API エンドポイント のすべてのカスタム プロパティ値の取得で、従来のカスタム プロパティ と共に返されます。 ただし、カスタム プロパティの /schema エンドポイント ("組織のすべてのカスタム プロパティを取得する" など) は、外部プロパティを返 しません 。

ユーザーは、 GitHubでこれらのプロパティを編集することはできませんが、従来のカスタム プロパティを使用する任意の場所で使用できます。

6. 統合を維持する

自動化の実行とアプリのインストールを維持して、外部システムからのデータの同期を維持します。 組織から GitHub App をアンインストールすると、インストール名と表示名が登録解除され、アプリによって作成されたすべての外部プロパティが 削除されます。

組織で定義されているプロパティの数に注意してください。 各組織は、最大 100 個のプロパティ定義を持つことができます。 外部カスタム プロパティと標準カスタム プロパティの両方がこの制限にカウントされます。