Structuring Git for API Collection Collaboration

“Why don’t other tools do this?” is the first question Bruno newcomers ask—and for good reason. Native Git-sync for API Collections destroys tribal-knowledge silos, unversioned specs, and duplicate work in one sweep.

In large orgs you’ll often find thousands .... even hundreds of thousands... of Bruno collections scattered across teams.

The vast majority are:

• Redundant or stale

• Locked behind cloud workspaces that developers rarely update

• Disconnected from the code they’re meant to validate

Other API clients lean on SharePoint- or Confluence-style hubs—and that brings two big headaches:

• Terrible upkeep: internal wikis age like milk

• Fragmented truth: another system apart from your Git repos, so tests drift from code

Bruno flips the script by making your Git provider the single source of truth for API Collections. Because a Git-first model still feels novel, teams often ask: “How should we organize our collections in Git?”

In this post, we’ll unpack the three most common patterns—polyrepo, monorepo, and colocation—and show when (and why) to use each.

Spoiler: at scale, you’ll likely run a mix of all three.

Why Structure Matters

A coherent Git layout helps teams share, version, and evolve Bruno collections alongside the rest of their code. Pick the wrong pattern and you’ll wrestle with scattered CI, fractured permissions, and surprise merge conflicts. Pick the right one and onboarding is frictionless, cross-team collaboration hums, and even large portfolios feel manageable.

1. Single repo per collection (polyrepo)

“One collection, one repo.”

What it is

• Each Bruno collection lives in its own Git repository.
• Typically named after the API/resource (e.g. payments-collection, orders-api-tests).

When teams choose it

• Small number of collections (1–5).
• Collections owned by different teams or vendors.
• High-security or compliance boundaries.

Key benefits

• Isolation & clarity
  • No unrelated code—every commit is 100% about that collection.
  • Fine-grained access control: you can lock down a repo per team or client.
• Independent CI/CD
  • Pipelines only run for relevant changes (builds finish in <2 min).
  • Easier to set up collection-specific test matrices.
• Versioning discipline
  • Semantic-version tags (v1.2.0) map exactly to collection releases.

Trade-offs to consider

• Repo sprawl
  • Managing 20+ repos can become a chore—cloning, updates, permissions.
• Cross-collection changes
  • If you update a common script/snippet, you must PR each repo.
• Discoverability
  • New team members need a directory of all repos (we’ve seen “lost” collections 15% of the time).

When to pick it

• • You have 1–3 collections or strict security domains.
  • Collections evolve at different cadences or are owned by siloed teams.

Here's an example of a polyrepo structure where we have a number of public collections stored. 

2. One repo for all collections (monorepo)

“Everything under one roof.”

What it is

• All collections live in a single repository (e.g. /collections/payments, /collections/orders, /collections/users).
• Shared CI pipeline that can trigger per-folder workflows.

Why teams choose it 

• GitHub, GitLab, and tools like Nx/Lerna have beefed up monorepo support in the last 2 years.
• If you want to offer other teams in your company access to all collections for your product(s), simply point them to one repo
• If you're a DevRel/DevEx team that maintains collections for a bunch of product groups, having a single area for this work can add efficiency. 

Key benefits

• Centralized discoverability
  • One repo to search, star, and clone.
  • A single README can document all collections and usage patterns.
• DRY pipelines & tooling
  • Reuse shared GitHub Actions or GitLab CI templates (e.g. ./ci/run-collection.sh).
  • Enforce standards (linting, naming) across all collections.
• Atomic commits
  • Update multiple collections in one PR (e.g. bumping auth headers everywhere).

Trade-offs to consider

• Build overhead
  • CI runs may take longer if not properly configured (avoid building untouched folders).
• Merge conflicts risk
  • Teams touching shared CI or root files can step on each other.
• Permissions granularity
  • Harder to restrict folder-level access without Git submodules or sparse-checkout hacks.

When to pick it

1. • You manage 5+ collections with many shared conventions.
   • You’re comfortable setting up folder-aware CI (using path filters).
   • You want to release collection updates in lockstep (e.g. monthly “API sync”).

2. Co-locating collections alongside API specs / source code

   “Tests live where the code lives.”

   What it is

   • Bruno collections live in the same repo as your code or OpenAPI specs (/src, /specs, /collections together).
   • Often mirrors your microservices or API-first repo structure.

   Why it’s contrarian—and why it works

   • Conventional wisdom says “separate tests from code,” but modern API-first teams treat collections as part of their code artifact.
   • By versioning tests + code together, you guarantee test-spec sync at every commit.

   Key benefits

   • Guaranteed alignment
     • Every commit changing an API also updates its Bruno collection (no drift).
   • One-stop developer experience
     • Devs clone a service, run code, and immediately have corresponding tests.
   • Simplified branching
     • Feature branches include both new endpoints and test updates—no orphaned branches.

   Trade-offs to consider

   • Repo size growth
     • Collections (especially with recorded responses) can bloat your service repo.
   • CI coupling
     • Service pipelines must now run Bruno tests, potentially lengthening deploy times.
   • Cross-service consistency
     • Harder to share snippets or variables across multiple services without submodules or mono-repo overlays.

   When to pick it

   • You follow an API-first or microservices approach and want zero drift.
   • Teams are small and own both code and tests.
   • You prioritize tight feedback loops over isolated test management.

My take (opinionated!)

• Lead with co-locating if your team ship services + tests together. You’ll catch breaking changes before they ever leave CI.
• Use monorepos to provide either a set of reference collections or share with teams/users who don't/can't have access to your source code
• Only splinter into single-collection repos when you hit security boundaries, open-source collections, or wildly divergent release cadences.

Final thoughts

No one pattern fits every team—pick based on scale, compliance needs, and how tightly you want your tests to track code. And don’t forget the new tools (Nx workspaces, Git sparse-checkout, GiTrove) that make hybrid approaches possible. Whatever you choose, Bruno’s CLI and Git integrations will adapt—so you can focus on testing, not Git gymnastics.