Git Integration

Overview

Bruno’s file-based approach makes it perfect for version control with Git. Since collections are stored as plain text .bru files in folders on your filesystem, you can use Git (or any version control system) to track changes, collaborate with your team, and maintain a history of your API development.

Bruno stores your collections directly in a folder on your filesystem using a plain text markup language (Bru) to save information about API requests. This design choice makes version control natural and seamless.

Why Git + Bruno?

Plain Text Format

.bru files are human-readable text files that work perfectly with Git’s diff and merge capabilities

Offline-First

No cloud sync means your data stays on your device and in your Git repository

Team Collaboration

Multiple team members can work on the same collection using Git workflows

Change History

Track every change to your API requests with full Git history

Setting Up Git for Your Collection

Initialize Git repository

Navigate to your collection folder and initialize Git:

cd my-api-collection
git init

Create .gitignore

Create a .gitignore file to exclude sensitive data:

.gitignore

# Environment secrets (keep local)
environments/Local.bru
environments/*.local.bru

# Bruno metadata
.bruno/

# OS files
.DS_Store
Thumbs.db

# IDE
.idea/
.vscode/
*.swp

Add collection files

Add your collection files to Git:

git add .
git commit -m "Initial commit: Add API collection"

Push to remote

Push to GitHub, GitLab, or your preferred Git hosting:

git remote add origin https://github.com/username/my-api-collection.git
git push -u origin main

Collection Structure in Git

Here’s what a typical Bruno collection looks like in a Git repository:

my-api-collection/
├── .git/                      # Git metadata
├── .gitignore                 # Ignore sensitive files
├── README.md                  # Collection documentation
├── bruno.json                 # Collection configuration
├── collection.bru             # Collection-level settings
├── environments/              # Environment variables
│   ├── Production.bru         # Committed (no secrets)
│   ├── Staging.bru           # Committed (no secrets)
│   └── Local.bru.example     # Template for local env
├── auth/                      # Authentication requests
│   ├── folder.bru
│   ├── login.bru
│   └── refresh-token.bru
└── api/
    └── v1/
        ├── users/
        │   ├── folder.bru
        │   ├── list-users.bru
        │   ├── create-user.bru
        │   └── get-user.bru
        └── posts/
            ├── folder.bru
            └── list-posts.bru

Managing Secrets with Git

Bruno provides a vars:secret block to mark sensitive variables:

Local.bru

vars {
  host: http://localhost:8080
  client_id: my_client_id
  api_key: sk_test_abc123
}

vars:secret [
  client_id,
  client_secret,
  api_key,
  bearer_token
]

Variables marked as secrets should not be committed. Add environment files with secrets to .gitignore and commit template files instead.

Environment File Strategy

Option 1: Template Files

# Commit template (no actual secrets)
environments/Local.bru.example
environments/Production.bru.example

# Gitignore actual files
environments/Local.bru
environments/Production.bru

Option 2: Separate Secrets

Production.bru

vars {
  # Safe to commit
  protocol: https
  host: api.example.com
  baseUrl: {{protocol}}://{{host}}
  apiVersion: v1
}

Production.secrets.bru

# Add to .gitignore
vars {
  api_key: sk_live_actual_secret_key
  client_secret: actual_client_secret
}

vars:secret [
  api_key,
  client_secret
]

Collaborative Workflows

Feature Branch Workflow

Create feature branch

git checkout -b feature/add-user-endpoints

Add new requests

Create new .bru files for your endpoints:

# Add files in Bruno UI or create manually
touch api/v1/users/update-user.bru
touch api/v1/users/delete-user.bru

Commit changes

git add api/v1/users/
git commit -m "feat: Add user update and delete endpoints"

Push and create PR

git push origin feature/add-user-endpoints
# Create Pull Request on GitHub/GitLab

Review and merge

Team members can review the .bru files in the PR, test the requests, and merge when ready.

Reviewing Changes

Git diffs of .bru files are human-readable:

diff --git a/api/v1/users/create-user.bru b/api/v1/users/create-user.bru
index 1234567..abcdefg 100644
--- a/api/v1/users/create-user.bru
+++ b/api/v1/users/create-user.bru
@@ -8,7 +8,7 @@ post {
 }
 
 headers {
-  Content-Type: application/json
+  Content-Type: application/json; charset=utf-8
+  X-API-Version: v1
 }
 
 body:json {

Branching Strategies

GitFlow for API Collections

main (production-ready requests)
  ↓
develop (integration branch)
  ↓
feature/add-payment-endpoints
feature/update-auth-flow
bugfix/fix-user-endpoint

Environment-Based Branches

Some teams use branches for different environments:

main → Production environment
staging → Staging environment  
develop → Development environment

Merge Conflicts

Because .bru files are plain text with clear block structure, conflicts are easy to resolve:

meta {
  name: Get User
  type: http
<<<<<<< HEAD
  seq: 1
=======
  seq: 2
>>>>>>> feature-branch
}

Resolve by choosing the correct sequence number or merging the changes.

Git Hooks for Collections

Pre-commit Hook: Validate .bru Files

Create .git/hooks/pre-commit:

#!/bin/bash

# Validate all .bru files before commit
for file in $(git diff --cached --name-only | grep '.bru$'); do
  echo "Validating $file"
  # Add validation logic here
  # You could use bruno-lang parser or custom validation
done

echo "All .bru files validated!"

Pre-commit Hook: Check for Secrets

#!/bin/bash

# Check for potential secrets in committed files
if git diff --cached | grep -i 'password\|secret\|api_key' > /dev/null; then
  echo "⚠️  Warning: Potential secrets detected in commit!"
  echo "Please review your changes for sensitive data."
  exit 1
fi

README for Your Collection

Create a comprehensive README for your collection repository:

README.md

# My API Collection

Bruno collection for the MyApp API.

## Setup

1. Install [Bruno](https://www.usebruno.com/downloads)
2. Clone this repository
3. Copy `environments/Local.bru.example` to `environments/Local.bru`
4. Update Local.bru with your local configuration
5. Open the collection in Bruno

## Environments

- **Local**: Development on localhost
- **Staging**: Testing environment
- **Production**: Live API (requires credentials)

## Folder Structure

- `/auth` - Authentication endpoints
- `/api/v1/users` - User management
- `/api/v1/posts` - Post operations

## Contributing

1. Create a feature branch: `git checkout -b feature/my-feature`
2. Add/update `.bru` files
3. Commit: `git commit -m "feat: Add new endpoint"`
4. Push and create PR

## Secrets

Never commit actual API keys or secrets. Use `environments/Local.bru.example` 
as a template and keep actual credentials in your local `Local.bru` file.

CI/CD Integration

Running Collections in CI

Use Bruno CLI to run collections in your CI pipeline:

.github/workflows/api-tests.yml

name: API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Bruno CLI
        run: npm install -g @usebruno/cli
      
      - name: Run API Tests
        run: |
          bru run --env Local \
            --output results.json \
            --format json
        env:
          API_KEY: ${{ secrets.API_KEY }}
      
      - name: Upload Results
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: results.json

GitLab CI Example

.gitlab-ci.yml

api-tests:
  stage: test
  image: node:18
  script:
    - npm install -g @usebruno/cli
    - bru run --env Staging --reporter json
  artifacts:
    reports:
      junit: bruno-results.xml

Best Practices

Semantic Commits

Use conventional commits: feat:, fix:, docs:, refactor:

Atomic Commits

One logical change per commit (e.g., one endpoint or related group)

Descriptive Names

Name .bru files clearly: create-user.bru, list-posts.bru

Code Review

Review .bru files in PRs just like code

Documentation

Keep README.md updated with collection structure and setup

Templates

Commit .example files for environment templates

Protect Secrets

Use .gitignore and vars:secret to prevent leaking credentials

Organize Folders

Use logical folder structure that mirrors your API

Migrating from Other Tools

If you’re migrating from Postman or Insomnia:

Export from current tool

Export your collection as JSON

Import to Bruno

Use Bruno’s import feature to convert to .bru format

Initialize Git

Set up Git repository as described above

Commit and push

Commit the imported collection and push to your Git hosting

Example: Team Workflow

Here’s how a team might use Bruno with Git:

1. Developer creates feature branch
   git checkout -b feature/payment-endpoints

2. Adds payment endpoints in Bruno
   - payments/create-payment.bru
   - payments/refund-payment.bru

3. Updates folder.bru with shared settings
   - Add auth headers
   - Add base URL

4. Commits and pushes
   git add payments/
   git commit -m "feat: Add payment endpoints"
   git push origin feature/payment-endpoints

5. Creates Pull Request
   - Team reviews .bru files
   - Tests endpoints locally
   - Approves and merges

6. Merges to main
   - CI runs collection tests
   - All team members pull latest
   - New endpoints available to everyone

Next Steps

Collections

Learn more about organizing your collections

Environments

Master environment and variable management

CLI

Run collections from the command line

Testing

Add tests to validate your APIs

Get Started

Core Concepts

Desktop App

CLI

Advanced

Integrations

​Overview

​Why Git + Bruno?

Plain Text Format

Offline-First

Team Collaboration

Change History

​Setting Up Git for Your Collection

​Collection Structure in Git

​Managing Secrets with Git

​Environment File Strategy

​Collaborative Workflows

​Feature Branch Workflow

​Reviewing Changes

​Branching Strategies

​GitFlow for API Collections

​Environment-Based Branches

​Merge Conflicts

​Git Hooks for Collections

​Pre-commit Hook: Validate .bru Files

​Pre-commit Hook: Check for Secrets

​README for Your Collection

​CI/CD Integration

​Running Collections in CI

​GitLab CI Example

​Best Practices

Semantic Commits

Atomic Commits

Descriptive Names

Code Review

Documentation

Templates

Protect Secrets

Organize Folders

​Migrating from Other Tools

​Example: Team Workflow

​Next Steps

Collections

Environments

CLI

Testing

Build docs developers (and LLMs) love

Overview

Why Git + Bruno?

Setting Up Git for Your Collection

Collection Structure in Git

Managing Secrets with Git

Environment File Strategy

Collaborative Workflows

Feature Branch Workflow

Reviewing Changes

Branching Strategies

GitFlow for API Collections

Environment-Based Branches

Merge Conflicts

Git Hooks for Collections

Pre-commit Hook: Validate .bru Files

Pre-commit Hook: Check for Secrets

README for Your Collection

CI/CD Integration

Running Collections in CI

GitLab CI Example

Best Practices

Migrating from Other Tools

Example: Team Workflow

Next Steps