Backstageに入門してみよう：02_PostgreSQLとの接続とGitHub Integrationの実装

はじめに
前提条件
Backstage インスタンスを PostgreSQL と接続する
GitHub Integration 機能を用いたユーザー認証
最後に
ACS事業部のご紹介

はじめに

こんにちは。ACS事業部の青木です。

2025/01/25 に以下のようなブログを書きました。
本記事はその続きとなります。（かなり間が空いてしまった…）

techblog.ap-com.co.jp

以前の記事では、 Backstage を開発するための環境構築の手順から、実際に開発モードで Backstage インスタンスを起動するところまでを行いました。
本記事では、ローカル環境で起動した PostgreSQL を Backstage と接続する手順と、 GitHub Integration 機能を用いたユーザー認証機能の実装方法について説明します。

前提条件

以前の記事との繰り返しになりますが、前提条件については以下の通りとなっています。

本検証の実行環境は Windows 11 の WSL2 Ubuntu 22.04 上にて作業します。
実行環境の管理者アカウントへのアクセスを任意のタイミングで行える状態で作業します。
git および docker は WSL 上にインストール済みであることとします。
apt-get を使ってパッケージをインストールできる環境であること
検証に利用する GitHub Organization で"GitHub App マネージャー"以上の権限があること

なお、私が検証した際の具体的なバージョンは以下の通りです。

Windows 11 バージョン24H2
WSL2 Ubuntu 22.04.3 LTS

Backstage インスタンスを PostgreSQL と接続する

まず、 PostgreSQL インスタンスをローカルにインストールし、 Backstage と接続します。

なぜPostgresSQLへの接続が必要なの？

Backstageの公式サイトによると、以下のような記述があります。

デフォルトのデータベースは、インメモリデータベースであるSQLiteですこれは、環境設定が不要なため、最初の実験に最適です。@backstage/create-app Backstage を本番環境にデプロイする準備ができたら、またはさらに永続的な開発セットアップでは、Backstage データベースを PostgreSQLです。

（上記は日本語で自動翻訳した文章です） backstage.io

つまり、デフォルトで実装されている SQLite は一度停止してしまうとデータが消失する仕様となっています。
そのため、実運用で使用することを想定すると、停止などの操作があってもデータが保存されるDBを使用することが推奨されているわけです。

PostgreSQLのインストールとセットアップ

それではこれからPostgreSQLのインストールとセットアップを行っていきましょう。
まずは、PostgreSQLをインストールします。

sudo apt update
sudo apt-get install postgresql

続いて、PostgreSQLの起動とパスワードの設定を行いましょう。

# Postgreの起動
sudo service postgresql start
# Postgreにログイン
sudo -u postgres psql
# postgresユーザーのパスワードを設定
postgres=# ALTER USER postgres PASSWORD '≪任意のパスワードを設定≫';
ALTER ROLE
# Postgresからログアウト
postgres=# \q

これで、PostgreSQLのセットアップは完了です。

Backstage に PostgreSQL の設定を行う

Backstage が PostgreSQL と接続する際に使用する PostgreSQL クライアントをインストールします。

yarn --cwd packages/backend add pg

続いて、app-config.local.yamlに以下の記述を追加します。

backend:
  database:
    # config options: https://node-postgres.com/apis/client
    client: pg
    connection:
      host: localhost
      port: 5432
      user: postgres
      password: ≪PostgreSQLに設定したパスワード≫

ここまで完了したら、 Backstage のルートディレクトリまでもどり、再度yarn devを実行しましょう。
問題なく Backstage が起動し、画面が表示されたら問題なく Postgres との接続は完了です。

GitHub Integration 機能を用いたユーザー認証

続いて、 GitHub Integration の導入を行いましょう。
これを行うことにより、 Backstage 利用時に GitHub によるユーザー認証を行わせることができます。
また、Backstage側で GitHub Issue やGitHub Actions の実行履歴などを確認することができたり、Software Template機能を使用してテンプレートから開発用資材を払い出すこともできます。
(一部機能は別途プラグインの導入も必要です)

Software Templateについてより詳しく知りたい方は、弊社がリリースしている Managed Backstage 「PlaTT」の開発者がとってもわかりやすいブログを出しておりますので、ぜひご覧ください。

techblog.ap-com.co.jp

