初回セットアップの流れ

ベースマキナを実際にご利用の際には、以下のような手順をたどるとよりスムーズにご利用いただけます。

設定には、ベースマキナの画面で設定するものと、コードで管理できるものがあります。

手順1〜5では、接続先・環境・ユーザー・権限を画面から設定します。手順6〜8で、アクション・ビューの作り方と開発の進め方を決めます。

1. bridgeの設定

もしbridgeを利用して、より安全に社内のデータソースへアクセスする場合は、自社のVPC内にbridgeを設置してください。bridgeはコンテナイメージを配布しているため、自由に配置できます。Terraformでデプロイする場合は、Terraformモジュールを利用できます。

詳しい設定方法（必要な環境変数など）は、プロジェクト設定の「ネットワーク設定」で確認できます。

ベースマキナのサーバーがbridgeを通じてデータソースにアクセスできるように、固定IPからのアクセスを許可してください。固定IPのアドレスはIPホワイトリストをご参照ください。

設定が保存できない場合は、トラブルシューティングを参考にしてください。もし解決しない場合は、お気軽にサポートにお問い合わせください。

2. 環境の設定

プロジェクト設定の「環境設定」から、開発環境と本番環境を作成します。環境ごとに、データソースの接続先やレビュー設定を切り替えられます。本番環境へ反映する前に動作を検証したい場合は、検証環境も作成します（手順8の実践的な開発フローで使います）。

あわせて、同じ画面でアクションを開発する環境を「開発環境」に指定します。開発環境を指定すると、アクションの編集やバージョンの設定は開発環境でのみ可能になり、他の環境ではアクションの実行だけができます。コード管理を使うには、開発環境の指定が必要です。

詳しくは開発環境と本番環境を登録すると開発環境をご参照ください。

3. データソースの設定

アクションから接続するデータベースやAPIを、データソースとして登録します。bridgeを利用する場合は、bridgeを通じてアクセスするデータソースを設定してください。

データソースの接続情報は環境ごとに登録します。開発環境と本番環境で、接続先のデータベースを分けられます。詳しくは環境別のデータソース設定をご参照ください。

4. 他のユーザーの追加

企業アカウント設定のユーザー管理画面から必要なユーザーを招待して、その後プロジェクトに追加してください。

CI/CDなど機械からの操作には、ユーザーではなくサービスアカウントを使います。サービスアカウントは手順7で用意します。

4.1. サポートアカウントの設定

ベースマキナからのサポートが必要な場合、企業アカウント設定のユーザー管理画面からサポートアカウントを招待できます。原因調査時にベースマキナ側からお手伝いできます。

5. 組織にあった権限設定（グループの作成）

プロジェクト設定の「グループ管理」から、レビューの承認条件やアクションの実行権限の設定に使うグループを作成します。組織内の事情にあった形で、職種や担当業務などに応じたグループを作成してください。グループにロールを設定すると、アクションや環境の設定を変更できるユーザーを絞れます。詳しくはグループをご参照ください。

本番環境ではアクションの実行前に承認を必須にしたい場合は、プロジェクト設定の「レビュー設定」からレビュー設定も作成します。

6. アクション・ビューの作成

データソースを呼び出すアクションと、業務に合わせた画面であるビューを作成します。作成方法は2つあります。

画面で作成したアクション・ビューも、あとからコード管理に取り込めます。まず画面で試し、運用が固まってからコード管理に移ってもかまいません。

画面を作る機能の選び方は、画面作成機能の使い分けをご参照ください。アクションの実行に失敗する場合は、トラブルシューティングを参考にしてください。もし解決しない場合は、お気軽にサポートにお問い合わせください。

7. コード管理の導入

コード管理では、アクション・ビューの設定をSDK（@basemachina/sdk）の関数を使ってTypeScriptで書き、CLI（@basemachina/cli）のbmコマンドでベースマキナに反映します。詳しい手順と必要な権限は、始め方をご参照ください。

