About Native Git

With Postman’s file system support (Native Git), API iterations are authored and iterated locally in Git, alongside code, and intentionally not synced to Postman Cloud until the API reaches a stable, deployable state.

In Postman, you can open the local instance of your remote Git repository where your API is implemented. The collections, specifications, and environments you work on in Postman are saved as a folder inside the source code folder. You keep your collection and project files in sync, then commit your local changes to Postman Cloud.

In Local View, you can edit the collection file directly in your IDE or in Postman. You can also make changes to your local files using Postman Agent Mode or the LLM in your IDE. All development changes flow through the Local View → Git → automated CI sync → Cloud View pipeline.

Native Git benefits

As a developer, you can work in a branch on a feature, like adding a new endpoint or changing the implementation, while the rest of your team works on something else. When your feature is ready, the PRs can contain code and collection changes and be version controlled together.

You can use the Postman CLI to run tests as part of the CI/CD pipeline before merging changes. Collections stored in a branch can have tests specific to the branch code.

Set up your workspace with Native Git

Follow these recommendations to ensure access to both the collection and the underlying implementation code. The Postman Agent’s capabilities, such as AI-assisted debugging and test generation, are significantly more efficient with such setup.

Repos with a single service

For repos with a single service, connect your Postman workspace to a root folder that contains both your API collections and your application code.

Example: Workspace setup for a single-service repo

Mono-repos with multiple services

For mono-repos containing multiple services, connect each individual service folder to a separate Postman workspace rather than connecting the entire repo to a single workspace.

Example: Workspace setup for a mono-repo with multiple services

Sync securely with CI/CD and Postman Cloud

While you as a developer may work primarily with local Git collections, maintaining an up-to-date Cloud View is essential for collaborating with teammates (like frontend developers) who may not have or may not want to have the local repository cloned. Consider local mode to be the builder’s view, and cloud mode to be the consumer’s view.

To ensure smooth collaboration, everyone working on the project should be on the same Postman team and same Postman workspace. Personal workspaces can’t be used for Native Git workflows.

To avoid manual errors and outdated cloud collections, automate the synchronization process using the Postman CLI push command within a CI/CD pipeline, triggered by events like merging a pull request.

If you have existing workspaces, you can transition to the local Git setup by connecting your current workspace to a repository and pulling the cloud collections down into your local file system.

Integrate your service with Postman’s Native Git

To integrate your service with Postman’s Native Git, you have to have write access to the collection and its associated environments. Then you can do the following:

1. Select the service you want to integrate.
2. Identify the blueprint collection for this service and verify write access.
3. Ensure the corresponding environments are pinned.
4. Verify the secrets aren’t shared with the cloud.
5. Create a new workspace for this service and add a workspace tag.
6. Move the blueprint collection and its pinned environments to the new workspace.
7. Check out a new branch from develop.
8. Connect the new project workspace to the repo. Validate this step by ensuring .postman/config.json appears in your root directory. This file maps your local files to specific Postman Cloud entities.
9. Pull the collection and environments into your file system. This step brings collections to your Git repo.

Connect your Git project to your workspace

To connect your Git project to your workspace, do the following:

1. Open your project workspace.

2. From the Postman sidebar, click Files.

3. Click Open Folder.

4. Open the Git project you want to connect to your workspace.

5. Click Connect. Postman connects your local Git project to your workspace. Now you have the option to see the branch in Local View or access Cloud View in the bottom left.

   

You can only connect one folder in your filesystem to a workspace at a time. To open your files in a different workspace, you must disconnect from the workspace your file are connected to. Select File viewer options > Disconnect.

When you connect to a workspace, Postman automatically adds two directories: .postman (hidden) and postman. The visible postman directory includes subfolders for your collections and environments.

Add a GitHub workflow to publish to Postman Cloud

1. 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, and so on).

2. Add the synchronization step to your pipeline. The primary command recommended for this workflow is postman workspace push. This command validates and synchronizes your local files with the cloud workspace.

Example: GitHub Actions workflow

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

1
name: Publish changes to Postman
2
on:
3
  push:
4
    branches:
5
      - main  # Trigger sync when code is merged to main
6
7
jobs:
8
  publish-changes:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - name: Checkout repository
12
        uses: actions/checkout@v4
13
14
      - name: Install Postman CLI
15
        run: |
16
          curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
17
18
      - name: Verify Postman CLI version
19
        run: postman --version
20
      - name: Login to Postman
21
        run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
22
      - name: Publish changes to Cloud
23
        run: postman workspace push -y

Recommended best practices

• Use the --yes flag: In a CI/CD environment, use the -y or --yes option to skip manual confirmation prompts.

• Mono-repo Support: If you follow the team’s recommendation for mono-repos, use the --collections-dir and --environments-dir flags to specify paths for each service.

• Validation: The push command automatically performs a “prepare” step to validate your files before syncing. You can skip this with --no-prepare if needed, though it’s not recommended for production pipelines.

Merge and validate your integration

To complete your setup, do the following:

1. Commit the Postman files + GitHub workflow and push your branch.
2. Create a PR to develop and merge it.
3. Trigger a release to main.

Develop with Native Git

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 JSON 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.

1. 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 JSON dumps 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.

2. Commit and push the JSON diff. Your changes will appear as modified .json files. Commit the changes and push the feature branch:

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

3. 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.

4. 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.

5. 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.

6. Validate release creation in your usual communication channels.

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

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