> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # Sync local and cloud elements with Native Git With Native Git, you keep your collections, specifications, environments, and globals as files in your project folder and sync them with Postman Cloud. Connect a workspace to a local project folder, use Postman AI to generate API artifacts from your code, and push and pull changes between your local files and Postman Cloud. To automate pushes from a CI/CD pipeline, see [Automate Native Git with CI/CD](/docs/use/native-git/automation/). ## Before you begin Before you sync a workspace, make sure you have the following: * A local project folder that contains your API code and, optionally, an existing `postman` directory. The folder doesn't need to be a Git repository to start. You can [set up Git](#connect-a-folder-and-set-up-git) later, and you need it to pull from Postman Cloud. * A Postman team to create the workspace in, or permission to create a workspace outside of teams. ## Create a workspace from a local folder When you create a workspace from a local folder, Postman stores your API resources as files in the folder, next to your code. Postman tracks the current Git branch, so the files you sync follow the branch you're working on. To create a workspace from a local folder, do the following: #### Open the workspace creation page From ![Home icon](https://assets.postman.com/postman-docs/aether-icons/descriptive-home-stroke.svg#icon) **Home**, select ![Workspaces icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-entity-workspaces-stroke.svg#icon) **Workspaces** and click **Create workspace**. #### Name the workspace Enter a **Workspace name**, such as the name of your service. #### Choose a team Select a team from **Create workspace for this team**, or select **Create workspace outside of teams**. #### Choose a local folder Under **Choose how you'd like to set up this workspace**, select **From a local folder**, then select **Choose a folder**. To start without a project, select **Blank workspace** instead. #### Optionally generate API artifacts with Postman AI In **Create with Postman AI**, describe the API you want to build. Postman AI sets up collections, specifications, and environments for it. #### Create the workspace Select **Create Workspace**. Postman creates the workspace and connects it to your project folder. From the workspace, you can generate API artifacts, pull resources from Postman Cloud, or push local changes to Postman Cloud. ## Connect a folder and set up Git You don't have to create a new workspace to use a project folder, and you don't need Git to start. You can connect a folder first and set up Git later. Until Git is set up, the workspace runs in Local mode. ### Connect a project folder How you connect the folder depends on where you're starting: * **You have an existing workspace and a local folder.** Click ![Local files icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-descriptive-localFiles-stroke.svg#icon) **Local Files** and select **Open Folder** to bring in your local files and work locally with Git. * **The workspace is already connected to a repository.** Postman shows the repository URL and offers **Open Folder**, for a folder you already have, or **Clone Repo**. * **The folder is already a Git repository.** Click **Connect to workspace** to link the folder to the workspace so it can sync with Postman Cloud. If Postman finds Postman resources in the repository, such as an environment, it asks for permission to connect the folder to the workspace, synced with your Git branches. Select **Connect to workspace** to approve. ### Set up Git If the folder isn't a Git repository, Postman shows a **Set up Git** prompt with two tabs: **Initialize** and **Configure remote**. To set up Git, do the following: #### Initialize the Git repository On the **Initialize** tab, select **Run in Terminal**. Postman runs `git init` in its built-in terminal. #### Configure the remote On the **Configure remote** tab, enter your **remote URL**. Postman fills in the command `git remote add origin `. #### Add the remote Select **Run in Terminal**. Postman adds the remote, and the **Set up Git** prompt goes away. You can keep using the same terminal for other Git commands, such as `git checkout -b develop` to create a branch. Postman shows the branch you have checked out, and `git status` lists the new `.postman/` and `postman/` directories as untracked files, so you can add and commit them like any other files. Use your team's integration branch as the base for feature branches. The branch name depends on your Git workflow, such as `main` or `develop`. ### Switch between Local and Cloud Postman shows a workspace in two views. **Local** mode shows the files in your Git repository, where you edit resources, change branches, and prepare changes. **Cloud** view shows what's in Postman Cloud. Use the switch between them to move between the Local Git and Cloud views, change branches, or push and pull updates. When you're in Cloud view, Postman prompts you: *You are viewing Postman Cloud. Switch to Local mode to work with files in their Git repository and keep them in sync.* ### Disconnect a folder You can connect only one folder in your file system to a workspace at a time. To open your files in a different workspace, disconnect the folder from its current workspace by selecting **File viewer options > Disconnect**. ![Native Git disconnect](https://assets.postman.com/postman-docs/v12/native-git-disconnect-v12.png) ### Files in your project folder When you connect a workspace, Postman creates a `.postman` directory for workspace configuration and a `postman` directory for resources. The `postman` directory contains subdirectories for resource types such as `collections`, `documents`, `environments`, `flows`, `globals`, `mocks`, and `specs`, plus a `sections.yaml` file. Some workspaces also have an `sdks` directory. These are the files that push and pull sync. You can also use [the Postman CLI](/docs/postman-cli/postman-cli-overview/) to sync and push local elements to workspaces in the cloud. See [Sync local elements with workspaces](/docs/postman-cli/postman-cli-workspace/) for details. ## Generate API artifacts with Postman AI Postman AI reads the code in your connected folder and creates API artifacts from it. Use it to create collections for an existing service, or to add missing details to artifacts you already have. To generate API artifacts, do the following: #### Start artifact generation In your workspace, select **Generate API artifacts**. #### Review the prompt Postman AI opens with a prompt that asks it to go through the implementation in the selected folder, analyze the API endpoints, and create a collection based on what it finds. #### Follow Postman AI's task list Postman AI: * Explores your directories and reads source files to identify endpoints. * Checks existing collections and specifications so it doesn't duplicate them. * Creates or updates the collection definition, including the description and variables. * Lints and validates the collection. #### Review the generated artifacts When Postman AI finishes, review the summary and the generated collections and specifications. Postman AI also suggests next steps, such as adding test scripts to the collection, creating an environment for local, staging, and production, setting up a monitor for the collection, and generating a README for the workspace. The generated artifacts are files in your repository, so you can edit them like any other source file. ## Push to Postman Cloud When you push, Postman publishes your local resource files to the cloud workspace, so they're available for teammates and for cloud features such as monitors. To push to Postman Cloud, do the following: #### Review local changes Open your workspace in Local View, then select **Push to Postman Cloud** in the footer. Review your local changes in the push dialog. Each changed item is listed with its file path. #### Choose which items to push Optionally select the items you want to push, and clear the items you don't want to push. Postman pushes only the items you leave selected. #### Push the selected items Select **Push**. Postman pushes your items to Postman Cloud. When the push is complete, no changes remain pending for the items you selected. Teammates who don't clone the repository can access the resources you push in **Cloud View** from the shared workspace. Push local changes when you want those resources available to the team. ### Resolve name conflicts when you push If an item you're pushing has the same name as an item that already exists in Postman Cloud, Postman pauses the push and opens the **Entity with conflicting name** dialog. For each conflicting item, choose what to do: * **Update existing** — Replace the cloud item with your local version. * **Keep both** — Push your local item as a new item and leave the existing cloud item unchanged. * **Rename and keep** — Rename your local item, then push it alongside the existing cloud item. **Update existing** isn't always available. If your local collection has request types that the cloud collection can't store, Postman disables it and shows the message: *This collection has request types that the selected collection can't store, so it can't update it. Choose "Keep both" or "Rename and keep" instead.* After you choose an option for every item, select **Push** to continue, or select **Cancel** to stop. ## Pull from Postman Cloud When you pull, Postman brings resources from the cloud workspace into your local file system. Pull to populate a new checkout, or to get changes made elsewhere. To pull from Postman Cloud, do the following: #### Open the pull dialog In your workspace, select **Pull from cloud**. #### Choose a workspace In **Pull from workspace**, choose the workspace you want to pull from. To filter the list, search for a resource. #### Select resources to pull Resources are grouped as **Collections**, **Environments**, **Globals**, and **Specifications**. Within a group, Postman separates resources into **Create** (they don't exist locally yet) and **Update** (they already exist locally and will be overwritten). Use **Select all** or **Deselect all** to change a whole set at once. The footer shows how many items you've selected, and **Pull from Cloud** stays unavailable until you select at least one. #### Pull the selected resources Select **Pull from Cloud**. Postman writes the selected resources to your local files. If a resource already exists locally, the pull updates it, so review your selection before you pull. ## Automate pushes with CI/CD For a pipeline example, API key handling, linting recommendations, and push-log guidance, see [Automate Native Git with CI/CD](/docs/use/native-git/automation/). ## Verify changes in the specification changelog A specification's changelog records each change made to it in Postman Cloud, including when it happened, who made it, and what changed. Use it after a push to confirm that Postman Cloud reflects your changes. To verify a push, do the following: #### Open the updated specification Open the specification you changed. #### Open the changelog Open the **Changelog**. Entries are grouped by date. #### Review the latest entry Expand the newest entry to see each change and a diff snippet. To see more context, select **Click to expand** to open the full diff. #### Verify the push Confirm that the diff matches what you pushed and that the author is the identity you expect. Pushes from CI are attributed to the account associated with the API key used by the pipeline. To mark a point in the specification's history, select **Add Version Tag**.