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. Your work on Postman API elements - including collections, environments, API specifications, SDKs, mocks, and flows - 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 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 with 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.

Push and pull changes in Postman

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 elements down into your local file system.

Push to Postman Cloud

You can edit your Local Items before you push them to Postman Cloud. If you’re in Cloud View, in the footer, click Switch to Local.

Then, in the left sidebar, open the Local Items tab and edit your Local Items. For example, edit your Collections, Environments, and Specs.

To push to Postman Cloud, do the following:

1. Open your workspace.

2. In the footer, click Push to Postman Cloud.

3. Review your changes.

4. (Optional) Edit the list of items to push to Postman Cloud:

   • Select the items you want to push to Postman Cloud.
   • Clear the items you don’t want to push to Postman Cloud.

5. When you’re ready to push your changes, click Push to Cloud.

Postman pushes your Local Items to Postman Cloud, where they’re available to anyone in your workspace.

Pull from Postman Cloud

You can edit your Cloud Items before you pull them from Postman Cloud. If you’re in Local View, in the footer, click your branch name. Then, click Postman Cloud.

Then, in the left sidebar, open the Items in Cloud tab, and edit your Cloud Items. For example, edit your Collections, Environments, and Specs.

To pull from Postman Cloud, do the following:

1. Open your workspace.

2. In the footer, click Pull from Postman Cloud.

3. (Optional) Choose another workspace.

4. Edit the list of items to pull from Postman Cloud:

   • Select the items you want to pull from Postman Cloud.
   • Clear the items you don’t want to pull from Postman Cloud.

5. When you’re ready to pull your changes, click Pull from Cloud.

Postman pulls your Cloud Items from Postman Cloud, where they’re available to you locally.

Push and pull changes in your CI/CD pipeline

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.

Integrate your service with Postman’s Native Git

To integrate your service with Postman’s Native Git, ensure you 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/resources.yaml 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 the your collection’s available cloud elements to your local 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.

View your project workspaces in Postman

Your Git-connected project workspaces appear in the workspaces dashboard.

To view all project workspaces in the workspaces dashboard, do the following:

1. Click Workspaces in the Postman header, and then click View all workspaces.
2. Select the Project Workspaces tab.

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

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

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

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.