As a developer, your code is probably already version-controlled in Git, but the surrounding API artifacts (OpenAPI specs, collections, environments, etc) can often be scattered across tools, scripts, and projects. This challenge is at the heart of what Postman provides – a unified workspace, with rich toolset for working with, managing, and collaborating on, APIs. Now, with the new native git integration, your APIs can be managed right alongside your code.
Let’s say you’re an engineer on a team building a Book API for your online business. The API implementation code lives in a GitHub repository , and multiple groups in your organization need to collaborate:
-
Your engineering team needs to design and evolve the API surface, not just the implementation.
-
QA needs collections and environments they can extend with tests and plug into CI.
-
Other internal teams and external consumers need a reliable way to discover, fork, and use the Collections.
In this post, I’m going to show you how to set up your collaboration flows and publish to the cloud to connect with your continuous integration processes. You can think of this as your inner loop of collaboration – people, teams, and processes internal to your organization. Then, in a follow up post, we will cover the outer loop of external collaboration. Let’s jump in.
Prerequisites
To follow along, you’ll need:
Phase 1 – Set up collaboration flows internally for your engineering team
Step 1 – Clone the repo
The repository contains a simple demo book API that has some basic CRUD operations. Run this command to clone the repository and create a feature branch
gh repo clone Postman-Devrel/Book-API
OR
git clone https://github.com/Postman-Devrel/Book-API.git
git checkout -b feat/branch-name
Step 2 – Connect your Workspace to git
The Workspace defines the collaboration boundary. Connecting it to a local Git repo ensures API artifacts are versioned, reviewable, and branch-aware like your code.
API collaboration in Postman begins with a Workspace. This is where your collections, environments, API specs, flows, and mocks reside. It enables teammates to discover APIs, grants consumers access, and distributes the authoritative version of your API artifacts.
In the top navigation menu, click on Workspaces→ Create Workspace. Give your Workspace a name (Book API) and create it. In the blank Workspace, on the left side of the Footer, you will see a “Connect Git” option and an “Open Folder” option in the left sidebar.
Select either of the options and choose the folder of the git repo you just cloned. Your local files will appear on the left sidebar. Click on the “Generate config file” prompt at the top of the file view.
You will land on a UI as shown above. Let’s break this down:
-
In the left sidebar, view your existing code base files from the cloned repo, including two folders: .postman and postman. The .postman folder contains Workspace configuration options, while Postman holds all Workspace resources and artifacts. Toggle these folders in the UI to view their contents.
-
In the footer’s left section, the current branch name appears. The active environment is Local View. Click the branch name to switch branches or to Cloud View. Local View stores local git resources on disk; Cloud View hosts resources in Postman Cloud. Cloud view shows what is deployed, while local view displays what is in development.
To get a clearer idea of Local vs Cloud view, let’s switch between the two. Click on the name of your branch to the left of the footer, and you will see a list of branches available in this repo and a search field. Click on “Postman cloud” above the search field to switch to cloud view. The difference might not be striking now until you start to generate collections and other artifacts in your Workspace. Switch back to Local and continue to the next step.
Step 3 – Create a Collection with Agent Mode
Next, click on the Ask AI button in #3. Agent Mode will automatically read all the files in this git repo, check for exposed API interfaces, and automatically generate a collection for you to start working with.
You can see the generated collection files in your file system. Click on the Local Items toggle of the left navigation sidebar to see the generated collection.
Switch back and forth between Local and Cloud view to confirm that this collection is only available locally in your Workspace. Stay in local view and continue to the next step.
Step 4 – Modify Workspace artifacts
Now, let us make some changes to the Collection we just created in this Workspace using Agent Mode.
First, test out the requests in this collection. You need to install the required dependencies and start the Node.js server.
Click on the terminal button at the footer and run the following command.
yarn install
yarn dev
Now, navigating back to the collection, run any random request and ascertain that you get a valid API response back. Click on the Save Response button to save this response as an example for this request. Repeat the same procedure for some or all other requests in this collection so they all have a saved request example.
On your terminal, if you run git status, you will see all the changes that have been made and are available to be staged for commit.
Next, open the right sidebar and ask Agent Mode to generate some tests for your collection(Prompt: Generate comprehensive tests for all the requests in this collection). Agent Mode will automatically modify each request and add some tests to its respective test scripts.
Step 5 – Invite Your Team
To follow this step, you need a Team Workspace. This is included in the Postman Team plan. If you don’t have a Team plan, skip to step #6. You can follow the rest of the article.
Now, you need to invite members of your team to this Workspace so they can similarly connect it to their local git repos. Navigate to the Workspace settings by clicking on the ellipsis icon to the right of the search bar in the left sidebar. Select Workspace Overview and navigate to settings. Click on Manage People and select the appropriate team to invite or type in users email individually. Default their roles to the viewer role, and only give edit access to those who need to maintain the Workspace itself.
Step 6 – Commit and Push Changes
Commit your Postman artifacts alongside your code changes.
git add .
git commit -m "feat: commit message"
git push origin feat/branch-name
The collection change is now part of the same commit as the code change. You can push these changes and open a pull request as you normally would. The PR contains both the implementation and the API artifact changes.
—
Anyone reviewing the code can pull these changes locally and similarly connect their Workspace to git locally to try out the changes.
Phase 2 – Automate the distribution of these changes
After development, the next step is distributing these APIs to the appropriate consumers, either internally within your organisation or externally to partners or customers.
All changes so far have been local. When updates occur, you must distribute them to consumers by pushing changes to the Cloud View. This can be done manually or automatically in CI using Postman CLI.
To push manually, click on the ellipsis icon beside the search bar in the left sidebar and select the “Push to Postman Cloud” option.
Publish to Cloud via the CI
Before pushing changes that update the Cloud View your consumers depend on, ensure they can be tested and run automatically in your CI pipeline, your specs lint successfully, there are no unexpected failures, etc.
Automation helps you build confidence in your workflows. Here’s a GitHub Actions workflow example that validates on every PR, and publishes to Postman Cloud when changes are merged to main:
name: Publish to Postman Workspace
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
jobs:
postman:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: "npm"
- name: Install dependencies
run: npm install
- name: Start server in background
run: |
npm run dev &
echo $! > pidfile
# Wait for server to be ready (port 3000)
for i in {1..20}; do
if nc -z localhost 3000; then
echo "Server is up!"
break
fi
echo "Waiting for server..."
sleep 2
done
- name: Validate Collection
env:
POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
run: |
postman login --with-api-key "$POSTMAN_API_KEY"
postman collection run ./postman/collections/Book-API
- name: Push to Postman Cloud
if: github.event_name == 'push'
env:
POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
run: |
postman login --with-api-key "$POSTMAN_API_KEY"
postman workspace prepare
postman workspace push -y
- name: Stop server
if: always()
run: |
if [ -f pidfile ]; then
kill $(cat pidfile) || true
rm pidfile
fi
This action file is already present in the ./github/workflows folder of the forked repository. You can copy and paste it if you’re working from a different repository.
It ensures that when the main branch updates, the collection runs, and all workspace changes are pushed to your consumers in Postman after the validation steps pass and your pull request is merged.
Note that the API keys are securely stored and referenced using GitHub Secrets.
Ensure you update the path in line 46 of the actions file to the relative path of your collection folder. In my case, this line becomes postman collection run ./postman/collections/Book-API
If the collection run is successful, the workspace changes are pushed to the Postman Cloud and made available to your consumers. Switch to Postman Cloud from the footer to confirm that the changes were pushed.
How you set this up is your choice. Note that Cloud view shows what is deployed, while local view shows what is in development.
A merge to main can trigger deployment. You can also use a different trigger to push to the cloud after successful deployment.
Conclusion
By now, you’ve:
-
Connected your Postman Team Workspace to a Git repository
-
Standardize how your engineering team designs, tests, and reviews API artifacts alongside code
-
Automated how trusted, validated changes are promoted to Postman Cloud for consumers via CI
This completes the internal collaboration loop: engineers can safely evolve APIs, reviewers can validate changes in pull requests, and consumers always get an up‑to‑date, reliable version of your Collections, environments, and other API artifacts.
However, most APIs don’t live in an engineering silo. Documentation writers, QA engineers, frontend teams, and even external partners often need to propose changes, improve docs, or extend tests—without having direct access to the codebase or your internal Git workflows.
In the second part of this article(Enabling Collaboration with External Teams), we’ll look at how to safely open up this workflow to non‑engineering contributors using Postman Cloud, Workspace forks, and pull requests on Collections themselves.
Resources
The post Collaborating on APIs with Postman Team Workspaces and Native Git appeared first on Postman Blog.
Log in
