始め方

コード管理を始めるための手順を説明します。

前提条件

開発環境が設定済みであること
企業アカウントの管理者の権限を持っていること

1. コード管理の開始とOIDC信頼ポリシーの設定

コード管理でのCLIやCI/CDからの認証は、OIDC信頼ポリシーを使用します。OIDC信頼ポリシーは、GitHub Actionsなどの外部サービスが発行したOIDC ID Tokenを、ベースマキナのサービスアカウントと紐づけるためのポリシーです。

右上のメニューから「設定」を選択します。
サイドバーのメニューから「開発設定」を選択します。
「コード管理」セクションの「コード管理を開始する」ボタンをクリックします。これにより、コード管理用のサービスアカウントがプロジェクトに自動作成されます。
サービスアカウント作成後に表示される「OIDC信頼ポリシー」のフォームから、「ポリシーを追加」→「GitHub Actions」または「カスタム」を選択して、ポリシーを追加します。

「コード管理を開始する」ボタンは企業アカウントの管理者のみが操作できます。

サービスアカウントはプロジェクト管理者の権限を持ち、アクションの作成・更新などの操作が可能です。サービスアカウントはベースマキナの画面上のユーザー一覧には表示されず、課金の対象にもなりません。

OIDC信頼ポリシーの設定項目

項目	説明
`Issuer`	OIDC ID Tokenを発行するサービスのURL（例: `https://token.actions.githubusercontent.com`）
`Audience`	ID Tokenの`aud`クレームに含めるAudience（例: `https://basemachina.com`）。企業アカウントごとに固有の値を設定するとトークン悪用を防げる
`Bound Claims`	受け入れるID Tokenの条件を`key`と`pattern`のペアで指定する（1件以上必須）

GitHub Actionsから利用する場合は、「ポリシーを追加」ドロップダウンリストで「GitHub Actions」を選択すると、Issuerなどがあらかじめ入力された状態でポリシーを追加できます。Bound Claimsには、例えばkey: sub、pattern: repo:<org>/<repo>:ref:refs/heads/mainのように、受け付けるブランチ・リポジトリの条件を指定します。

ここで設定したAudienceは、bm-actionのaudience入力やbm syncの認証時に同じ値で要求されます。CI/CD側のワークフローでも同じ値を指定してください。

2. プロジェクトのダウンロード

「開発設定」画面の「コード管理」セクション上部にある「設定のダウンロード」ボタンをクリックすると、プロジェクトの設定ファイル一式（oac-project.zip）をダウンロードできます。

ダウンロードされるファイルの構成は、設定ファイルをご参照ください。

ダウンロードの対象はコード管理対応のアクション種別（gRPC・HTTP API・JavaScript・MySQL・PostgreSQL）のうち、識別子が設定されているものです。識別子が未設定のアクションはダウンロードされないため、同じ画面にある「識別子の一括設定」から事前に識別子を設定してください。

3. リポジトリの作成とセットアップ

ダウンロードしたファイルをGitリポジトリとして管理します。

# リポジトリを作成
git init
git remote add origin <リモートリポジトリのURL>
 
# 依存関係をインストール
npm install
 
# 初回コミットとプッシュ
git add .
git commit -m "Initial commit"
git push -u origin main

ダウンロードしたpackage.jsonには、npmで公開されている@basemachina/sdk (opens in a new tab)と@basemachina/cli (opens in a new tab)の依存関係が含まれています。通常はnpm installでそのままインストールできます。

セットアップ後にWeb UIで作成したアクションをコード管理へ取り込みたい場合は、bm pullを使用します。bm pullは標準のsrc/actions/、src/bm-refs.ts、type.d.tsを更新対象にするため、取り込み運用を使う場合はこれらのパスを維持することを推奨します。

4. CI/CDからの認証の準備

GitHub Actionsからbm syncを実行する場合は、公式のComposite Action basemachina/bm-action (opens in a new tab)を使うのが簡単です。bm-actionがOIDC ID Tokenの取得・bm syncの実行・PRへのコメント投稿を一括で行ないます。

ワークフローにはid-token: writeのパーミッションを付与します。具体的なワークフローの書き方は、CI/CDの設定と運用例をご参照ください。

bm-actionを使わずに自前でCI/CDを構成する場合は、CI/CDが発行したOIDC ID Tokenを環境変数 BM_OIDC_TOKEN に設定してbm syncを実行します。

ローカルからCLIを実行する場合は、bm loginでブラウザログインするとトークンが~/.basemachina/credentials.jsonに保存されます。以降はそのトークンが自動で利用されるため、BM_OIDC_TOKENの設定は不要です。

5. 初回の反映

セットアップが完了したら、PRを作成してコード管理を開始します。

PRを作成すると、CIでbm sync --dryが実行され、設定の差分がPRにコメントされます。
初回は各アクションの管理方法が「Web管理」から「コード管理」に移行する差分が表示されます。
PRをマージすると、bm syncが実行されて管理方法が更新されます。

初回の反映では、管理方法の変更のみが行なわれます。アクションの設定内容自体は変更されません。ダウンロード後に画面上で設定を変更した場合は、差分として検出されます。

6. 必要に応じてWeb管理のアクションを取り込む

コード管理の開始後も、Web UIでアクションを新規作成することがあります。設定ファイルにまだ存在しないWeb管理アクションは、ローカルでbm pullを実行するとコード管理用のファイルとして取り込めます。

bm pull

bm pullは取り込み予定を表示し、確認後にsrc/actions/配下の新規ファイル、src/bm-refs.ts、type.d.ts、設定ファイルへの追記を適用します。詳しくはbm pullをご参照ください。

これで、以降はコード管理の運用に沿って開発を進められます。詳しくは運用例をご参照ください。

コード管理とは設定ファイル