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.

1
name: API Tests
2
3
on: push
4
5
jobs:
6
  test:
7
    runs-on: ubuntu-latest
8
    steps:
9
      - name: Run Postman Collection
10
        uses: postmanlabs/postman-cli-action@v1
11
        with:
12
          command: 'collection run 12345678-collection-id'
13
          api-key: ${{ secrets.POSTMAN_API_KEY }}

The Postman CLI GitHub Action accepts the following inputs:

The Postman CLI commands return the following outputs:

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.

1
# Local file
2
- uses: postmanlabs/postman-cli-action@v1
3
  with:
4
    command: 'collection run tests/collection.json --environment tests/environment.json'
5
6
# Cloud resources
7
- uses: postmanlabs/postman-cli-action@v1
8
  with:
9
    command: 'collection run 12345678-collection-id --environment 87654321-environment-id'
10
    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.

1
- uses: postmanlabs/postman-cli-action@v1
2
  with:
3
    command: 'monitor run 12345678-monitor-id'
4
    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.

1
# Local file
2
- uses: postmanlabs/postman-cli-action@v1
3
  with:
4
    command: 'spec lint specs/openapi.yaml --fail-severity ERROR'
5
6
# Cloud resources
7
- uses: postmanlabs/postman-cli-action@v1
8
  with:
9
    command: 'spec lint 12345678-spec-id --output json --fail-severity ERROR'
10
    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.

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

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