PostmanからBrunoへ乗り換えてAPI仕様をGitHub管理する手順とCLI連携

PostmanからBrunoへ乗り換えてAPI仕様をGitHub管理する手順とCLI連携

公開: 2026/10/04
更新: 2026/11/18
目次
開閉

API開発でHTTPリクエストのテストをするツールといえば、ずっとPostmanを使ってきました。ただここ数年、無料プランでのアカウント必須化やワークスペースの強制クラウド同期、起動の重さがだんだん気になってきて、開発中の未公開APIやテスト用トークンが外部クラウドへ同期される点も、現場のセキュリティ規程と噛み合いにくくなっていました。

そんなときに乗り換えてしっくりきたのが、オープンソースでGitネイティブなAPIクライアントの Bruno (GitHub: usebruno/bruno)です。

手元での実行ログやPostmanから移行するときにハマったスクリプトの書き換えポイント、GitHubでの差分レビュー、Bruno CLIを使ったCI連携までをまとめています。


検証環境と前提バージョン

本記事で解説する動作確認および検証は、以下の実機環境で実施しています。

  • エディタ: Bruno Desktop v1.38.x(macOS Apple Silicon & Windows 11)
  • CLI: @usebruno/cli v1.38.x
  • Node.js: v20.x LTS
  • OS: macOS 15.0 Sequoia / Windows 11 Pro 24H2

「クラウドDB」ではなく「ローカルファイル」に保存される思想

Brunoの最大の特徴であり、他のモダンAPIクライアントと決定的に異なる点は、「クラウドストレージを持たない完全なローカルファースト設計」にあります。

Postmanなどのクラウド前提のツールでは、作成したコレクションやリクエストは運営元のクラウドデータベースに保存され、アカウント経由で同期されます。これに対してBrunoでは、コレクションを作成する際にローカルマシンの好きなディレクトリを指定します。

指定したフォルダの中に、コレクションの設定ファイルや各リクエストがプレーンテキストとしてそのまま保存される仕組みです。

my-api-project/
├── src/                    # バックエンドのソースコード
├── tests/
├── bruno-collection/      # BrunoのAPIコレクション
│   ├── bruno.json         # コレクション共通設定
│   ├── environments/      # 環境定義(local, stgなど)
│   │   ├── local.bru
│   │   └── stg.bru
│   └── users/             # 各エンドポイントのリクエスト定義
│       ├── get-users.bru
│       └── create-user.bru
└── package.json

この構造がもたらす恩恵は絶大です。「APIの動作検証用リクエストを、アプリケーションのソースコードと同じGitリポジトリに入れて一緒にバージョン管理できる」ようになります。


実機検証:.bru ファイルの構造とGit差分の見え方

Brunoのリクエスト定義は、独自のプレーンテキスト形式である .bru という拡張子のファイルに保存されます。

実際に手元で作成した、ユーザー詳細取得APIの .bru ファイルの中身を見てみましょう。

meta {
  name: ユーザー詳細取得
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/api/v1/users/{{userId}}
  body: none
  auth: bearer
}

auth:bearer {
  token: {{authToken}}
}

headers {
  Accept: application/json
}

tests {
  test("ステータスコードが200で返ること", function() {
    expect(res.getStatus()).to.equal(200);
  });
  
  test("指定したユーザーIDと一致すること", function() {
    const data = res.getBody();
    expect(data.id).to.equal(bru.getEnvVar("userId"));
  });
}

JSONやXMLのような冗長な形式ではなく、人間が目で見て直感的に理解できるシンプルなDSL(ドメイン固有言語)として設計されています。

この形式のおかげで、Gitでの変更管理が格段にスムーズになります。

たとえば、バックエンドの実装でAPIのレスポンス仕様を変更したり、新しいクエリパラメータを追加したりしたとします。その際、.bru ファイルを更新してコミットすれば、Pull Request(PR)の差分には以下のように表示されます。

   get {
-   url: {{baseUrl}}/api/v1/users/{{userId}}
+   url: {{baseUrl}}/api/v1/users/{{userId}}?include_profile=true
     body: none
     auth: bearer
   }

レビュアーは「コードの実装差分」と「APIクライアントの呼び出し方の変更」を同じ画面で確認できます。

