始め方
コード管理を始めるための手順を説明します。
前提条件
- 開発環境が設定済みであること
- 企業アカウントの管理者の権限を持っていること
1. サービスアカウントとOIDC信頼ポリシーの用意
コード管理では、CLIやCI/CDからの操作をサービスアカウントとして行ないます。コード管理を始める前に、サービスアカウントを用意し、アクション管理権限を持つグループへ所属させてください。
CI/CDからコード管理を行なう場合は、OIDC信頼ポリシーの設定も必要です。ローカルからbm syncを実行するだけであれば、OIDC信頼ポリシーの設定は不要です。
2. プロジェクトのダウンロード
「設定」→「開発設定」を開くと、「コード管理」セクションにセットアップガイドが表示されます。ガイドの「設定をダウンロードする」ステップにある「設定ファイル一式のダウンロード」ボタンをクリックすると、プロジェクトの設定ファイル一式（oac-project.zip）をダウンロードできます。
ダウンロードされるファイルの構成は、設定ファイルをご参照ください。
ダウンロードの対象は、コード管理対応のアクションのうち識別子が設定されているものです。識別子が未設定のアクションはダウンロードされないため、同じ画面にある「識別子の一括設定」から事前に識別子を設定してください。
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 pullbm pullは取り込み予定を表示し、確認後にsrc/actions/配下の新規ファイル、src/bm-refs.ts、type.d.ts、設定ファイルへの追記を適用します。詳しくはbm pullをご参照ください。
これで、以降はコード管理の運用に沿って開発を進められます。詳しくは運用例をご参照ください。