Set up Native Git

You can start using local mode right away by connecting to a local project folder. When you’re ready to sync your changes with Postman Cloud, you can link the folder to Git and enable push and pull.

Follow these recommendations to set up your workspace 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 more efficient with this 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

Monorepos with multiple services

In a monorepo, each service is an independently deployable application or API that lives in its own folder within the repository, with its own Postman elements, such as collections and environments.

For monorepos containing multiple services, connect your Postman workspace to the repository root. Postman creates one top-level .postman/resources.yaml manifest, where you register each service’s Postman elements. This lets you sync every service from one workspace, rather than connecting each service folder to a separate workspace. To learn how this file controls what’s created, updated, or deleted in the cloud, see How the resources.yaml manifest controls sync.

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

In the root .postman/resources.yaml file, register each service’s elements under localResources, using paths relative to the .postman/ directory:

1
localResources:
2
  collections:
3
    - ../services/service_1/postman/collections/Service 1 API
4
    - ../services/service_2/postman/collections/Service 2 API
5
  environments:
6
    - ../services/service_1/postman/environments/Service 1 Staging.environment.yaml
7
    - ../services/service_2/postman/environments/Service 2 Staging.environment.yaml

Run postman workspace prepare and postman workspace push from the repository root so the commands pick up the root manifest and sync all registered services.

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 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 folder you want to connect to your workspace.
5. Click Open. Postman connects your local folder to your workspace. Now you have the option to see the folder in Local View or access Cloud View in the bottom left.
6. To connect Git to your local folder, switch to Local View and click Set up Git. You’ll get the commands to run in the terminal to initialize Git in the folder and add a remote origin for cloud sync.

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

How the resources.yaml manifest controls sync

The .postman/resources.yaml file configures how a repository syncs to the cloud. Postman creates it when you connect a folder to a workspace, and the prepare and push commands read it from your working directory. It has three main parts:

push and prepare find your local elements two ways and combine the results: they scan the default postman/ directories, and they read the paths listed in localResources. An element found both ways is synced only once.

Paths in localResources are relative to the .postman/ directory and must match the on-disk folder names, which are also the element names in the cloud.

For each element it finds, push uses cloudResources to decide whether to create or update it:

• If the element has a matching cloudResources entry, push updates the existing cloud element.
• If it has no cloudResources entry, push creates a new cloud element. After a successful create, push records the returned ID in cloudResources so later pushes update it instead of relying on name matching.

With --push-strategy force-sync, push mirrors the cloud to everything it finds locally, from both the scan and localResources. It deletes a cloud element only when that element is absent from both.

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.