Bitbucket for Salesforce: A Developer’s Guide to Version Control Setup

Salesforce development has evolved far beyond making changes directly in Production or unmanaged Sandboxes. Adopting a modern DevOps architecture requires a reliable source of truth, and Bitbucket serves as a powerful repository for managing Salesforce Metadata and Source Code.

This guide walks technical users—including Salesforce Admins, Developers, Analysts, and Architects—through configuring Bitbucket for Salesforce version control from scratch using the Salesforce CLI and VS Code.

Prerequisite

First, install and setup VS Code for your Salesforce Project.

How to install and set up VS Code for Salesforce?

Step 1: Generate a Bitbucket API Token

To authenticate your local repository with Bitbucket securely (without using your main account password), you must create a dedicated API token.

• Log in to your Bitbucket account.
• Navigate to Personal settings > API tokens.
• Select Create API token with appropriate repository scopes (e.g., Read, Write).
• Copy and securely store the generated token.

Step 2: Initialize & Push Code via VS Code Terminal

Open your local Salesforce project directory in VS Code and run the following commands sequentially in the terminal:

git init
git add .
git commit -m "Initial commit"
git remote add origin <PASTE_YOUR_BITBUCKET_URL_HERE>
git branch -M main
git push -u origin main

Step 3: Authenticate the Push

When prompted by Git for your credentials in the terminal:

• Username: Enter your Bitbucket username.
• Password: Use the API Token created in Step 1 instead of your personal Bitbucket password.

Git Best Practices & Recommendations

• Never Hardcode Secrets: Avoid saving API Tokens, password strings, or Salesforce login credentials directly in your project code or repository files.
• Maintain a .gitignore File: Ensure temporary files, local environment variables, and IDE configuration folders (like .sf/, .sfdx/, or .vscode/) are ignored prior to running git add ..
• Standardize Branching Strategies: Utilize feature branches (e.g., feature/JIRA-123) rather than pushing directly to the main branch to maintain a clean source of truth for deployment pipelines.