はじめに
これは、Postman v12で登場したネイティブGit連携のハンズオン記事です。
これまで、API仕様・テスト・モック・コレクションといったPostmanの成果物はPostman Cloud上で管理していましたが、v12のネイティブGit統合により、通常のアプリケーションコードとまったく同じように、Gitのブランチやプルリクエストで管理できるようになりました。
本記事ではコードファーストアプローチ（既にAPIのソースコードがある前提でPostmanの活用を進める）で、Git連携のセットアップからCI/CDによる自動化まで、一通り体験します。
なお、ネイティブGit連携の概念については以下の記事でわかりやすく解説されているので、まず参照ください。
ネイティブGit連携のポイント整理とコラボレーションの流れ
ハンズオンに入る前に、ネイティブGit連携を活用した開発フローを理解するうえで基本となる考え方を紹介します。とりあえず理屈より先に手を動かしたいという方はここを読み飛ばしていただいてもOKです。
コラボレーション（共同作業）の種類
Postmanでのコラボレーション（共同作業）は、API（Application Programming Interface）のインターフェース設計・テスト・ドキュメントを中心に行うものです。その具体的な内容や登場人物は、APIライフサイクルのステージによって異なります。
ネイティブGit連携は、GitをベースにAPIのソースコードと同じようにPostmanの成果物を扱うことから、主に開発者向けの機能になります。一方、FEを含めAPIの連携先のチームだったり、企画やQA担当者、パートナーとのAPI共同作業・反復作業においては、Gitを活用しないケースも多いでしょう。そのようなGitを使わないメンバーとの共同作業は、これまでと同じようにPostman Cloud経由で行えます。
大きく分けると、コラボレーションには次の2種類があります。
| 作業の種類 | 主な手段 |
|---|---|
| コードの共同作業（開発者同士） | Gitベース開発 |
| APIインターフェースの反復作業（API開発チームと社内企画・QAチームやパートナー連携など） | Postman Cloud経由のコラボレーション |
ネイティブGit連携によるコラボレーションのポイント
ポイントを整理します。Postmanを活用したコラボレーションの基盤はPostman Cloudワークスペースです。Git連携パターンでも、Gitリポジトリは必ずワークスペースとリンクさせて作業を行います。Gitを使わないチームメンバーとの共同作業は、Postman Cloudのワークスペースを通じて行います。
また、Gitベースの開発においては、GitリポジトリがSingle Source of Truth（SSoT） になります。コレクション・環境・その他のPostmanデータはコードと共にGitリポジトリに保存され、プルリクエストを通じて更新します。さらに、Gitリポジトリに保存されたPostmanの成果物は、CI経由でPostman Cloudに同期するのが基本です。前述のとおり、コラボレーションの基盤はPostman Cloudワークスペースであり、APIの共同反復作業ではPostman Cloud経由のコラボレーションが基本であるためです。
以下、全体の概略図になります。
ネイティブGit連携によるコラボレーションの流れ
- [初回のみ] 共同開発メンバーがアクセス可能なワークスペースとGitリポジトリを作成し、ローカル環境にclone。ワークスペースとGitリポジトリをリンク（紐づけ）する
- 作業用ブランチを作成し、Postmanコレクション・環境・モック・Spec Hubなどを活用してローカルで開発・テストを実施。APIコードとともにPostmanデータをローカルリポジトリに保存
- ブランチをリモートにpushし、プルリクエスト経由でリリースブランチ（もしくはマージ先ブランチ）にマージ
- そのイベントをトリガーにCIが実行され、ローカルの開発内容がCI経由でPostman Cloudに同期
なお、開発者メンバーが機能開発を行う場合は、上記フローの2〜4を繰り返します。
1. 事前準備
必要なもの
- Postmanアカウント
- GitHubアカウント
- チームで共有可能なワークスペース（Internal ワークスペース）
- Gitリポジトリとそのclone
Postmanワークスペースの作成
チームメンバーがアクセス可能なワークスペースを作成します。ワークスペースタイプは Internal を選択します。Internalワークスペースでは、共同開発したいチーム、または特定のメンバーを招待して作業できます。
手順: PostmanアプリのヘッダーにあるWorkspace をクリック → Create をクリック
ハンズオン用のGitHubリポジトリの作成
まずは、プライベートな空のGitリポジトリを作成して、リポジトリ用フォルダーに移動します。
ここではghコマンドでレポジトリを作成しています。ghコマンドを使わない人は、直接GitHubサイトで作成してください。またリポジトリ名はpostman-git-showcasとしてますが、お好きな名前でどうぞ。
# Privateな空のリモートリポジトリを作成してローカルにclone
gh repo create postman-git-showcase --private --clone
# リポジトリ用フォルダーに移動
cd postman-git-showcase
次に、サンプルAPIのソースパッケージをダウンロードして、APIのソースファイルをプロジェクトに追加して、その内容をmainブランチにpushします。
# サンプルAPIコードをダウンロードしてリポジトリの作業フォルダーにコピー
curl -OL https://github.com/yokawasa/postman-git-code-first-showcase/archive/refs/tags/api-code.zip && unzip -j api-code.zip && rm api-code.zip
# APIファイルを追加、mainブランチにpush
git add *
git commit -m "Initial commit"
git push origin main
次に、作業用ブランチを作成します。ここではfeature/api-testingという名前のブランチを作成します。
git checkout -b feature/api-testing
2. Connect Git（ワークスペースとGitリポジトリの紐づけ）
「1.事前準備」で作成したハンズオン用のワークスペースとGitリポジトリの紐づけを行います。
- Postmanアプリのフッターにある [Connect Git] をクリック
- [Open folder] が表示されるので、クリックしてGitリポジトリを選択
- [Connect to workspace] が表示されるのでクリック → ワークスペースとGitリポジトリが紐づけられる
紐づけが完了すると、サイドバーメニューのローカルファイルに下図のようなSetupガイドページが表示されます。サイドバーにはファイル一覧が、フッターにはGitリポジトリの現在のブランチが表示されます（ここでは、Setupガイドは無視して次に進みます）。
紐づけの解除方法
サイドバーメニューのローカルファイル → [⋯] → Disconnect を選択することで紐づけを解除できます。
3. Postmanコレクションの作成
ここでは Agent Mode(PostmanのAIエージェント機能) を使ってPostmanコレクションを作成します。
＊ Agent Modeの基本については、Postman Agent Mode入門シリーズで詳しく解説しているので興味のある方は一読ください。
事前確認: AI設定をオンにする
Postmanの設定でAI機能がオンになっていることを確認します。
Agent Modeでコレクションを作成
- 右サイドバーのAIアイコンをクリックしてChatウィンドウを開く（右サイドバーが表示されていない場合はフッターの右サイドバー表示アイコンをクリック）
- 次のプロンプトを入力する
このプロジェクトのAPIサーバーのソースコードに基づいてコレクションを作成してください
途中、Auto-Runが有効化されていない場合は確認が促されます。
作成が完了すると、サイドバーの [ローカルアイテム] アイコンをクリックし、コレクション部分をトグルすると作成されたコレクション（例: Poll API）が表示されます。
4. APIの手動テスト
APIサーバーの起動
ターミナルを開き、APIサーバーを起動します。
# npmパッケージのインストール
npm install
# APIサーバーの起動
npm start
補足：Postmanアプリのフッターにある [Terminal] からもターミナルが利用可能です。画面を切り替える手間が省けるため、ぜひ活用してみてください。
テストの実行
まずは、手動でAPIリクエストを実行して結果を確認します。
手順: 各APIリクエストを送信（[Send] ボタンをクリック） → レスポンスメニューのTest Resultsでテスト結果を確認
次に、Postmanのコレクションランナーを使って、コレクション全体のテストを実行します。
手順: コレクションを選択 → [⋯] → Run を選択 → [Start run] ボタンをクリック
これで、コレクションランナーがコレクションのテスト実行を開始します。そして、各APIリクエストのテスト結果を一覧で確認できます。
5. Postman Cloudへの同期
ローカルファイルシステム上で作業しているPostmanアイテムをPostman Cloudに同期します。
同期の手順
- ワークスペースを開き、フッターにある [Push to Postman Cloud] をクリック
- Pushしたいアイテム（ここではコレクション）を選択して [Push] ボタンをクリック
特にエラー表示がなければ、その時点のローカルのPostmanコレクションがPostman Cloudに同期されているはずです。
Local View / Cloud Viewの切り替え
下記の手順でLocal ViewからCloud Viewに切り替えます。Cloud Viewで表示されるコレクションの内容が、ローカルのコレクションと同じであることを確認ください。
- フッターのブランチ名をクリック → [Postman Cloud] をクリックするとCloud View（Postman Cloud上のアイテム）に切り替わる
- [Switch to Local] をクリックするとLocal Viewに戻る
6. Postman CLIでテスト実行＆Postman Cloudに同期
これまでPostmanアプリのUIで行ってきた操作を、今度は Postman CLI で実行します。CI/CDパイプラインでのテスト実行やPostman Cloudへの同期はPostman CLIを経由して行うため、パイプラインに組み込む前に、まずは手動で実行してみましょう。
Postman CLIのインストール
公式ページの手順 に従いインストールします。npmが使える環境では次のコマンドでインストールできます。npmが使えない環境の方は、npmが使えない環境の場合は、公式の手順から適切な方法を選択してください。
npm install postman-cli@latest -g
[補足] -gでグローバルにインストールされます。不要な場合は、-g を省略してください。なお、npmで-gを付けずに（ローカルに）インストールした場合、以降の手順でpostmanコマンド実行時に、npx postmanと打ってください。
Postman CLIでコレクションテストを実行
次の手順で、Postman CLIでコレクション（Poll API）を実行します。
# コレクションの実行
# postman collection run <collectionIDまたはパス>
postman collection run postman/collections/Poll\ API
-
postman/collections/Poll\ APIはローカルファイルシステム上でのコレクションファイルが格納されているフォルダーへの相対パス
コレクションの実行が成功すると、次のような結果が出力されます。
→ Get Poll Results
GET http://localhost:3000/polls/1 [200 OK, 414 B, 1 ms]
✓ Status code is 200
✓ Response has question and options properties
✓ Options array contains vote counts
┌─────────────────────────┬───────────────────┬───────────────────┐
│ │ executed │ failed │
├─────────────────────────┼───────────────────┼───────────────────┤
│ iterations │ 1 │ 0 │
├─────────────────────────┼───────────────────┼───────────────────┤
│ requests │ 3 │ 0 │
├─────────────────────────┼───────────────────┼───────────────────┤
│ test-scripts │ 3 │ 0 │
├─────────────────────────┼───────────────────┼───────────────────┤
│ prerequest-scripts │ 0 │ 0 │
├─────────────────────────┼───────────────────┼───────────────────┤
│ assertions │ 7 │ 0 │
├─────────────────────────┴───────────────────┴───────────────────┤
│ total run duration: 245 ms │
└─────────────────────────────────────────────────────────────────┘
Postman CLIでワークスペースをPostman Cloudに同期
postman workspace push を使います。このコマンドはローカルファイルを検証し、クラウドワークスペースと同期します。実行にはpostman login でのログインが必要です。
postman login
postman workspace push
もし、CI/CD環境で確認プロンプトをスキップしたい場合は 次のように、-y または --yes オプションをつけて実行します。
postman workspace push -y
npm scriptsへのコマンド追加
よく使うコマンドは、package.json のnpm scriptsに追加しておくと便利です。
"scripts": {
"start": "node app.js",
"start:daemon": "pm2 start app.js --name poll-api",
"stop:daemon": "pm2 stop poll-api",
"restart:daemon": "pm2 restart poll-api",
"postman:test": "postman collection run postman/collections/Poll\\ API",
"postman:publish": "postman login && postman workspace push"
}
これで、次のようにnpm runコマンドでコレクションテストや同期が実行できます。
npm run postman:test
npm run postman:publish
7. CIの設定（GitHub Actions）
次に、コレクションのテストや Postman Cloud への同期を CI パイプラインで実行するための設定を行います。CI のトリガーイベントと実行内容は以下の通りです。
| イベント | 実行内容 |
|---|---|
| PRの作成・更新（main 向け） | (マージ前処理) コレクションを実行し、コレクションのテストに問題がないことをチェック |
| mainへのマージ | （マージ後処理）コレクションテスト ＋ ローカルのPostmanアイテムをPostman Cloudへ同期 |
GitHub Actions ワークフローファイルの作成
次の内容の.github/workflows/postman.ymlを作成します。
name: "Postman CI"
on:
# PRの作成・更新時にAPIテストを実行
pull_request:
branches:
- main
# mainへのマージ時にAPIテスト＋Postman Cloudへのpushを実行
push:
branches:
- main
jobs:
automated-api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v3
with:
node-version: '24.x'
- name: Install dependencies
run: npm install
- name: Start API server as daemon
run: npm run start:daemon
- name: Install Postman CLI
run: curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
- name: Verify Postman CLI version
run: postman --version
- name: Login to Postman
run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
- name: Run API tests
run: postman collection run postman/collections/Poll\ API
- name: Push to Postman Cloud (only when code is merged)
if: github.event_name == 'push'
run: postman workspace push -y
- name: Stop API server
run: npm run stop:daemon
ポイント:
-
postman loginでは--with-api-keyオプションでPostman APIキーを指定することで、ログイン時の対話をスキップできる (Postman APIキーの取得方法は後述します) -
postman workspace pushの-yオプションで確認プロンプトをスキップ（CI環境では必須） -
postman workspace pushはPRのマージ時（pushイベント）のみ実行するようif条件で制御
Postman APIキーの取得
Postman CLIでPostmanにログインするためにはPostman API キーが必要です。以下のいづれかの方法で、Postman APIキー管理ページに遷移します。
- (a) Settings (画面右上の設定アイコン) → [Account settings] → [API Keys] をクリック
- (b) go.postman.co/settings/me/api-keysに直接アクセス
Postmanキー管理ページで [Generate API Key] ボタンをクリックしてAPIキーを生成します。APIキー文字列は生成時にしか表示されないので、生成時に必ずクリップボードなどにコピーしておきましょう。
こうするとすっきりすると思います。
GitHub Actions Secretの設定
先の手順で取得したPostman APIキーを、GitHubリポジトリのSecretとして登録します。
リポジトリの Settings → Security: Secrets and Variables → Actions を開き、[New repository secret] をクリックして次の内容を入力してください。
| 項目 | 値 |
|---|---|
| Name | POSTMAN_API_KEY |
| Secret | PostmanのAPIキーの値 |
8. プルリクエストの作成とCIの実行
まずは、ローカルのfeature/api-testingブランチの作業内容をGitHub（リモートリポジトリ）にpushします。
ブランチをpush
git add .github
git add .postman
git add postman
git add package.json
git commit -m "Add postman items and CI workflow"
git push origin feature/api-testing
GitHub上でプルリクエストを作成
マージ元ブランチ（feature/api-testing）からマージ先（main）へのプルリクエストを作成します。
参考: pull request の作成
GitHub ActionsとPRのマージ
プルリクエストを作成すると、自動的にGitHub Actionsが起動します。各ステップをクリックすると詳細な実行結果を確認できます。
問題がなければ [Merge Pull Request] ボタンをクリックしてPRをマージします。
マージ後、再度CIがキックされ、APIテストとPostman CloudへのPushが実行されます。
Cloud ViewでPostman Cloudの結果を確認
さきほどと同じ手順で、フッターから [Postman Cloud] に切り替えて、変更が反映されていることを確認してください。
まとめ
本記事では、PostmanのネイティブGit連携を使った以下の一連の流れを体験しました。
- ワークスペースとGitリポジトリの紐づけ
- Agent Modeを使ったコレクション作成
- ローカルでのAPIテスト
- Postman Cloudへの手動同期
- Postman CLIを使ったテストと同期
- CI（GitHub Actions）によるテストと同期の自動化
ネイティブGit連携を活用することで、APIのコードとPostmanの成果物を一元管理でき、Gitを使う開発者チームにとっては、開発ワークフローに自然に組み込むことができます。また、Gitリポジトリへのマージ内容をCIを通じて自動的にPostman Cloudに同期することで、Gitを使わないQAチームやパートナーともPostman Cloudを通じて共同作業をすすめることができます。
次は、同じネイティブGit連携でもAPI（デザイン）ファーストなアプローチで行うハンズオン記事を書きます（たぶん）。ご期待ください。