Run Postman CLI commands in your CI/CD workflows using GitHub Actions

With the Postman CLI GitHub Action, you can run Postman CLI commands directly in your GitHub CI/CD workflows, without creating and maintaining custom actions. The action supports collection runs, monitors, syntax checks, governance validation, and more. By catching regressions and configuration issues early, you can confidently decide whether to proceed with or roll back a deployment.

To learn more about the Postman CLI GitHub Action, see the GitHub Marketplace.

Use the Postman CLI GitHub Action

Specify the Postman CLI commands you’d like to run in your CI/CD workflows. For each command, you can customize inputs to suit your API project, such as the Postman CLI version. Each command returns an exit code output you can use to check whether the results succeeded or failed.

name: API Tests

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run Postman Collection
        uses: postmanlabs/postman-cli-action@v1
        with:
          command: 'collection run 12345678-collection-id'
          api-key: ${{ secrets.POSTMAN_API_KEY }}

The Postman CLI GitHub Action accepts the following inputs:

Name	Description
api-key	Specify your Postman API key used for authentication. Required if you’re accessing the Postman cloud. This is optional if you’re accessing local files.
command	(Required) Specify the Postman CLI command you’d like to run and its options.
postman-cli-version	Specify the Postman CLI version to install. For example, 1.27.0. (Default: latest)
region	If you purchased a Postman EU Data Residency plan, specify that your instance of Postman is hosted in the EU region. Accepts eu.
working-directory	Specify the directory to run the command from. (Default: .)

The Postman CLI commands return the following outputs:

Name	Description
exit-code	The Postman CLI command returns exit code 0 when it successfully completes. The command returns a non-zero exit code when a failure is detected.

Run collections

A collection is a set of API requests, a workflow, or a test suite. You can use the Postman CLI to run HTTP collections and send the run results to the Postman cloud. Learn more about collections.

# Local file
- uses: postmanlabs/postman-cli-action@v1
  with:
    command: 'collection run tests/collection.json --environment tests/environment.json'

# Cloud resources
- uses: postmanlabs/postman-cli-action@v1
  with:
    command: 'collection run 12345678-collection-id --environment 87654321-environment-id'
    api-key: ${{ secrets.POSTMAN_API_KEY }}

Learn more about the collection run options you can use to configure the command.

Run monitors

Monitors enable you to regularly check the health and performance of your APIs. You can use the Postman CLI to trigger monitor runs and send the run results to the Postman cloud. You can learn more about configuring a monitor for your CI/CD workflow.

- uses: postmanlabs/postman-cli-action@v1
  with:
    command: 'monitor run 12345678-monitor-id'
    api-key: ${{ secrets.POSTMAN_API_KEY }}

Learn more about the monitor run options you can use to configure the command.

Validate specifications in Spec Hub

Run syntax validation and governance rule checks against API specifications in Spec Hub. The command is supported for API specifications in OpenAPI 2.0, 3.0, or 3.1 format.

# Local file
- uses: postmanlabs/postman-cli-action@v1
  with:
    command: 'spec lint specs/openapi.yaml --fail-severity ERROR'

# Cloud resources
- uses: postmanlabs/postman-cli-action@v1
  with:
    command: 'spec lint 12345678-spec-id --output json --fail-severity ERROR'
    api-key: ${{ secrets.POSTMAN_API_KEY }}

Learn more about the specification validation options you can use to configure the command.

Validate specifications in the API Builder

Run syntax validation and governance rule checks against API specifications in the Postman API Builder.

- uses: postmanlabs/postman-cli-action@v1
  with:
    command: 'api lint 98765432-api-id --fail-severity WARNING'
    api-key: ${{ secrets.POSTMAN_API_KEY }}

Learn more about the API validation options you can use to configure the command.