実践的な開発フロー

main、stg、prdの3つのブランチで、開発環境・検証環境・本番環境を管理する運用例です。

開発環境で動作確認を済ませたアクションだけを、検証環境・本番環境へ順に昇格させます。defineConfigのdevelopmentActionsとbm syncの--fromオプションを組み合わせることで、複数の作業者が並行して開発しても、動作確認前の変更が検証環境・本番環境に混ざりません。

ブランチと環境の対応

この運用では、アクションの動作確認の状態を設定ファイルの2つのフィールドで管理します。

開発フローの全体像

developmentActionsで開発したアクションを開発環境で動作確認し、確認が済んだものだけをactionsへ移して検証環境・本番環境へ昇格させる流れです。

重要な役割を担うオプション

bm sync <環境ID>は、同期先のすべてのアクションのバージョンと有効化設定を同期元の状態に合わせます。そのため、なにも対策をしないと、動作確認が済んでいないアクションまで検証環境・本番環境へそのまま同期されてしまいます。この運用例では、次の2つのオプションでこれを防ぎます。

developmentActions

defineConfigのdevelopmentActionsは、開発環境で動作確認中のアクションを他環境への同期から除外するためのフィールドです。

• 開発環境への反映（環境IDを指定しないbm sync）では、actionsと同様に反映されます。開発環境での動作確認は通常どおり行なえます
• 他環境への同期（bm sync <環境ID>）では対象外となり、同期先環境には反映されません

詳細はdefineConfigとbm syncをご参照ください。

--from

bm sync <環境ID>の同期元は、--fromを省略すると開発環境になります。本番環境への同期で--from <検証環境のID>を指定すると同期元が検証環境になるため、検証環境での確認を通過した状態だけが本番環境へ昇格します。開発環境にしか存在しない変更が、本番環境へ直接同期されることはありません。

作業シナリオ

作業者Aが新しいアクションupdate-user-statusを、作業者Bが新しいアクションexport-ordersを並行して開発しているとします。

両方を最初からactionsに入れてmainにマージしていると、Aの動作確認が完了してmainをstgへマージした時点で、動作確認が済んでいないBのアクションまで検証環境に同期されてしまいます。developmentActionsを使うと、次の流れでAのアクションだけを昇格できます。

ステップ2時点のbasemachina.config.tsは次のようになります。

import { defineConfig } from "@basemachina/sdk/oac";
import { listUsers } from "./src/actions/list-users";
import { updateUserStatus } from "./src/actions/update-user-status";
import { exportOrders } from "./src/actions/export-orders";
 
export default defineConfig({
  project: {
    id: "your-project-id",
  },
  // 動作確認済み。検証環境・本番環境への同期対象
  actions: [listUsers, updateUserStatus],
  // 動作確認中。開発環境にのみ反映される
  developmentActions: [exportOrders],
});

Bの動作確認が完了したら、同様にexportOrdersをactionsへ移すPRをマージし、次の昇格PRで検証環境へ同期します。

開発環境への変更

1. featureブランチで開発

mainからfeature/xxxブランチを作成し、アクションやビューの設定を編集してPRを作成します。動作確認が済むまで検証環境・本番環境に出したくないアクションは、actionsではなくdevelopmentActionsに指定します。

2. CIで差分を確認

PRが作成されると、CIでbm sync --dryが実行され、設定の差分がPRにコメントされます。開発環境への反映内容なので、コメントのヘッダーは## bm sync 実行後、以下の変更が適用されますです。

3. マージして開発環境に反映

PRをマージすると、CDでbm syncが実行され、アクションの変更がベースマキナの開発環境に反映されます。developmentActionsのアクションも、開発環境へはactionsと同じルールで反映されます。新しいバージョンが作成され、開発環境では常に最新バージョンが使用されるため即時反映されます。設定ファイルから削除されたアクションは、--with-disable指定時のみ開発環境で無効化されます。

4. 開発環境で動作確認

