Automating API spec fetching from Postman using GitHub Actions

This tutorial will guide you through setting up a GitHub Action to automatically fetch a Postman collection and upload it to your repository using the Postman API. By automating this process, you can keep your Postman collections synced with your CI/CD pipeline and ensure that your SDKs are always up-to-date with the latest API spec, without manual exports from Postman.

Prerequisites

Before you begin, ensure you have the following:

• A GitHub repository to store the Postman collection.
• A Postman account and access to the Postman API.
• The Postman collection ID of the API spec you wish to fetch.
• Your Postman API key for authentication.

Steps

This tutorial covers the following steps:

1. Set up the GitHub Action
2. Use the GitHub Action in your workflow
3. Generate the Postman API Key
4. Get the collection id
5. Store secrets in GitHub
6. Triggering the workflow
7. Verifying the process

Step 1: Set up the GitHub Action

The first step is to set up the GitHub Action to fetch the Postman collection and save it as a JSON file in your repository. You'll need to create a new GitHub Action in your repository. This process is described in the following steps:

1. Create a .github/actions/fetch-postman-collection-action directory in your repository.

2. Add a new YAML file named action.yml under the .github/actions/fetch-postman-collection-action directory.

3. Copy and paste the following code into action.yml:

   name: 'Fetch Postman Collection'
   description: 'Fetch a Postman collection and save it as a JSON file, then validate it.'
   inputs:
     postman_collection_id:
       description: 'The Postman collection ID to fetch.'
       required: true
     postman_api_key:
       description: 'Your Postman API key.'
       required: true
     output_file:
       description: 'The file where the Postman collection will be saved.'
       required: false
       default: 'collection.json'
   
   runs:
     using: 'composite'
     steps:
       - name: Fetch Postman Collection
         shell: bash
         run: |
           curl -s -H "X-API-Key: ${{ inputs.postman_api_key }}" \
             "https://api.postman.com/collections/${{ inputs.postman_collection_id }}" \
             | jq '.collection' > ${{ inputs.output_file }}
           echo "saved_file=${{ inputs.output_file }}" >> $GITHUB_OUTPUT
   
       - name: Validate JSON
         shell: bash
         run: |
           jq empty ${{ inputs.output_file }} || (echo "Invalid JSON file" && exit 1)
   
       - name: Commit and push changes
         shell: bash  
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git fetch origin main
           git merge origin/main --no-edit || echo "No conflicts to resolve."
           git add ${{ inputs.output_file }}
           git commit -m "Add updated Postman collection"
           git push

This GitHub Action fetches a Postman collection using the Postman API, saves it as a JSON file, and validates its format. If the collection is valid, it commits and pushes the updated file to the repository, ensuring the Postman collection in the repo stays up-to-date automatically.

Step 2: Use the GitHub Action in your workflow

To use the action, you can trigger it as part of your CI/CD workflow by calling it from your main workflow YAML file.

To trigger the action, reference it in your main workflow YAML file. If you don’t have an existing workflow file, you can create a new one and add the following code snippet to .github/workflows/main.yml:

name: API Spec Fetch and Sync

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch: # Allows manual triggering of the workflow

jobs:
  fetch_postman_collection:
    runs-on: ubuntu-latest

    permissions:
      contents: write # This grants write access to the repository contents

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Call Fetch Postman Collection Action
        uses: ./.github/actions/fetch-postman-collection-action
        with:
          postman_collection_id: ${{ secrets.POSTMAN_COLLECTION_ID }}
          postman_api_key: ${{ secrets.POSTMAN_API_KEY }}
          output_file: 'postman-collection.json'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

To ensure the workflow will work, you must make sure that the path used for uses: ./.github/actions/fetch-postman-collection-action is correct. In addition, you still need to add POSTMAN_COLLECTION_ID and POSTMAN_API_KEY to your secrets before using the action.

output_file

You can set output_file, the output file name, where the Postman collection will be saved. The default is collection.json, but you can change this to any desired file name and edit the path.

Step 3: Generate the Postman API Key

To use the GitHub Action from Step 1, you need to use your Postman API Key. If you have never used a Postman API Key before, you must generate one. To generate a new Key, follow the steps:

1. Access the API Keys section using the Postman account that owns the collection.
2. Click Generate API Key.
3. Name your key and click Generate API Key.
4. Copy the API Key and save it in a secure place. This is the only time you'll see it unencrypted.
5. After creating the API Key, change the API Key settings, select the option Never expire API keys. This will ensure you'll not need to repeat this process in the future.

Step 4: Get the collection id

You have to get the collection id. This information is required so the action knows which collection to get the information from.

To retrieve the collection id, follow the steps:

1. Make a request to the Postman API endpoint to have access to all collections linked to your account. Replace the <your_api_key> by the API Key you got in Step 3.

  curl -X GET "https://api.getpostman.com/collections?apikey=<your_api_key>"

2. You will receive an array with all collections linked to your account. Identify the collection you want to use and copy its id. The following snippet presents an example of the response you can expect.

{
  "collections": [
    {
      "id": "30107d04-5793-4bdd-9449-601be46cf6b2",
      "name": "Collection Name",
      "owner": "28471659",
      "createdAt": "2024-08-19T12:35:18.000Z",
      "updatedAt": "2024-08-19T12:35:18.000Z",
      "uid": "28471659-30107d04-5793-4bdd-9449-601be46ef6a2",
      "isPublic": false
    },
    {
      "id": "640c6fca-bb4b-4959-b23a-0b1278cf056b",
      "name": "Collection Name",
      "owner": "21397186",
      "createdAt": "2022-09-05T22:54:41.000Z",
      "updatedAt": "2022-09-16T18:27:32.000Z",
      "uid": "21397186-640c6fca-bb4b-4959-b23c-0b1278ef056b",
      "isPublic": false
    }
  ]
}

Step 5: Store secrets in GitHub

For security reasons, you should not hardcode your Postman API key or collection ID in the workflow. Instead, use GitHub Secrets to store these values securely.

1. Go to your GitHub repository's Settings.
2. Navigate to Secrets and variables > Actions.
3. Add the following secrets:

• POSTMAN_COLLECTION_ID: The ID of the Postman collection.
• POSTMAN_API_KEY: Your Postman API key.

Step 6: Triggering the workflow

Once everything is configured, the GitHub Action will trigger on a push or pull_request event to the main branch, or any branch you specify. The action will:

1. Fetch the Postman collection from the Postman API.
2. Save it as a JSON file.
3. Validate the JSON file to ensure it is well-formed.
4. Commit the updated file to the repository.

After triggering the workflow, access the Actions tab in your GitHub repository to check the action's current status.

Step 7: Verifying the process

Once the workflow is complete, you should see the updated Postman collection file in your repository. You can now use it in your CI/CD pipeline to regenerate SDKs as needed.