Use PostmanNative Git

Set up Native Git

View as Markdown

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. For an end-to-end workflow that includes creating a workspace, generating API artifacts, and syncing resources, see Sync local and cloud elements with Native Git.

After you connect your repo, review the Issues tab for schema, path, and file-format problems before syncing changes to the cloud.

If you’re using a coding agent to set this up instead of the app, run postman init from the terminal. It creates the same project structure without the app and installs agent skills so the agent can work with Postman the way a developer would.

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.

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 choose the folder, select the service’s subfolder inside the repository, such as multiservice-monorepo/services/service_1, 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 folder in a monorepo

multiservice-monorepo

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 push from the service folder, not the repository root, so the command reads that service’s .postman/resources.yaml manifest and syncs only that service’s elements.

Connect an existing service to Native Git

To bring a service with existing Postman elements into Native Git, ensure you have editor access to the workspace that contains the service’s collection and environments. Then do the following:

  1. Check out your team’s integration branch, such as main or develop.
  2. Connect your 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.
  3. Pull the collection and environments into your file system. When you choose which workspace to pull from, select the workspace that already has the service’s elements — you don’t need to move them into the newly connected workspace first.

If the service doesn’t have existing Postman elements yet, skip the pull step and generate API artifacts with Postman AI instead.

Keep local environment values in the Postman app, and commit only Shared values to Git. Integrate a Postman Vault to reference managed secrets instead of committing them to your repository.

Connect your Git project to your workspace

For the folder connection steps, Git setup, and an explanation of the files Postman creates, see Connect a folder and set up Git. For monorepos, connect the service folder rather than the repository root.

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

RuleSeverityMessageDescription
FMT014ErrorUnknown request kind "<value>" (path: /$kind)The $kind field has an unrecognized value. Must be one of: http-request, graphql-request, grpc-request, websocket-request, socket.io-request, mqtt-request, mcp-request, llm-request.
FMT015ErrorInvalid discriminator value. Expected one of the allowed values (path: /<field>/type)An enum field has an invalid value. Common triggers: auth.type (must be one of bearer, basic, apikey, oauth1, oauth2, jwt, hawk, awsv4, digest, ntlm, noauth, or inherit) or body.type (must be one of json, formdata, urlencoded, text, xml, html, javascript, file, graphql, none).
FMT016ErrorSchema validation error on an example file (*.example.yaml)The example file doesn’t conform to the http-example schema — for example, a missing $kind or a response.statusCode of the wrong type.
FMT017ErrorSchema validation error on a scope or definition file (.resources/definition.yaml)The collection or folder definition file has an invalid structure, such as the wrong $kind or a malformed variable shape.
FMT018ErrorYAML parse error: <parser message>The file isn’t valid YAML — a syntax error, bad indentation, an unquoted special character, and so on.
FMT019ErrorFolder name "<name>" contains characters unsafe for filesystem operations. Rename to "<safe-name>".A collection or folder directory name contains characters that aren’t safe for filenames, such as slashes, colons, asterisks, question marks, quotation marks, angle brackets, or pipes.

File and path rules

RuleSeverityMessageDescription
FMT001Error<field> path does not exist: <path>A path referenced in the YAML (such as an examples path or a script path) points to a file or directory that doesn’t exist on disk.
FMT002ErrorInvalid request filename stem "<name>" — contains unsafe charactersThe filename before .request.yaml contains characters not allowed on the filesystem (slashes, colons, asterisks, question marks, quotation marks, angle brackets, or pipes). Also fires if the request file sits inside a .resources/ directory.
FMT003Error<field> path is non-canonical for request "<name>": <path>A referenced path resolves correctly but isn’t written in normalized form (for example, ./foo/../bar instead of ./bar).
FMT004ErrorInvalid scripts declaration shape for protocol "<protocol>"The scripts array uses a type value that isn’t valid for the request’s protocol — for example, using beforeRequest on a gRPC request instead of beforeInvoke.
FMT005ErrorScripts directory must include <required-file>A path-backed scripts directory is missing its required entry file.
FMT006ErrorPath-backed script entry does not resolve to an existing file, or is non-canonical: <path>A script referenced by file path either doesn’t exist or uses a non-normalized path.
FMT007ErrorCase-insensitive filename collision in directory: <file1>, <file2>Two files in the same folder have names that differ only by case (for example, Login.request.yaml and login.request.yaml), which causes problems on case-insensitive filesystems.
FMT010ErrorPath does not exist, or is not a directoryA directory path referenced in the collection structure doesn’t exist, or points to a file instead of a folder.
FMT011ErrorOrphan request resources directory without matching request file: <path>A .resources/<name>.resources/ directory exists, but there’s no corresponding <name>.request.yaml file alongside it.
FMT012Error<field> path escapes collection root: <path>A referenced path (for example, ../../outside) resolves to a location outside the collection’s root directory.
FMT013Error<field> path contains backslash separator. Use forward slashes in YAML paths.A path in the YAML uses Windows-style backslashes instead of forward slashes.

Style and redundancy warnings

RuleSeverityMessageDescription
FMT201WarningRequest name equals filename stem; omit name to reduce redundancy.The name field in the YAML is identical to the filename stem, so it’s redundant and can be removed.
FMT202WarningExamples directory contains zero *.example.yaml / *.example.yml files.An examples/ directory exists under .resources/ but is empty.
FMT203WarningUnrecognized file type for Postman Collection Format v3.A file in the collection directory has an extension Postman doesn’t recognize (not .request.yaml, .example.yaml, definition.yaml, and so on).
FMT204WarningWorkspace config issue.The .postman/resources.yaml or .postman/config.json file wasn’t found or is malformed.
FMT207WarningUnrecognized field "<field>" is not part of the Postman Collection Format v3 schema and will be ignored.A field isn’t supported on that object type and is ignored — for example, an auth field on an http-example object, since examples inherit authentication from the parent request.
FMT209Warningurl and queryParams are out of sync.The url field and the queryParams array disagree on which query parameters exist, usually because the URL is missing a query string that queryParams defines.

Fix issues with AI

Instead of fixing each flagged issue by hand, use Postman AI to fix them.

1

Open the Issues panel

Open the Issues tab, next to Console and Terminal. Hover an issue to show a per-issue Fix button, or select Fix Issues in the panel header to fix every issue at once.

2

Review the proposed edits

Postman AI opens with a prompt to fix the lint issues in the workspace. It reads each affected file, groups the fixes into a to-do list, and proposes edits one at a time as a diff with Apply Edit and Reject buttons.

3

Apply each edit

Review each diff, then select Apply Edit. Postman AI never writes to disk without an explicit Apply Edit, so don’t click through without reviewing.

4

Confirm the result

As you apply edits, the error and warning counts in the Issues panel drop and to-do items are checked off. When every to-do item is resolved, the panel reports no remaining issues.

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 push command reads it from your working directory. It has three main parts:

PartWhat it defines
workspace.idThe cloud workspace this repository syncs to.
cloudResourcesA map of local paths to the cloud IDs of elements that already exist in the cloud.
localResourcesLocal elements to sync that live outside the default postman/ directories, listed by path.

push finds your local elements two ways and combines the results: it scans the default postman/ directories, and it reads 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.

Use --push-strategy force-sync when you want your local files to be the complete source of truth and the cloud workspace to be an exact mirror of them — for example, after renaming or deleting elements locally. With this flag, push mirrors the cloud to everything it finds locally, from both the scan and localResources, and 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.