開発環境でアクションを実行し、動作を確認します。動作確認が済んでいないアクションがdevelopmentActionsにある状態で昇格PRがマージされても、検証環境には同期されません。

検証環境への変更

開発環境で確認が取れたら、検証環境に同期します。

検証環境への変更は、mainブランチをstgブランチへ取り込む昇格PRとして作成します。stgブランチで設定ファイルやアクションコードを直接編集する運用は避けてください。

1. 動作確認済みのアクションをactionsに移す

動作確認が済んだアクションをdevelopmentActionsからactionsへ移すPRを作成し、mainへマージします。

2. 昇格PRの作成

stgブランチにmainをマージするPRを作成します。

3. マージして検証環境に同期

PRをマージすると、CDでbm sync <検証環境のID>が実行され、検証環境のすべてのアクションのバージョンと有効化設定が開発環境の状態に合わせて同期されます。developmentActionsのアクションは同期対象外のため、動作確認中のアクションが検証環境に反映されることはありません。

ビューのコードも同じリポジトリで管理している場合は、同じワークフローで検証環境用のストレージへのアップロードも行なえます。

本番環境への変更

検証環境で確認が取れたら、本番環境に同期します。

本番環境への変更は、stgブランチをprdブランチへ取り込む昇格PRとして作成します。

1. PRの作成

prdブランチにstgをマージするPRを作成します。

PR作成時にbm sync --dry <本番環境のID> --from <検証環境のID>を実行すると、本番環境への同期内容がPRにコメントされます。環境間の同期内容なので、コメントのヘッダーは## bm sync 実行後、以下の変更が同期されますです。

2. マージして本番環境に同期

PRをマージすると、CDでbm sync <本番環境のID> --from <検証環境のID>が実行され、本番環境のすべてのアクションのバージョンと有効化設定が検証環境の状態に合わせて同期されます。--from <検証環境のID>により同期元は検証環境になるため、開発環境にしかない変更やdevelopmentActionsのアクションが本番環境へ直接同期されることはありません。

ビューのコードも同じリポジトリで管理している場合は、同じワークフローで本番環境用のストレージへのアップロードも行なえます。

コード管理した設定のWeb上での変更

コード管理している設定は、引き続きWeb上（ベースマキナの管理画面）からも変更できます。

Web上で変更すると、そのアクションの管理方法は一時的に「Web管理」に戻ります。次回のbm syncで、設定ファイルに差分があれば「コード管理に移行（変更あり）」として設定を上書きし、差分がなければ「コード管理に移行（変更なし）」として管理方法だけを戻します。

Web UIで新しく作成したアクションを設定ファイルに取り込みたい場合は、ローカルでbm pullを実行し、生成されたファイルを通常のPRに含めてレビューします。

コード管理を開始した後は、設定の変更はコードで行なうことを推奨します。

CI/CDの設定例

developmentActionsを使う場合も、CI/CDの設定に変更は不要です。他環境への同期時の除外はbm syncが自動で行ないます。

GitHub Actionsの設定ファイル例

以下は.github/workflows/に配置するワークフローファイルの例です。公式Composite Action basemachina/bm-action (opens in a new tab)を使い、OIDC認証・bm sync実行・PRコメント投稿を一括で扱います。認証の詳細はGitHub Actionsをご参照ください。

開発環境への反映（.github/workflows/sync-dev.yml）

name: Sync to dev
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          with-disable: "true"

検証環境への同期（.github/workflows/sync-stg.yml）

name: Sync to stg
on:
  push:
    branches: [stg]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          environment-id: "${{ vars.BM_STG_ENV_ID }}"

本番環境への同期（.github/workflows/sync-prd.yml）

name: Sync to prd
on:
  pull_request:
    branches: [prd]
  push:
    branches: [prd]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          environment-id: "${{ vars.BM_PRD_ENV_ID }}"
          from: "${{ vars.BM_STG_ENV_ID }}"

環境IDはGitHub Actionsの変数 (opens in a new tab)などで管理することを推奨します。