Version Control with Bruno and Bitbucket

Bitbucket is a Git hosting platform developed by Atlassian. Like GitHub and GitLab, it allows developers to store, manage, and collaborate on code — but with tighter integration into Atlassian’s suite of tools like Jira and Confluence.

In this guide, we’ll walk through how to integrate Bitbucket with Bruno to enable version-controlled API development using Bruno’s built-in Git UI (a premium feature). By the end, you’ll have your API collection stored in a Bitbucket repo and fully synced with your local Bruno environment.

What is a Version Control System (VCS)?

Before jumping into the setup, let’s quickly cover the “why” behind this workflow.

A Version Control System (VCS) tracks and manages changes to files over time. For software development, that means you can:

• View the history of changes to your code or API definitions

• Revert to earlier versions when something breaks

• Collaborate with others without overwriting work

• Review changes through diffs and pull requests

Bruno is the only API client that stores collections/folders/requests as files on your local filesystem, allowing for native Git-based workflows. This gives you a huge advantage in versioning, collaboration, and ultimately feeling confident in your source of truth. 

Git Hosting Providers

A Git hosting platform helps you to deploy your local working directory (repository) to the cloud. It's helpful for organization to collaborate, automate, and maintain clean str

In the competitive landscape of Git hosting services, Bitbucket stands as a strong contender alongside two giants:

• Bitbucket: Bitbucket's strength lies in its tight integration with the Atlassian ecosystem. For organizations already using Jira (project management), Confluence (collaboration wiki), or other Atlassian products, Bitbucket provides a seamless experience for linking code changes directly to issues, tracking progress, and centralizing project data. 
• GitHub: Often considered the market leader, especially for open-source projects and its massive developer community. It boasts extensive collaboration features, integrated CI/CD (GitHub Actions), and a broad ecosystem of tools. GitHub generally has the largest user base.
• GitLab: Positions itself as a complete "DevOps platform" that encompasses the entire software development lifecycle, from project planning and source code management to CI/CD, security scanning, and monitoring – all in a single application. GitLab has seen significant growth by offering a comprehensive, end-to-end solution.

What Makes Bruno Unique?

Bruno is an open-source, fast, and Git-friendly API client. Unlike some other API clients that store collections in proprietary formats or hidden cloud databases, Bruno stores your API requests as simple, human-readable .bru files directly on your local filesystem. This design choice makes Bruno exceptionally well-suited for Git-based version control.

When you save a request in Bruno, it creates a .bru file. When you modify it, the .bru file changes. This means you can commit, push, pull, and manage your API definitions just like your source code.

Bruno's Team Collaboration Feature: Bruno enhances team collaboration over API development by providing in-app Git UI functionality. This feature allows teams to:

• Perform Git operations (commit, pull, push, branch, etc.) without leaving Bruno.
• Track changes to API requests visually.

This functionality is part of Bruno's commercial offering, aimed at streamlining workflows for professional teams. It bridges the gap between your API client and your version control system, making API development a truly collaborative and version-controlled process.

Step 1: Create a Repository in Bitbucket

If you don't already have one, create a new Git repository in Bitbucket. This is where your Bruno API collection will live.

1. Log in to your Bitbucket account (bitbucket.org).
2. Click on the + icon in the left sidebar and select Repository.
3. Give your repository a meaningful name (e.g., `my-api-collection`).
4. Choose access level (Public/Private).
5. Select Git as the version control system (this is the default).
6. Click Create repository.

After creation, Bitbucket will provide you with the Git URL

git@bitbucket.org:your_team/my-api-collection.git

or

git@bitbucket.org:your_team/my-api-collection.git

Step 2: Configure Authentication with Bitbucket (SSH Key)

To interact with your Bitbucket repository from your local machine and Bruno, you need to authenticate securely. There are two primary methods: SSH Keys (recommended for convenience and security) or App Passwords (for HTTPS connections).

Option A: Using SSH Keys

SSH keys provide a more secure and convenient way to authenticate, as you don't have to enter your password repeatedly.

1. Generate an SSH key pair (if you don't have one): Open your terminal or Git Bash.

   ssh-keygen -t rsa -b 4096 -C your_email@example.comb -f ~/.ssh/id_rsa_bitbucket
   

   Press Enter to accept the default file location (`~/.ssh/id_rsa`). You can optionally set a passphrase for added security (you'll need to enter it once per session).
2. Add your SSH key to the SSH agent:

   ssh-add ~/.ssh/id_rsa_bitbucket
   

   If you used a different file name, specify that path.
3. Copy your Public SSH key:

   cat ~/.ssh/id_rsa_bitbucket.pub 
   

   Copy the entire output, starting with `ssh-rsa` and ending with your email.
4. Add the SSH key to Bitbucket:
   • Log in to Bitbucket.
   • Go to your Account Settings > SSH keys.
   • Click Add key.
   • Give it a descriptive label (e.g., "My Laptop").
   • Paste your copied public SSH key into the Key field.
   • Click Add key.
5. Test SSH Connection:

   ssh -T git@bitbucket.org 
   

   You should see a message like "authenticated via ssh key" and "You can use Git to connect to Bitbucket."

Step 3: Initialize and Link Your Bruno Collection into the Repository

Now, tell Bruno to link this local directory (API Collection) to the the Bitbucket repo.

1. Launch the Bruno desktop application.
2. Add New Collection:
   • If you have an existing Bruno collection you want to version control:
     
     • Click on the Branch icon (next to Safe Mode) and initialized the directory with Git.
   • If you're starting a brand new collection:
     • Create a new Create New Collection and initialized it.

3.  Add Remotes:

   Go to remotes and add the origin (link copied previously).


Step 4: Perform Git Operations Directly in Bruno

Bruno offers an integrated Git UI for seamless version control operations. This is typically available as part of Bruno's premium features designed for teams.

Check out the official documentation to learn more about Bruno’s Git UI functionality and how to use all its available operations effectively.

Step 5: Verify Changes in Bitbucket

After pushing your changes from Bruno, go back to your Bitbucket repository in your web browser. You should see your .bru files and any other changes reflected in the repository's file browser and commit history.

Wrap Up

By integrating Bruno with Bitbucket, you elevate your API development from a standalone process to a fully version-controlled, collaborative workflow. This ensures that your API definitions are as well-managed as your code, enabling better team synchronization, clearer history tracking, and a more robust development lifecycle.

Want to learn more? Come join us on the Bruno Discord!