Using version control

You can use version control with your Postman Collections by forking and merging and utilizing a standard pull request process. Version control allows you to collaborate with teammates by working on different forks of the same collection, updating forks from the parent collection, and merging changes when you're ready. You can tag collaborators to review pull requests and resolve conflicts to manage collection versions.

Forking a collection

To fork a collection in Postman, select the collection in the Collections sidebar, click View more actions (...), and select Create a fork. To provide a uniform forking experience, you can create a fork in a public workspace in three steps — login to Postman, fill up fork details and enable your public profile.

Create Fork

Enter a label for your fork, and select a workspace to save it to. Click Fork Collection.

Fork Label

Your fork will be created in the selected workspace.

If there are any mocks or monitors associated with a collection, they will not be available with the forked collection. You will need to create mocks and monitors specifically for the fork if you need them.

Forking information

To fork a collection within a public workspace, you must enable your public profile. Navigate to Edit Profile and enable Make Profile Public. Your username should consist of only only alphanumeric characters and hyphens. If you do not have a public profile, the screen shows a dialog box — once you have entered a valid username, click Enable public profile.

Enable public profile

Fork information provides details about forks and the users who have created them. You will be able to identify the users who are actively consuming and contributing to your APIs. Click the fork count to reveal the list of users who have active forks.

Fork Information

You can click on a user under Forked by to view their public profile.

Forking to send requests

If you are a visitor who does not belong to any public workspace, to send requests from a collection in a public workspace, login to Postman with your credentials. Click Sign in.

Visitor accessing public workspace

Postman will prompt a login screen, you can either create a free account or sign in to get started.

Visitor Sign in

Being a signed-in non-member, to send requests in a public workspace, fork the collection into a workspace that you belong to (either team or personal whichever you choose during fork creation) and then make changes.

Visitor creating a fork

Make sure your public profile is enabled before you fork a collection from a public workspace.

Watching a collection

The watch option allows you to receive an email/in-app notification when one of your team member belonging to the same workspace modifies the collection. If you watch a collection, you will be notified of actions such as adding a new request, modifying the existing requests, adding or updating variables, editing pre-request scripts or tests, adding or deleting a folder and so on.

Once you've created the collection, click Watch to start watching the collection.

Collection watching

Click the bell icon in the top right corner of Postman to view the notification. The popup will indicate further information about the change that was made to the collection.

Notification Collection Watching

In addition to a notification, you will receive an email with the information regarding who has made the change, what the change was, and when it was made.

Watch Collection Email Notification

Click View changelog to access the full changelog in Postman.

If you created the collection and modified it from the same account, you will not receive email or in-app notifications for changes made.

Forking an environment

To fork an environment in Postman, select the environment in the Environments sidebar, click View more actions (...), and select Create a fork. You can also fork an environment by clicking Fork in environment overview tab.

Create an Environment Fork

Enter a label for your fork, and select a workspace to save it to. Click Fork Environment.

Fork Label Environment

Your forked environment will be created in the selected workspace. You will be able to view the forked environments in the sidebar on the left as well as under the environment dropdown on the right side of Postman.

Environment dropdown for forked environments

The forks icon Fork icon on context bar for v8 on the context bar provides details about the forks created.

Fork icon overview for v8

Click View all forks to reveal the detailed list of forks along with information about users who created them.

Fork overview details v8

Creating pull requests

You can merge changes from a collection fork (the source) into the parent (the destination) using a pull request process, by tagging reviewers who can comment on your changes and decide to merge them. In Postman, open the menu for a collection and select Create Pull Request.

Create Pull Request

You can overview the source, destination, and changes that will be included in the pull request.

Pull Request Changes

If the parent collection has any changes since you last updated your fork, you can pull those changes before merging.

If there are any conflicts, they will be highlighted so that you can resolve them.

Resolve Conflicts

If your pull request has no conflicts, you can go ahead and open it for review. Enter a title and description, and select up to three reviewers from the dropdown list. Reviewers will need edit access to the collection in order to merge your changes. Click Create Pull Request.

Create Pull Request

Reviewers can comment on your pull request or decide to merge your changes into the parent collection.

Pull request settings

Pull request settings are available on Postman Business and Enterprise plans in the Manage Roles section of a collection.

Collection Manage Roles

In Postman, select the collection in the Collections sidebar and click View more actions (...). Select Manage roles, then select Editor for the users you want to provide editor access to.

manage roles

You must have Editor access on a collection to merge changes. If you have Viewer access to a collection, you will see a warning icon while adding reviewers to a pull request.

Reviewer permission

Once you have created the pull request, you can assign merge checks before approving changes.

Merge Check

