Use PostmanNative Git

Develop locally with Native Git

View as Markdown

Once your workspace is connected to your Git project, you can use the following workflow to develop a feature locally and sync it back to Postman Cloud.

  1. Open the service-specific project workspace. This workspace contains your blueprint collection and its pinned environments, and is already connected to your Git repo.

  2. Switch Postman to Local View. This ensures you are editing the local YAML files generated by the Git-backed connection.

  3. (One-time per machine) Set the repo directory. Point Postman to the root of your service’s Git repository. This enables the app to read/write the collection dumps under postman/.

  4. Create a new feature branch. From your terminal or Git client:

    $git checkout main
    $git pull
    $git checkout -b feature/<your-feature>

    The branch switch is automatically reflected inside the Postman App.

  5. Make API changes in the Postman App. Edit the blueprint collection or its pinned environments from Local View only.

    Examples:

    • Adding new endpoints

    • Updating request structures

    • Updating test scripts

    • Editing STAGE/BETA environment variables

    All edits are saved directly into the Postman Collection V3 YAML files under postman/.

    Any changes made directly in Cloud View will get deleted upon subsequent invocation of postman workspace push due to absence of corresponding changes in local files.

  6. Commit and push the YAML diff. Your changes will appear as modified .yaml files. Commit the changes and push the feature branch:

    $git add .
    $git commit -m "Update API blueprint for <feature>"
    $git push

  7. Raise a PR and merge to main. Review and merge the changes like any other code change.

    Cloud View is still not updated at this stage.

  8. Understand what’s not synced yet. After the merge, the project workspace still shows previous data in Cloud View, and the catalog workspace forks (used by PAN) also show previous data. This is expected because updates only propagate to Cloud after a release.

  9. Create a new release. Follow your usual service release process. Creating a release merges the branch to main, triggers a push to main, and kicks off the Postman sync GitHub Action. See Automate Native Git with CI/CD for how this pipeline is configured.

  10. Validate release creation in your usual communication channels.

  11. Verify the GitHub Action run. Open your repository’s Actions tab and look for “Publish Changes to Postman Cloud”. Ensure it completed successfully.

  12. Confirm Cloud sync. Your blueprint collection and environments should now show updated content. Forked copies should reflect the same updates.

If you need to share your in-progress local changes with someone before you push to Postman Cloud, see Share changes from your local branch.