1. プロジェクト設定の「開発設定」を開き、「コード管理」のセットアップガイドに沿って、アクションへの識別子の設定、サービスアカウントの用意とグループへの所属、設定ファイル一式のダウンロードを進めます。

2. ダウンロードしたファイルをGitリポジトリで管理し、ローカルで差分を確認してから開発環境に反映します。

   npm install
   npx bm login
   npx bm sync --dry
   npx bm sync

   初回の反映では、各アクション・ビューの管理方法が「Web管理」から「コード管理」に切り替わります。ダウンロード後に画面で設定を変更していなければ、設定内容は変わりません。

3. CI/CDからbm syncを実行できるように、サービスアカウントにOIDC信頼ポリシーを設定します。GitHub Actionsでは公式のComposite Action basemachina/bm-action (opens in a new tab)を使うと、PRへの差分のコメントとマージ時の反映をまとめて扱えます。GitLab CIにも対応しています。詳しくはCI/CDの設定をご参照ください。

コード管理を始めたあとに画面で作成したアクション・ビューは、bm pullでリポジトリに取り込めます。データソースやグループ、レビュー設定を画面で追加・変更したときも、bm pullを実行すると、設定ファイルから参照する定数（src/bm-refs.ts）が更新されます。

7.1. 反映前に動作を確認する

コード管理では、環境へ反映する前に、手元で動作や差分を確認できます。

bm preview actionはアクションを開発環境で実際に実行するため、書き込みを伴うアクションでは開発環境のデータが変わります。bm-view-previewはビューを保存せず、表示だけを確認するツールです。使い方はbm-view-previewのREADME (opens in a new tab)をご参照ください。

7.2. AIエージェントに作業を任せる

ベースマキナが公開しているスキル（Agent Skill）をClaude CodeなどのAIエージェントに導入すると、次の作業を任せられます。

どのスキルも、アクションの実行や、--dryをつけないbm syncはしません。環境への反映は、レビューを経たCI/CDか、ユーザー自身の操作で実施します。導入方法はAgent Skillをご参照ください。

8. 開発フローを決める

コード管理を始めたら、Gitのブランチとベースマキナの環境の対応を決め、ブランチごとにCI/CDのワークフローを用意します。検証環境を用意する場合は実践的な開発フロー、開発環境と本番環境だけで運用する場合は基本（2ブランチ運用）を参考にしてください。

実践的な開発フローでは、3つのブランチを3つの環境に対応させ、各ブランチへのマージを契機にCI/CDでbm syncを実行します。

日々の開発は、次の流れで進めます。

1. mainから作業用のブランチを作成し、アクション・ビューを編集します。動作確認が済むまで検証環境・本番環境に出したくないアクションは、actionsではなくdevelopmentActionsに指定します。ビューの場合はdevelopmentViewsです。
2. 手順7.1のツールで、アクションの実行結果やビューの表示を確認します。
3. PRを作成すると、CIでbm sync --dryが実行され、開発環境への差分がPRにコメントされます。レビュー後にマージすると、開発環境に反映されます。
4. 開発環境で動作を確認したら、そのアクションをdevelopmentActionsからactionsへ移すPRをmainにマージします。
5. mainをstgに取り込む昇格PRと、stgをprdに取り込む昇格PRをマージして、検証環境、本番環境の順に同期します。

この運用では、次の3つの仕組みで、動作確認前の変更が検証環境・本番環境へ同期されないようにしています。

• developmentActionsに指定したアクションは、他の環境への同期の対象外になる
• --from <検証環境のID>を指定すると、本番環境への同期元が検証環境になる
• --pin-versionを指定すると、同期先のバージョンが同期した時点のものに固定され、開発環境で新しいバージョンを作っても同期先の動作は変わらない

本番環境に反映したあとでバージョンを戻したい場合などの対処は、コード管理のトラブルシューティングをご参照ください。