Version Control for Collections

You can use version control with your Postman collections, forking and merging using a standard pull request process. Version control allows you to collaborate with teammates, 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

You can fork a collection from the Postman app or the web dashboard. To fork a collection in the Postman app, select the collection in the Collections sidebar and click the View more actions (...) button. Select Create a Fork.

Create Fork

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

Create Fork

Your fork will be created in the selected workspace.

fork collection

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.

Creating pull requests

You can merge changes from a collection fork (the source) into the parent (the destination) using a pull request process, tagging reviewers who can comment on your changes and decide to merge or not. In the Postman app or web dashboard, 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.

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.

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 the Postman app or web dashboard.

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 the Postman app or web dashboard).

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 in the web dashboard Pull Requests tab.

Open Pull Request

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

Select an open pull request from the list to review it. You can comment to have a discussion or request changes.

Pull Request Comments

You can choose to Edit or Decline the pull request.

If you are ready to merge, click Approve and Merge. Choose a merge option and click Merge.

The pull request will be listed as merged in the Collection Pull Requests list.

Merged PR

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

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

Merge Conflicts

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 Merge all changes or Approve and Merge button will be enabled and you can merge your fork.

Next steps

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