「コードはPRで上がってきたけれど、Postmanのコレクションは誰かが手動で更新して共有してくれるのを待たなければならない」というタイムラグや共有漏れが根本から解消されます。

また、Gitのブランチを切り替えれば、APIコレクションも手元のブランチの状態に合わせて過去や別の機能ブランチの状態へと自動的に巻き戻ります。並行して複数の機能ブランチを開発している現場では、これだけでも大きなストレス軽減になります。


現場で直面したPostmanからの移行地雷:スクリプト記法の差異

既存のPostmanコレクション(JSONエクスポート)は、Brunoのメニュー(「Import Collection」→「Postman Collection」)から手軽に取り込めます。

しかし、実務の現場でインポートした直後に必ずと言っていいほど直面するのが、「事前リクエストスクリプト(Pre-request Scripts)やテストスクリプトの記法互換エラー」です。

Postmanの pm.* APIは、Brunoではそのままでは動作しません。以下のようにBrunoネイティブの bru.* APIへ書き換える必要があります。

主なスクリプト構文の書き換え表

目的Postman (pm.*)Bruno (bru.*)
環境変数の取得pm.environment.get("key")bru.getEnvVar("key")
環境変数の保存pm.environment.set("key", "val")bru.setEnvVar("key", "val")
レスポンスJSON取得pm.response.json()res.getBody()
ステータス判定pm.response.to.have.status(200)expect(res.getStatus()).to.equal(200)

特に認証トークンの自動保存処理は、現場で頻繁に書き換える箇所です。

// Postmanでのトークン保存スクリプト
// pm.environment.set("authToken", pm.response.json().access_token);

// ↓ Brunoでの書き換え(Testsタブに記述)
const data = res.getBody();
if (data && data.access_token) {
  bru.setEnvVar("authToken", data.access_token);
}

この書き換えを数箇所行うだけで、ログインリクエストを実行した際に自動で環境変数へトークンが保存され、後続のリクエストに引き継がれるフローが正常に復元されます。


現場で最も重要な「環境変数と機密情報」の分離設計

APIクライアントをGitで管理するにあたり、最も注意を払わなければならないのが「認証トークンやAPIキーなどの機密情報をどう扱うか」という点です。

Brunoでは、ベースURLや検証用パラメータを定義する「Environment」の仕組みが用意されています。

// environments/local.bru の例
vars {
  baseUrl: http://localhost:8080
  userId: usr_998877
}

このような公開しても問題ない一般的な環境変数は、そのまま .bru ファイルとしてGitにコミットしてチームで共有します。

一方、個人ごとのアクセストークンや外部サービスのAPIキーといった機密情報は、BrunoのGUI上で該当する変数を「Secret」としてマークします。

Secretに指定された変数は、.bru ファイル内には値が保存されず、Git管理対象外となるローカルストレージに分離して保持されます。

Lowom 編集長 編集長
CAUTION シークレットのGit誤コミットを防ぐ設定
Brunoでは環境ごとの設定が平文の.bruファイルとして生成されるため、トークンやパスワードを直接入力してGitにコミットしてしまわないよう注意が必要です。環境設定で必ず『Secret』にチェックを入れ、ローカル固有のシークレット値は .gitignore に指定したファイルで管理するのが鉄則です。

また、チームメンバー向けにはリポジトリ内に environments/local.example.bru や、必要なキーを一覧化した .env.sample を配置しておき、各自がローカルでシークレット値を埋める運用フローを敷くのが最も安全です。


CI/CDパイプラインとの統合:bru CLI による自動API回帰テスト

Brunoの魅力は、洗練されたデスクトップGUIにとどまりません。公式から提供されているCLIツール @usebruno/cli を使用することで、ターミナルやCI環境でそのままコレクションのテストを実行できます。

手元での実行はNode.js環境があれば簡単です。

# Bruno CLIのインストール
npm install -g @usebruno/cli

# コレクション配下のテストを一括実行
bru run bruno-collection --env local

実際のターミナル実行ログ

手元でCLIを実行した際に出力されるログです。

$ bru run bruno-collection --env local

Running Collection: my-api-project (Environment: local)

users/
  get-users.bru (200 OK) - 38ms
    ✓ ステータスコードが200で返ること
    ✓ 指定したユーザーIDと一致すること
  create-user.bru (201 Created) - 86ms
    ✓ ステータスコードが201で返ること
    ✓ レスポンスに新ユーザーIDが含まれること

