Better Practices
Published in

Better Practices

Better Practices for Git Version Control in Postman

Manage collaboration within your team and community so that you don’t release breaking changes

Real-time updates versus atomic changes

Let’s take an example of making changes to an API in Postman. If you don’t need to manage updates carefully, you can grant an editor role to collaborators within your Postman team. Everyone can make real-time updates to the specification, similar to editing in Google Docs. Editors make changes and viewers see those changes reflected in real time too.

Different forking workflows

How Git works in Postman

To continue our example of making changes to an API, here is a basic overview of how Git works in Postman:

  1. Import or create an API specification in the workspace.
  2. Connect a “repository” with a Git hosting tool (e.g., GitHub or Bitbucket).
  3. “Commit” and save the changes to your workspace.
  4. “Push” your changes to a branch in your connected repository.
  5. Make a change to your specification with a Git hosting tool and commit.
  6. “Pull” the changes to your workspace.
  7. Create a “fork” (i.e., version or branch), make a change, commit the change.
  8. Open a “pull request” to propose changes to the main branch.
  9. “Merge” your branch to the main branch.
Git features for API management in Postman

Single source of truth for internal teams

For many teams, the API specification is the single source of truth, where any other linkages are for reference only. In our example, suppose that you want to automatically generate a collection from the specification. The API specification remains the ultimate source of truth, and the collection can be used for documentation, tests, or whatever else. To manage your API, you can use the Git workflow outlined in the previous section and also manage version, release, and status for your API in Postman. You are currently not able to fork APIs.

  1. Create a “fork” (i.e., branch) of the collection, make, and save a change.
  2. Open a “pull request” to propose changes to the main branch, or “push” your changes to the main branch if you have an editor role on the main branch.
  3. “Merge” your branch to the main branch.
  4. Make a change to the main branch of your collection and save.
  5. “Pull” the changes to your fork.

How it works for API publishers with public APIs

Some organizations only want to expose their public API when ready for public consumption. In this case, here is how you can control your updates:

  1. Fork the collection to a public workspace when ready.
  2. Continue developing the collection in a team workspace.
  3. Pull updates to the collection in the public workspace if needed.
  4. Submit a pull request to the main branch in your team workspace if needed.
  5. The process is the same for external contributors who fork the collection from a public workspace.
Everyone works asynchronously using separate forks

Version control versus versioning

Although they sound very similar, “version control” is not the same as “versioning.” Version control is what we’ve talked about earlier regarding forking, merging, and pull requests. Teams create workflows around version control so that they don’t release breaking changes in a collaborative environment.

In conclusion

Different teams follow their own recipes for version control, so always check with your team lead on the preferred way that your team works. Your team might choose to use any combination of these better practices depending on your specific goals and constraints. If your team has a unique workflow, share some of your tips or questions in the comments below.



For individual engineers to the largest teams, Better Practices is intended to distill knowledge from the Postman community. This is a place to learn about modern software practices together! Read more:

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store