There are two different types of checks that you can enable for a pull request:

  • Approved once : You need at least one approval to merge the pull request.
  • Approved by a collection editor : You require the approval of a collection editor to merge the pull request.

If you do not have editor access to the collection, the option to Merge will be disabled.

Merge Disabled

Click View Merge Conditions to see the merge conditions to be met for the pull request.

Merge Condition

Creating public PRs

To create a pull request on a public collection, you must fork the collection to a public workspace and you should have either viewer or editor access on the source collection.

The pull request author and users with viewer or editor access on the destination collection can do the following:

  • Edit the metadata (update the title and description)
  • Decline a pull request
  • Approve or unapprove a pull request
  • Merge a pull request
  • View or add pull request comments

You can create a pull request on a fork (the source) into the parent (the destination). The parent collection resides in a public workspace where as the forked collection is present in a team workspace. While creating a pull request, share the source collection to a public workspace so that the reviewers can access it while reviewing the pull request. Select the workspace and click Create Pull Request.

Source Collection Public

Once you create the pull request, you will get a notification that it has been Shared to public workspace.

Source Collection Shared

Watching a pull request

The watch option allows you to receive an in-app notification when one of your team member belonging to the same workspace modifies the pull request. If you watch a pull request, you will be notified of actions such as adding a new comment, approving or unapproving, merging, editing or declining a pull request, and so on.

Once you've created the pull request, click Watch to start watching the pull request.

Pull request watching

Once you have enabled watch, you will be able to view and modify the conditions for which notifications will be triggered.

Conditions for watch notifications

Click the bell icon in the top right corner of Postman to view the notification. The popup will indicate further information about the change that was made to the pull request.

Notification Pull Request Watching

If you created the pull request and modified it from the same account, you will not receive any notifications for changes made.

Approving changes

You can approve changes on a fork (the source) into the parent (the destination). Once the pull request is created, navigate to the collection in Postman and click on the Pull Requests icon on the right panel.

Status Pull Request

If you're tagged as a reviewer on a pull request, you can go ahead and approve the pull request. Upon approval, you will see the status of the pull request as Approved.

Approve Fork

Merging changes

You can merge changes on a fork (the source) into the parent fork (the destination). It is recommended that you use the pull request process instead of merging straight away—which you can only do if you have edit access to the original collection. If you do not have permissions to edit the parent collection, you will need to open a pull request so that someone with edit access can merge your changes.

When you merge changes from a fork into its parent collection, you have a chance to review the "diff" first. Select Merge changes on the fork in Postman.

Postman will display an overview of the changes you are attempting to merge.

Merge Fork

If the parent collection has any changes since you last updated your fork, you can pull those changes before merging.

If there are no conflicts you can review the changes and click Merge all changes when you are ready.

Merge Fork Options

You can merge all changes from the fork into the parent, merge into the parent and update the fork, or merge in the parent and delete the fork. Make a selection and click Merge.

Pulling updates

You can keep your forked collections up to date with any changes in the parent, for example if another team member has merged changes into the parent collection.

To compare your fork to its parent, choose Merge changes in the forked collection in Postman.

Merge Fork

Postman will warn you before you attempt to merge a fork whose parent has changed since you last updated it. Click Pull Changes to update your fork with the changes in the parent collection.

Update Fork

Reviewing pull requests

If you're tagged as a reviewer on a pull request, you can view the changes, comment, and merge the forked collection into the parent (or decline the pull request) when you are ready.

You can see a list of pull request for any collection under the Pull Requests tab on the right panel in Postman.

Open Pull Request

Each pull request includes status, which will be OPEN for any that have not been merged or declined.

You can choose to Edit or Decline the pull request.

Pull Request Options

To view the differences between the fork (the source) and the parent fork (the destination), click Changes tab.

Diff Navigation

The diff navigation view enables you to review the changes made to a collection effortlessly. The nested folder structure shows the requests present within the folders and improves navigation while working with forks and pull requests.

Once a pull request is merged, you cannot edit or decline it. You can check the merged pull request in the Pull Requests panel.

Merged PR

You can view the detail on any merged pull request by selecting it.

Merge PR Detail

Resolving conflicts

If you encounter conflicts when you attempt to merge a forked collection, you will need to decide how you want to resolve them before continuing. A conflict will occur when you are attempting to merge changes into a request, folder, or example that has changed since you updated your fork.

Merge conflicts can involve changes in multiple workspaces.

Pull Changes

The Source will indicate the changes on your fork, with the Destination representing the changes on the parent branch. Click Use this next to the version you want to include when you merge. When conflicts are resolved, the Pull changes button will be enabled and you can pull updates.

Next steps

You can also use version control on APIs you design and build in Postman.