はじめに
Postman最大の年次イベント POST/CON 25 の週に、PostmanコレクションとGitHubの連携機能がベータ版としてリリースされました。これは、PostmanとGitHub間でコレクションのシームレスな双方向同期を可能にする機能です。
これにより、Postmanで作成したコレクションをGitHub上でコードとして管理しながら、APIテストやレビューを効率よく進めることが可能になります。Postman上の更新がGitHubに反映され、逆にGitHub上で編集した内容もPostmanに反映されるといった、実用的な開発フローが実現できます。
本記事では、このPosmtanコレクションのGitHubリポジトリとの連携機能を活用して、PostmanコレクションをGitHubリポジトリと同期してPull Request（以下、PR）を通じてコレクションを更新する方法を紹介します。
制限: GitHubリポジトリと接続可能なPostmanコレクション
GitHubリポジトリとの接続は、インターナルワークスペース内のPostmanコレクションに限定されています。また、GitHub接続されたコレクションをForkする場合も、そのFork先がインターナルワークスペース以外であればFork先コレクションもGitHub接続できないのでご注意ください。
GitHub接続されたPostmanコレクションと、公開を目的としたパブリックやパートナーワークスペースのコレクションとの連携フローについては、「コレクション公開のためのGitHub連携コレクションと公開コレクションの同期フロー」を参照ください。
PostmanのGitHub連携でPRを通じてコレクションを更新
「はじめに」で紹介した通り、PostmanコレクションとGitHubリポジトリを同期させることで、PRベースでコレクションの更新・管理が可能になります。
ここでは「Todo API」をチームで開発しているケースを例に、具体的な作業フローを紹介します。
フローを分かりやすくするために、一枚の図にまとめました。
図: GitHub連携を使ったPostmanコレクションの更新フロー（PRベース）
ここで紹介するTodo APIの開発チームは、APIのドキュメンテーションとテストのために、Postmanのプライマリーワークスペース（図では、primary workspace）上にTodo API コレクションを作成・管理しています。そして、新機能の追加や変更を行う場合は、各メンバーがこのコレクションを開発作業用ワークスペース（図では、feature workspace）にForkして開発を進め、変更内容をPull Requestでチームに共有・レビューし、プライマリーワークスペースにmergeする、という開発方針をとっています。
この運用に、GitHubとの接続（リポジトリ＆ブランチ）を絡めると、流れは次のようになります：
- [初回のみ] プライマリーワークスペースにあるTodo APIコレクションを、GitHubリポジトリのmainブランチと接続する
- コレクションを開発作業用ワークスペースにforkする。Fork作成時にForkコレクションをGitHubリポジトリのfeatureブランチと接続する
- Forkコレクションを更新すると、GitHubのfeatureブランチにも変更が自動で同期される
- GitHubでPRを作成し、チームによるレビューを経て、変更をmainブランチにmergeする。マージされた内容は、プライマリーワークスペースのコレクションにも自動で同期される
それでは、この運用フローを１つずつ実施していきます。
Step 1: GitHubリポジトリとの接続
API開発チームは、プライマリーワークスペースでTodo API コレクションを作成・管理しています。まずは、このコレクションをGitHubリポジトリのmainブランチ（もちろん、mainでなくてもOK）と接続します。
下図のように、コレクションの右隣にある「･･･」メニューから More > Connect repositoryを選択します。
図: プライマリーコレクションをGitHubリポジトリと接続
次に、下記イメージの①で表示された画面で、GtiHub を選択します。
図: Postman Appインストールフロー 1/2
②では、接続先リポジトリを選択します。まずは、GitHub Organization (組織)を選びます。もし、対象の組織が表示されない場合は、その組織にGitHub Appのインストールが必要です。組織へのGitHub Appのインストール方法については 「Installing a GitHub App from a third party」が参考になります。
組織ではなく、個人アカウントのリポジトリとも接続可能です。その場合は個人アカウントにGitHub Appをインストールする必要があります。本記事では、テスト用に③で個人アカウントを選択してます。
下記イメージの④では接続したいリポジトリ（例: todo-app-postman-collection）を選び、⑤でブランチ（ここでは main）との接続を設定します。コレクションファイルの作成先のリポジトリのディレクトリも指定できますが、ここでは空としているのでデフォルトのpostman/collectionsディレクトリに作成されます。
図: Postman Appインストールフロー 2/2
これで、指定したTodo APIコレクションはGitHubリポジトリのmainブランチと接続され、コレクションIDをファイル名としたJSONファイル（<コレクションID>.json）がmainブランチに自動生成されます。
図: コレクションデータがmainブランチと同期
Step 2: コレクションを開発作業用ワークスペースにFork
Step1で接続されたプライマリーワークスペースのコレクションを、開発作業用ワークスペース(feature workspace)にForkします。
コレクションの「･･･」メニューから Forkを選び、Fork先のワークスペースとGitHubのブランチ（ここでは feature-1）を指定します。
図: プライマリーコレクションをFork（ForkコレクションとGitHubのfeatureブランチをリンク）
この操作により、Postman上にForkコレクションが作成され、GitHub上ではfeature-1ブランチにコレクションファイル（<コレクションID>.json）が生成・同期されます。
💡注意
GitHubと接続されたコレクションをForkする場合は、必ずForkコレクションとGitHubブランチをリンクしてください。リンクされていないと、Postman上でPull Requestを作成しても、Fork元にマージできずエラーになります。
Step 3: Forkしたコレクションに変更を加える
次に、Forkコレクションに対して編集を加えます。ここでは新しいAPIリクエストを追加して保存しました。
図: Fork先ワークスペースでコレクション編集
このPostmanでの変更は自動的にGitHubのfeature-1ブランチへ同期されます。
図: Forkコレクションに紐づいているGitHubのfeature-1ブランチ (feature-1)
Step 4: GitHubでPRを通じてmainブランチにマージ
Step3でForkコレクションに加えた変更を、Fork元のプライマリーコレクションにも反映させていきます。まず、GitHub上でfeature-1→mainブランチのPull Requestを作成します。PRが作成されると、自動でPostman Appが下記のようなコメントを投稿します。
図: GitHub PRとPostman Appによる自動コメント
このコメントには、ForkコレクションのURLや、変更内容の差分URLが含まれています。これによりレビュアーは簡単にその変更内容をPostman上で確認したり、その内容をPostmanでテストしたりできます。
レビューを経てmergeが完了すると、GitHubのmainブランチとPostmanのプライマリーコレクションの両方に変更が反映されます。
図: GitHub PRをマージするとPostman側のプライマリーコレクションにもマージ
merge完了後、Forkコレクションは不要であれば削除しても問題ありません（任意）。
Postman上でForkを作成しないでGitHub PRを通じてコレクションを更新
もちろん、PostmanコレクションをGitHubリポジトリ接続設定後に、Postman上でのコレクションのForkをすることなく、GitHub上で直接PRを通じてコレクションを更新することも可能です。
フローとしては次のようになります。
図: Postman上でForkを作成しないでGitHub PRを通じてコレクションを更新
- プライマリーワークスペースにあるTodo APIコレクションを、GitHubリポジトリのmainブランチと接続する
- プライマリーコレクションと接続しているGitHubリポジトリのmainブランチからfeatureブランチを作成（もしくは、そのリポジトリの書き込み権限がない場合はForkするでもOK）
- featureブランチのコレクションを更新
- GitHubでPRを作成し、チームによるレビューを経て、変更をmainブランチにmergeする。マージされた内容は、プライマリーワークスペースのコレクションにも自動で同期される
なお、このケースでは、先のケースと違いPostman上でForkコレクションを作成しないので、PRでGitHub Appによるレビュー用の便利コメントは投稿されないのでご注意ください。
コレクション公開のためのGitHub連携コレクションと公開用コレクションの同期フロー
本記事の冒頭でも触れたように、GitHubリポジトリとの連携はインターナルワークスペース内のPostmanコレクションに限定されています。そのため、一般公開を目的としたパブリックワークスペースや、パートナー向けのパートナーワークスペースでコレクションを公開する場合、従来のフローとは異なる工夫が必要です。
ここでは、GitHubリポジトリに接続されたコレクションと、公開用のPostmanコレクションを同期させるためのフローを説明します。
図: GitHub連携コレクションと公開用コレクションの同期フロー
中央にあるのが、GitHubと連携されたインターナルワークスペースのプライマリーコレクションです。このコレクションを元に、公開用のパブリックワークスペースへ同期するフローは以下のようになります。
- [初回のみ] プライマリーコレクションをパブリックワークスペースへForkする。このとき、Fork先のコレクションをGitHubブランチとは接続しない（接続できません）
- その後、プライマリーコレクションに更新が発生した際は、パブリックコレクション側で変更をPullして取り込む
Step 1: パブリックワークスペースへのFork（初回のみ）
まず、プライマリーコレクションを公開用のパブリックワークスペースにForkします。
コレクションの「･･･」メニューから Fork を選択し、Fork先のパブリックワークスペースを指定します。この際、Link to branch の設定は必ずオフにします。オンにしてしまうと、パブリックワークスペースがFork先の候補に表示されません。
図: プライマリーコレクションをFork（ForkコレクションはGitHubブランチと接続しない）
これでパブリックワークスペースにForkコレクションが作成されます。
Step 2: 差分のPullによる公開
Step 1の後、プライマリーコレクションに変更があった場合、その変更をパブリックコレクション側に反映する必要があります。
パブリックワークスペース内のForkコレクションの「･･･」メニューからPull changesを選択します。すると、プライマリーコレクションとの差分が表示されるため、内容を確認し問題がなければ、Pull Changesボタンをクリックして変更を取り込みます。
これで変更が公開用コレクションに反映され、公開作業は完了です。
図: 差分をPullで取り込み公開を完了する
おわりに
PostmanとGitHubを連携させることで、API仕様やテストのコード管理をGitHubで、更新をPull Requestベースでできるようになります。ソースコードと同じようにレビューや履歴管理ができるため、普段からGitHubを使っているチームにとっては、非常に馴染みやすく、自然な形でAPI開発に組み込めるはずです。ぜひ一度試してみてください。