GitHub Actions that update Postman Collection based upon OpenAPI Spec using openapi-to-postman

update-postman-collection.yml

name: Update Postman Collection

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize]

env:
  # OpenAPI file path
  OPENAPI_FILE: oas/openapi.yaml
  # Postman Collection file path
  COLLECTION_FILE: postman/collections/36962762-584eb5cd-551c-4b2a-8bcc-d4ae56f2db0e.json

jobs:
  generate-postman-collection:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout PR branch
        uses: actions/checkout@v3
        with:
          ref: ${{ github.event.pull_request.head.ref }}

      - name: Check for changes in openapi.yaml
        id: detect_change
        run: |
          git fetch origin main
          CHANGED=$(git diff --name-only origin/main HEAD | grep "$OPENAPI_FILE" || true)
          echo "changed_files=$CHANGED" >> $GITHUB_OUTPUT

      - name: Exit if no changes detected
        if: steps.detect_change.outputs.changed_files == ''
        run: |
          echo "No changes detected in oas/openapi.yaml. Exiting workflow."
          exit 0

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install openapi-to-postmanv2
        run: npm install -g openapi-to-postmanv2

      - name: Get postman collection ID
        id: get_collection_id
        run: |
          if [ -f "$COLLECTION_FILE" ]; then
            COLLECTION_ID=$(jq -r '.info._postman_id' "$COLLECTION_FILE")
            echo "collection_id=$COLLECTION_ID" >> $GITHUB_OUTPUT
          fi

      - name: Generate postman collection
        run: |
          openapi2postmanv2 -s $OPENAPI_FILE \
            -o $COLLECTION_FILE -p \
            -O folderStrategy=Tags,parametersResolution=Example,enableOptionalParameters=false
          # Update collection ID if it exists
          if [ -n "${{ steps.get_collection_id.outputs.collection_id }}" ]; then
            jq --arg id "${{ steps.get_collection_id.outputs.collection_id }}" \
               '.info._postman_id = $id' "$COLLECTION_FILE" > tmp.json
            mv tmp.json "$COLLECTION_FILE"
          fi 

      - name: Commit and push generated collection
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add $COLLECTION_FILE
          git commit -m "chore: auto-generate postman collection from OpenAPI"
          git push origin HEAD:${{ github.event.pull_request.head.ref }}

このGHAファイル (update-postman-collection.yml)をmainブランチの.github/workflows配下に配置します。envブロックで定義するOPENAPI_FILEとCOLLECTION_FILEの値はみなさんの値に変更してください。これで、feature -> mainブランチへのPRが作成されると、OpenAPIファイルに変更があった場合に、それを元にPostmanコレクションが自動生成され自動的にcommit & pushされるようになります。

Explanation points

• トリガー: mainブランチに対するPR作成時/更新時に発火
• 差分検出: git diff で OpenAPIファイル (環境変数 OPENAPI_FILE) の変更有無を確認
• 生成: 変更があった場合に限りコレクションをopenapi2postmanを使ってPostmanコレクションファイル (環境変数 COLLECTION_FILE)を生成する。生成毎にコレクションファイルのコレクションID (info._postman_id)が変更されるため、それを変更前のIDで再更新にする処理を行う
• Commit & Push: 再生成されたPostmanコレクションをcommit ＆ push

Required Settings on Repository

このGHAは生成されたPostmanコレクションをリポジトリにPushするため、リポジトリへ書き込みするための設定が必要です。もし書き込み権限がない場合は、下記手順を参考に設定してください

Option 1. GitHub Actionsに書き込み権限を付与する

リポジトリの設定で、GitHub Actionsに書き込み権限を付与する必要があります。

1. リポジトリのSettingsに移動
2. 左側のメニューからActions > Generalを選択
3. Workflow permissionsセクションで、以下を選択:
   • Read and write permissions（読み取りと書き込み権限を付与）
4. Saveボタンをクリックして設定を保存

Option 2. Personal Access Token (PAT) を使用する

GitHub Actionsがリポジトリにプッシュできるようにするために、Personal Access Token (PAT) を使用する方法もあります。

1. PATを作成:
   • GitHubのプロフィールアイコンをクリックし、Settingsに移動
   • 左側のメニューからDeveloper settings > Personal access tokens > **Tokens (classic)**を選択
   • Generate new tokenをクリックし、必要なスコープ（repo）を選択してトークンを生成
2. GitHub SecretsにPATを保存:
   • リポジトリのSettingsに移動
   • 左側のメニューからSecrets and variables > Actionsを選択
   • New repository secretをクリックし、以下を入力:
     • Name: GH_PAT
     • Value: 作成したPAT
3. Workflowを修正:

以下のように、PATを使用して認証するようにGitHub Actionsのワークフローを修正します。

```yaml
- name: Commit and push generated collection
  env:
    GH_PAT: ${{ secrets.GH_PAT }}
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add $COLLECTION_FILE
    git commit -m "chore: auto-generate postman collection from OpenAPI"
    git push <https://x-access-token:${GH_PAT}@github.com/yokawasa/todo-api-expressjs.git> HEAD:${{ github.event.pull_request.head.ref }}

```