BackstageのGitHub Orgデータ連携を深堀り！

はじめに

ACS事業部　亀崎です。

自分自身の仕事が直接関係するからということもありますが、最近「Backstage」という言葉を聞く機会が少しずつ増えてきた気がします。

Backstage Communityが公開した2024年11月時点でのプロジェクトの状況は以下の通り。

2024年3月に公開したものと比較すると

項目	2024年3月	2024年11月
Adopters	2500+	3000+
Contributors	1.4k+	1.6k+
Discord members	13k+	15k
Project forks	5k	6k
Total contributions	50k+	60k
Open source plugins	150+	200+
stars	25k+	28k

とまだまだ拡大中といったことがわかります。

本ブログでも多くの記事を投稿させて頂いております。ぜひこの機会に過去の記事もご覧いただきたいと思います。

techblog.ap-com.co.jp

さて、そんなBackstageですが、皆様ご存知の通りBackstageのユーザーやグループ情報としてGitHub Organizationの情報と連携できます。では、その連携の具体的内容についてはどうでしょうか。ドキュメント等に記載されている内容のままであることも多いのではないかと思います。今回は、このGitHub Organizationとの情報連携の機能について少し詳しく見ていきたいと思います。

BackstageのGitHub Organization連携機能

まず、BackstageのGitHub Organization連携のドキュメントはこちらになります。

backstage.io

導入方法

まずは導入方法からみていきましょう。GitHub Org連携はBackstageのBackend側に組み込む機能です。New Backend Systemをご利用の場合は導入そのものはとても簡単で、 @backstage/plugin-catalog-backend-module-github-org というPluginをインストールし、コンフィグレーションを追加するだけです。

install方法

yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github-

packages/backend/src/index.ts

backend.add(import('@backstage/plugin-catalog-backend'));
backend.add(import('@backstage/plugin-catalog-backend-module-github-org'));

コンフィグレーションの例

catalog:
  providers:
    githubOrg:
      id: production
      githubUrl: https://github.com
      orgs: ['organization-1', 'organization-2', 'organization-3']
      schedule:
        initialDelay: { seconds: 30 }
        frequency: { hours: 1 }
        timeout: { minutes: 50 }

コンフィグレーションの catalog.providers.gitHubOrg.orgs には、連携するGitHub Organizationを指定し、scheduleにそのデータをチェックするスケジュールを記載します。orgsについては指定しなくても構いません。指定しない場合、データが取得できるOrganizationすべてを対象としてデータを取得します。

これで定期的にGitHubにアクセスし、指定したGitHub Organizationに関係するGitHubのTeamやUserの情報を取得し、BacskstageのGroupやUser Entityとして登録するようになります。

このほかBackstageのEvent指定をすることで、GitHub Webhookを利用した連携も有効にすることができます。

指定方法についてはこちらのページに詳細に記載されています。

backstage.io

より詳細な指定可能オプションについては、以下のconfig.d.ts ファイルをご参照ください。

github.com

GitHubのデータとBackstageデータのマッピング

GitHubのTeamやUserデータをBackstageのデータに変換、登録する処理は次のコードで確認することができます。

github.com

簡単にまとめると次のようになっています

User情報

GitHub	Backstage
GitHub アカウント名	metadata.name
GItHub アカウント名	metadata.annotations.'github.com/user-login'
bio	metadata.subscription
name	spec.profile.displayName
email	spec.profile.email
avatarUri	spec.profile.picture

なお、登録されるユーザーのBackstage namespaceは default となります。

Team情報

GitHub	Backstage
teamアカウント名	metadata.name
/teamアカウント名	metadata.annotations.'github.com/team-slug'
'team'	spec.type
description	metadata.description
name	spec.profile.dispplayName
avatarUrl	spec.profile.picture
親teamアカウント名	spec.parent
members 登録ユーザーアカウント名のリスト	spec.members

登録されるGroupのBackstage namespace ですが、コンフィグレーションのorgs登録内容によって設定される内容が異なります。

orgsが明示的に指定されており、かつ指定が1つしかない場合、namespaceは default で登録されます。orgsが指定されていない場合、または2つ以上登録している場合は namespace は GitHub Organization 名となります。

この違いは、異なるGitHub Organizationで同じTeam名が存在する場合にそれぞれのTeamを別々のBackstage Groupとして登録するための仕様です。

仕様としては理解できるものの、ある条件のもとでは問題が発生します。つまり本仕様では、orgsに当初1つしか登録していなかった状態から途中で2個以上に追加した場合に、Groupデータの一貫性が失われることを意味します。グループの名称は Backstageのその他のEntityで owner として登録している情報です。Permissionを指定する場合にも重要な要素の１つです。このため指定内容を変更する前後で一貫性が失われるのは好ましくありません。

　1つしか登録しない場合はorgsを指定せず、2つ以上にする場合にも orgs を無指定のまま利用するか、2つ以上のときにはじめて orgs を明示的に指定することをお勧めします。

実はこの点がこの記事で一番重要なポイントです。Backstageの公式ドキュメントにも次のように記載はされている動作ではありますが、導入前に動作の違いを認識し、どうすべきかを理解するのは難しいのではないかと思いますので、ご注意ください。

orgs (optional): The list of the GitHub orgs to consume. If you only list a single org the generated group entities will use the default namespace, otherwise they will use the org name as the namespace. By default the provider will consume all accessible orgs on the given GitHub instance (support for GitHub App integration only).

ユーザー／グループの連携について、その内容の詳細をみる機会は少ないのではないでしょうか。しかしユーザー／グループの内容についてはその後活用していくなかでも重要な要素でもあり、一番最初に適切に設定していないとあとで問題になることがありますので、この機会に一度ご紹介した部分をご覧になってみるのもよいと思います。

また、この記事が皆様の参考になれば幸いです。

さいごに

弊社ではPlatform Engineering、Backstageに関するご支援をさせていただいております。ご興味のある方ぜひご連絡ください。

APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。