本記事では、「ユーザー認証」と「GitHub 環境を利用したSoftware Templateの実装」を実現するために必要な GitHub Integrationの実装を行います。
ステップは大きく分けて、以下の 4 ステップに分かれています。

Backstage 用 GitHub App を使用した認証情報の準備
GitHub Authentication Provider の実装
GitHub Organizational データ連携の実装
Backstage フロントエンドに GitHub サインイン画面を実装

Backstage 用 GitHub App を使用した認証情報の準備

GitHub App の作成

まずは、 GitHub App の作成から行いましょう。

GitHub にて、[≪ Backstage と連携する GitHub Organization のホームページ≫]→[Settings]→[Developer settings]→[GitHub Apps]→[New GitHub App]をクリックします。
まずは、"Register new GitHub App" 、"Identifying and authorizing users" 、"Post installation" 、 "Webhook" のセクションから行います。

設定セクション	設定名	設定値	備考
Register new GitHub App	GitHub App name	≪任意のGitHub App名≫	名前は、グローバルで一意である必要があります
	Homepage URL	http://localhost:3000
Identifying and authorizing users	Callback URL	http://localhost:7007/api/auth/github/handler/frame
	Expire user authorization tokens	☑
	Request user authorization (OAuth) during installation	□
	Enable Device Flow	□
Post installation	Setup URL (optional)	□
	Redirect on update	□
Webhook	Active	□
	Webhook URL	□
	Secret	□

続いて、 "Permission" セクションです。
ここでは、 Backstage に許可したい GitHub の操作権限を設定します。
設定することができる Permission の種類は非常に多くあるので、設定するものだけこちらに記載します。

Permission種別	設定名	設定値	備考
Repository permissions	Actions	Read-only
	Administration	Read and write
	Commit statuses	Read-only
	Contents	Read and write
	Environments	Read and write
	Issues	Read and write
	Metadata	Read-only	Contentsに権限を付与すると、自動的にRead-onlyになります
	Pull requests	Read and write
	Secrets	Read and write
	Variables	Read and write
	Workflows	Read and write
Organization permissions	Members	Read-only

最後に、"Subscribe to events"セクションです。

質問	設定名	設定値
Based on the permissions you’ve selected, what events would you like to subscribe to?	Installation target	□
	Meta	□
	Security Advisory	□
Where can this GitHub App be installed?	Only on this account	⦿
	Any account	〇

ここまで完了したら、[Create GitHub App]をクリックして Application を作成します。

GitHub App の認証情報の取得

作成が完了すると、作成した GitHub App の概要が表示される画面に遷移します。

こちらに表示される App ID と Client ID は Backstage に読み込ませる認証情報の一部となりますので、控えておきましょう。

続いて、 Client secret の作成を行います。
"Client secrets"セクションに移動し、[Generate a new client secret]をクリックします。

払い出された Client secret の値を控えておきましょう。

続いて、 Private key の作成を行います。
そのまま画面下にスクロールして、"Private keys"セクションに移動し、[Generate a private key]をクリックしましょう。

新たな Private key が画面上に表示され、 Private key の pem ファイルがローカルにダウンロードされます。

この pem ファイルも Backstage からの認証に必要となりますので、控えておきましょう。

App ID 、 Client ID 、 Client secret 、 Private key の値をそれぞれ控えることができていれば、 GitHub 認証に必要な情報はそろえられています。

GitHub App を Organization にインストール

続いて、 GitHub App をインストールしましょう。
左ペインから、[Install App]をクリックします。

[Install]をクリックします。

Backstage の Scaffolder Template 機能や、 GitHub リポジトリの情報集約機能をフルで活用するためにはすべてのリポジトリを対象とすることが望ましいです。
そのためここではOrganization内のすべてのリポジトリに対してインストールされるように設定します。
"for these repositories:"にて、インストール対象を[All repositories]に設定し、[Install & Authorize]をクリックします。

https://github.com/organizations/≪GitHub Appを作成したOrganizaion名≫にアクセスし、[Settings]にアクセスします。
"Third-party Access"セクションの[GitHub Apps]をクリックし、インストールした GitHub App が表示されていることを確認してください。

github-credential.yamlに認証情報を入力

続いて、 GitHub Integration にて利用するクレデンシャル情報をファイルに記載します。 Backstage のルートディレクトリに、 GitHub App の認証情報用の yaml ファイルを作成しましょう。
ここではファイル名を github-credentials.yaml とします。

