Version Control & Team Workflow

Collections, environments and mock servers are plain JSON in your repository. They travel through the same branches, pull requests and code review as the code they describe — no cloud workspace, no seats, no sync service.

TEAM & CI/CD

Why source control, not a cloud workspace

API Studio has no server component. Everything it knows about your APIs lives in a .openpost/ directory at your project root. Because that directory is ordinary text, your existing version control is the sharing mechanism.

The API definition ships with the code that implements it — one branch, one commit, one review

Branches work as expected — a feature branch carries its own requests and environments

History is your audit trail — git blame and git log answer who changed an endpoint and when

Onboarding is a clone — a new developer gets every collection by checking out the repo

No drift between docs and code — a stale collection shows up as an unmerged diff, not a forgotten cloud workspace

What to commit

Local workspace storage lives in .openpost/. Some of it is shared team state; some of it is personal and noisy.

File	Commit?	Why
collections.json	Yes	The shared API definition — the whole point
environments.json	Yes	Shared variable sets — but never real credentials
mock-servers.json	Yes	Teammates get the same mock backends
snapshots.json	Yes	Response structure snapshots act as a contract baseline
config.json	Yes	Project settings the team should share
session.json	No	Your open tabs — changes constantly, means nothing to others
cookies.json	No	Your personal session cookies
history.json	Optional	Can grow large and is personal; usually ignored

Recommended .gitignore entries:

.openpost/session.json
.openpost/cookies.json
.openpost/history.json

Global storage is never committed. ~/.openpost/global/ holds your licence key, vault and personal preferences. It lives outside the project directory, so there is nothing to exclude.

Keeping secrets out of the repository

environments.json is a committed file, so treat it as public to everyone with repository access.

Put tokens and passwords in the encrypted vault, which is global-only and never enters the project

Commit environments containing only non-sensitive values — base URLs, API versions, feature flags

Secret values are automatically scrubbed from history before it is written to disk, so an accidentally committed history.json does not leak them

In pipelines, inject credentials from your CI secret store — see CI/CD Integration

Reviewing API changes in a pull request

Because collections are committed JSON, a change to an endpoint appears in the pull request next to the handler that serves it. Reviewers see the request change and the implementation change together.

$ git diff --stat
 src/routes/users.ts              | 24 ++++++++---
 .openpost/collections.json       | 18 +++++---
 2 files changed, 31 insertions(+), 11 deletions(-)

Things worth asking for in review:

A new endpoint arrives with a request in the collection, not in a follow-up commit

A changed response shape updates its test rules in the same diff

No literal credentials appear in the environments.json hunk

Pair this with the pipeline from CI/CD Integration so the collection is also executed on the pull request, not only read.

Merge conflicts, honestly

Worth being straightforward about a real trade-off. API Studio stores every collection in a single .openpost/collections.json array rather than one file per request. That keeps the format simple and makes the whole workspace portable, but it means two people editing different requests in the same workspace are still editing the same file, and git may report a conflict where a per-request layout would not.

In practice this is manageable, and these habits keep it small:

Commit collection changes on their own. A small, focused commit is far easier to resolve than one bundled with a large refactor

Rebase before you push. Most conflicts here come from a stale branch, not genuinely incompatible edits

Split by service, not by person. In a monorepo, give each service its own workspace directory so teams touch different .openpost/ folders

Requests carry stable UUIDs. Objects are matched by id, so a conflict is normally resolved by keeping both objects rather than merging text line by line

Ignore the noisy files. Most spurious conflicts come from session.json and history.json. Gitignore them and the problem largely disappears

When a conflict does happen, both sides are valid JSON objects in an array, so resolution is usually mechanical — take both entries and verify the result parses:

# after resolving the conflict markers by hand
jq empty .openpost/collections.json && echo "valid JSON"

# confirm nothing broke
openpost list collections
openpost run "My API" --dry-run

--dry-run validates configuration and variable interpolation without sending any traffic, which makes it a safe post-merge check.

Setting a team up

Commit the workspace

Add .openpost/ with the gitignore entries above. One developer does this once.

Everyone clones

Opening the folder in VS Code picks up the collections automatically. No import, no invite, no licence seat to assign.

Each developer sets up their own secrets

Vault contents are personal and global. Shared environments reference secrets by name, so each person supplies their own values.

Wire the collection into CI

Run it on every pull request so a broken endpoint fails review rather than production. See CI/CD Integration.

Monorepos and multiple workspaces

Local storage is per workspace, so a monorepo can hold one .openpost/ per service. Each team owns its own file, which removes most cross-team conflicts outright.

repo/
├── services/
│   ├── billing/
│   │   └── .openpost/collections.json   ← billing team
│   └── identity/
│       └── .openpost/collections.json   ← identity team
└── .github/workflows/api-tests.yml

Point the CLI at whichever workspace you need:

openpost run "Billing API" --workspace services/billing --env staging

Collections that genuinely belong to everyone can live in global storage instead — see Data Storage.

CI/CD Integration → Data Storage → Collection JSON Schema →