Tech & Design LAB

GitHub Actionsとgit-secretによるPostmanのCI/CD環境の構築

#CI/CD #Postman #GitHub Actions
author icon
Posted on
tech

はじめに

HiCustomer のエンジニアの 吉村(@jumpyoshim)です。 今回は、 GitHub Actions と git-secret による Postman の CI/CD 環境の構築方法 を紹介させていただきます。弊社では公開 API とプライベート API の結合テストや回帰テストなどで Postman を利用しています。Postman を利用するなかで以下の問題がありました。

上記の問題を解決するべく、GitHub Actions を活用した Postman への同期の自動化と git-secret を活用した Postman のバージョン管理を行いました。

Postman とは

Postman とは 「 The Collaboration Platform for API Development 」 で、API の自動テストやモニタリング、モックなど API の開発を効率的に行うための機能を備えたツールです。

https://www.postman.com/

弊社 では自動テストやモニタリング、E2E テストを行うためのデータのセットアップなどで活用しています。

Postman では自動テストやモニタリングでコールする API のリクエストを Collection というリクエストの集合で管理でき、Environment という機能で Collection で利用できる環境変数を設定できます。この Collection と Environment を JSON 形式でバージョン管理し、任意のタイミングで Postman に Collection と Environment を同期するのが今回の目的です。

Postman のつらみ

便利な Postman ですが、以下の問題がありました。

Postman としては GitHub にバックアップをとれる機能を提供してはいましたが、今回実現したかったことは GitHub で Collection や Environment をバージョン管理し、任意のタイミングで Postman にデータを同期する というものでした。

https://learning.postman.com/docs/integrations/github/

今回実現したいことが公式の連携機能やサードパーティでもなかったため、Postman の CI/CD 環境を独自に構築することにしました。

全体構成

まず今回の CI/CD の構成を紹介します。

  1. Collection と Environment の JSON ファイルの作成 or 更新
  2. Environment を暗号化し push
  3. PR の作成
  4. PR のレビューとマージ
  5. GitHub Actions で Postman にデータを同期

1. Collection と Environment の JSON ファイルの作成 or 更新

Collection と Environment を JSON 形式で作成または更新します。JSON は最終的に Postman へ同期する際に、Postman の公開 API のリクエストボディとして利用します。既にデータが Postman にあれば JSON 形式でファイルをエクスポートできます。

https://learning.postman.com/docs/postman/collections/sharing-collections/

既に Git 管理されている JSON ファイルの更新であれば、該当箇所を更新してコミットします。

2. Environment を暗号化し push

API キーなどの秘密情報をもつ Environment は git-secret で暗号化し push します。

「Postman のバージョン管理」の章で詳細を記載します。

3. PR の作成

GitHub でコードレビューをする際の通常のフローです。PR を作成しレビューを依頼します。

4. PR のレビューとマージ

GitHub でコードレビューをする際の通常のフローです。追加・更新する Collection をレビューし、問題なければ承認、マージします。

5. GitHub Actions で Postman にデータを同期

PR がマージされたら Postman にデータを同期する Workflow を GitHub Actions で構築します。

「Postman への同期の自動化」の章で詳細を記載します。

Postman への同期の自動化

Postman への同期の自動化には GitHub Actions を利用しました。GitHub Actions は昨年 2019 年にリリースされた GitHub の CI/CD ツールです。issue の作成や commit の push など、GitHub の様々なイベントをトリガーとして Workflow を構築することができます。

https://github.com/features/actions

今回は、Pull Request がマージされたら Postman への同期のスクリプトを実行する Workflow を構築しました。下記のように、Workflow は YAML で構築できます。

name: Sync to Postman

    on:
      pull_request:
        types: [closed]
        branches:
          - master

    jobs:
      build:
        runs-on: ubuntu-latest

        steps:
          - uses: actions/checkout@v1
          - uses: actions/setup-python@v1
            with:
              python-version: "3.x"
              architecture: "x64"
          - name: Update collections
            run: ./bin/update_collections.py
            env:
              POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}

今回初めて GitHub Actions を触りましたが、他の CI/CD ツールと似たシンタックスなので直感的に記述できました。しかし、手動実行できなかったり、PR の close と merge が同じトリガーだったりとまだサービスとしては未熟だなと感じる点がありました。今後の機能追加に期待したいです。

Workflow で実行しているスクリプト update_collections.py は Collection の Put API をリクエストしています。

https://docs.api.getpostman.com/?version=latest