ファイルを作成したら、以下のように値を記載しましょう。

# Backstage が GitHubを操作するために使用する認証情報
appId: ≪App ID の値≫
clientId: ≪Client ID の値≫
clientSecret: ≪Client secret の値≫
webhookSecret: ≪任意の値（今回はWebhookを利用しないものの設定しないとエラーになるため）≫
privateKey: |
  -----BEGIN RSA PRIVATE KEY-----
  ≪private.keyの値≫
  -----END RSA PRIVATE KEY-----

注意点として、"privateKey"の値を上記のように次の行以降に入力する際は、行頭にスペースを2つ入れ、インデントされるようにしてください。
インデントされていないと値として正しく認識されないため、注意しましょう。

GitHub Authentication Provider の実装

では続いて、 GitHub Authentication Providerの実装を行います。
こちらは、 GitHub のユーザー情報などを用いて OAuth 認証を行う際に利用する機能となります。

バックエンド更新

Backstage のルートディレクトリから、packages/backend/src/index.tsxファイルを開きます。
// auth pluginというセクションに、@backstage/plugin-auth-backend-module-github-providerプラグインを追加する処理を追記しましょう。

// auth plugin
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-github-provider')); // ←この行を追記

app-config.local.yaml に GitHub の設定を追記

早速、Backstageの設定ファイルに GitHub Integration 認証の設定および OAuth 認証の設定をを追記します。 app-config.local.yamlを開き、以下のように追記しましょう。

# BackstageがGitHubを操作する際にGitHub Appの認証情報を利用するように設定
integrations:
  github:
    - host: github.com
      apps:
      # github-credentials.yamlに記載の情報を利用する
      - $include: github-credentials.yaml

# GitHub の OAuth認証を利用するように設定
auth:
  # providerパラメータ内の設定の中から"development"を利用する
  environment: development
  providers:
    github:
      development:
        clientId: ≪Client IDの値を入力≫
        clientSecret: ≪Client Secretの値を入力≫
        signIn:
          resolvers:
            # resolverとしてusernameMatchingUserEntityNameを指定
            - resolver: usernameMatchingUserEntityName

OAuth認証を利用する際、 Backstage ではどのように GitHub から得たどの情報とBackstage上で持つ情報をどのように突合して認証を許可するかを定義するために、resolverというパラメータを指定する必要があります。
今回は"usernameMatchingUserEntityName"というパラメータを指定しています。
これは、 GitHub Organization に登録されているユーザー名が Backstage に登録されているユーザーエンティティと同じ場合にログイン認証を許可する、という仕組みとなっています

参考：GitHub Authentication Provider

backstage.io

ここまで設定が行えたら一度、yarn devコマンドを実行し、 Backstage が立ち上がることを確認しておきましょう。
エラーなく立ち上がるようであれば、ここまで問題なく設定が行えています。

GitHub Organizational データ連携の実装

前章では、 GitHub を利用した OAuth 認証で認証するための設定を追加しました。
しかし、まだ認証を行うための設定は完全ではありません。

Backstage のユーザーエンティティは現時点ではまだ作成されていないため、現時点で認証を行おうとしても、「Backstage 側にユーザーエンティティが存在しない」という旨のエラーが出てしまいます。
ユーザーエンティティは手動で作成は可能です。
しかし、随時 Backstage 利用希望者が現れる度手動で追加して、メンバーが離れたら削除して…と管理するのは大変です。

しかしご安心ください。 Backstage には GitHub Organization のユーザーや GitHub Team の情報を定期的に Backstage に同期し、ユーザーエンティティとして管理する機能が存在します。

参考：GitHub Operational Data

backstage.io

こちらの機能については弊社のブログでも詳しくご紹介しておりますので、よろしければご覧ください。

techblog.ap-com.co.jp

では、早速実装を行っていきましょう。
GitHub Organizationに所属するメンバーでの自動認証を行うためには、@backstage/plugin-catalog-backend-module-github-orgプラグインを使用します。
Backstage のルートディレクトリにて以下のコマンドを実行し、プラグインをインストールします。

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

Backstage のルートディレクトリから、packages/backend/src/index.tsxファイルを開きます。
// catalog pluginというセクションに、@backstage/plugin-catalog-backend-module-github-orgプラグインを追加するする処理を追記しましょう。

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

次に、app-config.local.yamlに以下の設定を追記します。

