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, don’t connect your Postman workspace to the repository root. Instead, create a workspace for each service and connect it to that service’s folder within the repository, for example services/service_1. Postman creates the .postman/resources.yaml manifest and the postman directory inside the service folder, so the workspace only picks up that service’s collections, environments, and specifications. Connecting to the repository root would sync every service’s files into a single workspace, which mixes unrelated elements together and makes it harder to scope access to each service’s team. To learn how the manifest controls what’s created, updated, or deleted in the cloud, see How the resources.yaml manifest controls sync.

To connect a service folder, follow the steps in Connect your Git project to your workspace. When you click Open folder, navigate into the service’s subfolder inside the repository, such as multiservice-monorepo/services/service_1, and open that folder rather than the repository root.

Multiple workspaces can connect to the same repository, each to its own subfolder. For example, a development team and a QA team can each connect their workspace to a different subfolder, then collaborate on the same pull request while keeping their Postman elements scoped to their own folder.

Example: Workspace setup for a monorepo with multiple services

When you use the Postman CLI, pass the service folder as the path when you connect, for example postman workspace connect-git <workspace-id> services/service_1. To learn more, see postman workspace connect-git. Then run postman workspace prepare and postman workspace push from the service folder, not the repository root, so the commands read that service’s .postman/resources.yaml manifest and sync only that service’s elements.

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. For a single-service repo, connect the repository root. For a monorepo, connect the service’s folder within the repo. Validate this step by ensuring .postman/resources.yaml appears in the folder you connected. 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. For a single-service repo, this is the repository root. For a monorepo, navigate into the folder for the specific service, such as services/service_1, so the workspace only syncs that service’s files. To learn more, see Monorepos with multiple services.
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.

Identify issues in local collection files

The Issues tab surfaces problems Postman finds in your local collection files. It shows a total error and warning count, then lists the affected files grouped by resource type, along with a description of what’s wrong with each one.

Flagged issues are generally file-format problems, such as an unknown request kind or an invalid value for a field like an auth or body type.

Schema validation

File and path rules (FMT001–FMT013)

Style and redundancy warnings

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.