Postman の公開 API は RESTful な API でドキュメントも充実しており、クライアントの実装を簡単に行うことができました。

Environment はマージされたタイミングではなく任意のタイミングで同期する方針にしたため、スクリプトだけ用意し GitHub Actions の Workflow には含めていません。

Postman のバージョン管理

Collection や Environment をすべて JSON 形式でバージョン管理します。

Environment に関しては、API キーなどの秘密情報を安全にバージョン管理する必要があるため git-secret を利用しました。

git-secret

https://git-secret.io/

git-secret は秘密情報を git で扱うためのコマンドラインツールです。 GPG と git を使い以下の処理を行ってくれます。

以下のようなコマンドを利用することでファイルの暗号化・復号化を行うことができます。

$ git secret add <path or file> # 暗号化するファイルの追加

$ git secret hide # ファイルの暗号化

$ git secret reveal # ファイルの復号化

$ git secret tell -m <email> # アクセス権限の付与

アクセス権限の付与で指定する email は GPG によって信頼されたメンバーを指定します。

GPG

https://gnupg.org/

git-secret の暗号化には 公開鍵暗号化方式の GPG が使用されます。GPG を利用するために、

  1. キーペアの生成
  2. 公開鍵のエクスポートとインポート

を行います。以下の手順で紹介する GPG のバージョンは 2.1.17 以降です。

1. キーペアの生成

GPG の鍵を所有していない場合は、鍵を作成する必要があります。鍵の作成に必要なパラメータは以下になります。

今回は参考として、暗号スイートが RSA の 4096 で、鍵の用途として署名・暗号・認証のすべてを選択し、有効期限をなしで作成するコマンドを紹介します。実際に作る際には、各種パラメータは組織のポリシーに従って決定してください。

$ gpg --quick-generate-key 'Taro Yamada <taro@example.com>' rsa4096 default never

2. 公開鍵のエクスポートとインポート

公開鍵の共有はファイル経由で行う方法やキーサーバ経由で行う方法があります。今回は、ファイル経由で行う方法を選択しました。キーサーバの方が何かと便利なのですが、推奨されていた SKS キーサーバプール hkps.pool.sks-keyservers.net が攻撃を受けたのと、新しい公開鍵サーバ keys.opengpg.org現時点で対応が進んでおらず動かない環境があるためです。

参照:OpenPGP 公開鍵サーバにおける公開鍵の汚染問題

$ gpg --export -a 'Taro Yamada' > key.asc

$ gpg --import key.asc

import した公開鍵を利用する(今回の用途である git-secret で暗号化するケース)には、利用する用途毎に trust-level を適切に設定する必要があります。参考として以下に無条件で公開鍵を信用する設定を紹介します。trust-level をどれにするかは組織のポリシーに従って決定してください。

$ gpg --edit-key '<fingerprint>'
gpg> trust
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)

  1 = I don't know or won't say
  2 = I do NOT trust
  3 = I trust marginally
  4 = I trust fully
  5 = I trust ultimately
  m = back to the main menu

Your decision? 5
gpg> save

以上のような流れを踏むことで、API キーなどの秘匿情報を安全にバージョン管理できるようになります。次は同期の自動化の方法を紹介します。

効果

誤操作で書き換えてしまっても正しいデータに同期できるようになりました。また、先日 IDaaS への移行で API の認証方式が変わったのですが、JSON ファイルで管理していたおかげでヘッダーの一括更新ができ、修正コストを大幅に下げることができました。

さらに、上記の問題解決に加え、Postman をバージョン管理できたことで以下の二次的な効果を得ることができました。

Postman は newman という CLI ツールを提供しており、以下のように JSON 形式のコレクションをコマンドラインからコレクションの実行が可能です。

$ newman run examples/sample-collection.json

https://github.com/postmanlabs/newman

さいごに

HiCustomer エンジニアチームは、今回のような自動化や業務効率化に積極的に取り組んでいます。今回はその一部を紹介させていただきました。よろしければ以下のスライドもご覧ください。

https://speakerdeck.com/hizeny/engineers-at-hicustomer

HiCustomer では一緒にプロダクト開発する仲間を募集しています!少しでも興味をお持ちいただけた方、ぜひお気軽にオフィスに遊びにきてください。Wantedlyか VPoE @hizeny までご連絡お待ちしております。

author icon
エンジニア

Goとサーバーレスを頑張ってます。筋トレが好きです。マッスルアップとプランシェができるようになりたい。