catalog:
  providers:
    githubOrg:
      id: 'github-local'
      githubUrl: 'https://github.com'
      schedule:
        initialDelay: { seconds: 30 }
        frequency: { minutes: 60 }
        timeout: { minutes: 50 }

上記の設定により、定義されたスケジュールで GitHub のメンバーの情報をBackstageに同期するようにすることができます。
これで、バックエンド側の設定も完了です！

GiHub 認証用のサインイン画面を実装する

それでは、最後に Backstage のソースコードを修正し、ログイン画面で GitHub を使用したログインを選択できるようにしましょう。

Backstage のルートディレクトリから、packages/app/src/App.tsxファイルを開きます。

まずは、@backstage/core-componentsパッケージの import ブロックに移動し、SignInProviderConfigを追記します。
その次の行に、'@backstage/core-plugin-api'のgithubAuthApiRefも新規で追記しましょう。

// SignInProviderConfigをリストに追記
import {
  AlertDisplay,
  OAuthRequestDialog,
  SignInPage,
  SignInProviderConfig,
} from '@backstage/core-components';
// importブロックを新規作成し追記
import { githubAuthApiRef } from '@backstage/core-plugin-api';

続いて、 GitHub 用のサインインボタンを定義するgithubProvider という const を追記します。

const githubProvider: SignInProviderConfig = {
  id: 'github-auth-provider',
  title: 'GitHub',
  message: 'Sign in using GitHub',
  apiRef: githubAuthApiRef,
};

続いて、定義したgithubProvider const をサインインページに表示させるために app const内に変更を加えます。
以下を参考に、githubProviderを追記しましょう。

  // 'guest' の横にカンマを入れ、"githubProvider" を追記
  components: {
    SignInPage: props => <SignInPage {...props} auto providers={['guest', githubProvider]} />,
  },

これでフロントエンドの修正は完了です。
それでは、改めてyarn devコマンドを実行してみましょう。

Backstage のサインイン画面が表示されたら、 GitHub 側の[SIGN IN]をクリックします。

Authorize ≪GitHub App名≫をクリックします。

無事にホームページが表示されれば、成功です！

左ペインの[Settings]をクリックすると、自分の GitHub アカウントも出てくることが分かります。

これで、 GitHub Integration の実装も完了です！

最後に

いかがでしたでしょうか？
GitHub Integrationの実装については少しやることが多かったかもしれませんが、これで GitHub の情報でログインすることもできるようになり、一層便利になりましたね。
とはいえこれはあくまでもローカル上で起動する Backstage インスタンスでできるようになったに過ぎないので、実際のところはチームメンバーもアクセスが可能なところにインスタンスを立ち上げて、同じように Backstage を動かす必要があります。
こちらについては次回のブログで解説できたらと思います。

ここまで読んでいただき、ありがとうございました。

ACS事業部のご紹介

最後にご紹介です。
私の所属するACS事業部では、開発者ポータルBackstage、Azure AI Serviceなどを活用し、Platform Engineering＋AIの推進・内製化のご支援をしております。

www.ap-com.co.jp www.ap-com.co.jp www.ap-com.co.jp

また、一緒に働いていただける仲間も募集中です！
我々の事業部のCultureDeckはこちらです。

www.ap-com.co.jp

今年もまだまだ組織規模拡大中なので、ご興味持っていただけましたらぜひお声がけください。 www.ap-com.co.jp

本記事の投稿者: 青木平
ウイスキーと柔道が好きなITエンジニア。
最近はBackstageやArgoCDに関心があります。

APC 技術ブログ

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

Backstageに入門してみよう：02_PostgreSQLとの接続とGitHub Integrationの実装

はじめに

前提条件

Backstage インスタンスを PostgreSQL と接続する

なぜPostgresSQLへの接続が必要なの？

PostgreSQLのインストールとセットアップ

Backstage に PostgreSQL の設定を行う

GitHub Integration 機能を用いたユーザー認証

Backstage 用 GitHub App を使用した認証情報の準備

GitHub App の作成

GitHub App の認証情報の取得

GitHub App を Organization にインストール

github-credential.yamlに認証情報を入力

GitHub Authentication Provider の実装

バックエンド更新

app-config.local.yaml に GitHub の設定を追記

GitHub Organizational データ連携の実装

GiHub 認証用のサインイン画面を実装する

最後に

ACS事業部のご紹介