Automate Native Git with CI/CD

Use this page after you understand the app-based Native Git workflow in Sync local and cloud elements with Native Git. Instead of pushing and pulling changes manually, automate synchronization with the Postman CLI push command triggered by events like merging a pull request.

Set up your CI/CD secret

To generate an API key, create a Postman API key from your Postman account settings. Add this key as a protected secret (for example, POSTMAN_API_KEY) in your repository’s settings (for example, GitHub Secrets, GitLab Variables). Both workflows on this page use this secret to log in to Postman.

Publish changes on merge

Add postman workspace push to your pipeline to synchronize local files with the cloud workspace. The command prepares entity IDs and lints the workspace configuration and supported element files before syncing.

Example: GitHub Actions workflow

Create or update your .github/workflows/postman-publish.yml file with the following steps:

name: Publish changes to Postman
on:
  push:
    branches:
      - main  # Publish changes after they reach the integration branch
jobs:
  publish-changes:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Postman CLI
        run: |
          curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
      - name: Verify Postman CLI version
        run: postman --version
      - name: Login to Postman
        run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
      - name: Publish changes to Cloud
        run: postman workspace push -y

Recommended best practices

Use the --yes flag — Use the -y or --yes option to skip manual confirmation prompts.
Lint before pushing — Add lint steps before postman workspace push so invalid files are caught before they reach the cloud. You can lint collections, environments, and global variables.
Validation — The push command prepares entity IDs and lints the workspace configuration and supported element files before syncing. Because element errors skip only the affected element while the rest of the push continues, run lint commands first so invalid YAML, structure, or schema issues fail the pipeline before a partial push.

Once the workflow is in place, trigger it on your merge or release path and confirm the cloud workspace updates after the pipeline completes.

Lint on pull request

Instead of waiting for the push workflow to catch issues, run postman workspace lint on every pull request so problems fail the check before the branch merges:

name: Lint Postman workspace
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  lint-workspace:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Postman CLI
        run: |
          curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
      - name: Login to Postman
        run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
      - name: Lint workspace
        run: postman workspace lint --fail-severity warning

For the full app-based workflow and push/pull flow, see Sync local and cloud elements with Native Git.