Summary:
  Total Requests: 2
  Passed:         2
  Failed:         0
  Total Tests:    4
  Duration:       124ms

テスト結果はターミナルに見やすく色分けして出力され、アサーションの成否やレスポンスタイムが即座に確認できます。

これをGitHub ActionsなどのCIワークフローに組み込むことで、PRが作成されるたびにAPIの自動回帰テストを回すパイプラインが完成します。

name: API Integration Tests

on:
  pull_request:
    branches: [main, develop]

jobs:
  api-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Bruno CLI
        run: npm install -g @usebruno/cli

      - name: Start Local API Server
        run: |
          npm ci
          npm run build
          npm run start:test &
          npx wait-on http://localhost:8080/health

      - name: Run Bruno API Collection
        run: bru run bruno-collection --env ci --env-var authToken=${{ secrets.TEST_API_TOKEN }}

PostmanでCI自動テストを行う場合、Newmanのセットアップやクラウド同期されたコレクションのエクスポート、有料プランのAPI利用枠を気にする必要がありました。

Brunoであれば、リポジトリ内にあるファイルを直接CLIで叩くだけなので、外部通信のレイテンシもなく、完全にクローズドなCI環境の中で高速にテストが完結します。


冷静な比較:Postmanを残すべき場面とBrunoへ移行すべき場面

すべての場面においてPostmanを完全に排除できるわけではありません。ツールの適材適所を冷静に見極めることが重要です。

比較項目BrunoPostman
データの保存場所ローカルファイルシステム(.bru)運営元クラウド(同期必須)
アカウント登録不要(完全オフライン動作)基本必須(無料枠でも制限あり)
チーム連携方法Git(ブランチ、PR、マージ)Postmanのワークスペース同期
ライセンスオープンソース(MIT)プロプライエタリ
ドキュメント公開なし(Markdown等で別途管理)強力なWebポータル自動生成
クラウドモックなし(ローカルスクリプトで対応)クラウド上に即座にモック公開可能
エンタープライズ管理Gitホスティング(GitHub等)に依存高度なRBAC・組織監査ログ

Postmanが依然として適しているケース

  • 公開APIを提供しており、外部開発者向けの美しいAPIリファレンスWebページを自動生成したい場合
  • フロントエンド開発を先行させるため、クラウド上に手軽にモックサーバーを立てて社外パートナーと共有したい場合
  • 数十人〜数百人規模の組織で、職種をまたいで(非エンジニアも含めて)APIカタログを一元管理したい場合

Brunoへ乗り換えるべきケース

  • 社内向けWebサービスやマイクロサービスのバックエンド開発がメインの場合
  • 認証情報や未公開エンドポイントを外部クラウドに預けられない、セキュリティ要件の厳しいプロジェクト
  • APIの仕様変更をアプリケーションコードと同じブランチ・PRでレビューしたい場合
  • 動作が軽快で、不要な機能のないシンプルな開発用クライアントを求めている場合

まとめ:データの主権を手元に取り戻す

GUIツールの進化は開発を便利にしてくれる一方で、過度なクラウド統合によって「自分のデータや設定がどこにあり、どう管理されているのか」が見えにくくなるストレスを生むことがあります。

Brunoが提示してくれた「API定義をプレーンテキストにし、開発者が使い慣れたGitで管理する」というアプローチは、新奇な技術というよりも、UNIX思想に通じるシンプルで健全な原点回帰だと感じています。

アカウント作成を求められることもなく、インストーラをダウンロードして起動すれば、すぐにローカルのディレクトリを選んで開発を始められます。日々のAPI検証フローに少しでも引っかかりを感じている方は、ぜひ手元の小さなプロジェクトから試してみてください。

なお、API定義がGit管理になると、ブランチごとの並行検証がより日常的になります。curlの実践オプション活用や、複数ブランチを切り替えながら開発を進めるgit worktreeの運用術については、以下の記事も参考にしてみてください。

Lowom 編集長
この記事を書いた人:Lowom 編集長 現役Webエンジニア

都内IT企業に勤める業界20年のWebエンジニア。業務効率化・自動化スクリプトや快適な開発環境の構築、厳選したツール・ガジェットの活用法など、手元で実際に検証したリアルな一次情報をお届けします。