Getting started overview

Getting started with Bitbucket involves creating an Atlassian account, configuring appropriate credentials for either Git operations or API access, and performing a first action, such as cloning a repository or making an authenticated API call. Bitbucket Cloud offers a free tier for small teams, providing unlimited private repositories for up to five users, making it accessible for individual developers and small projects Bitbucket pricing details. This guide outlines the steps to get you operational quickly.

The core process can be summarized into these key stages:

  1. Account Creation: Establish an Atlassian account, which grants access to Bitbucket Cloud.
  2. Credential Setup: Configure SSH keys for secure Git repository access or generate Bitbucket App Passwords for programmatic API interactions.
  3. First Interaction: Perform an initial operation, such as cloning an existing repository or executing a simple Bitbucket Cloud REST API request.

This page focuses on programmatic access via the REST API and command-line Git operations, providing a foundational understanding for integrating Bitbucket into development workflows.

Getting started quick reference

Step What to Do Where
1. Sign up Create a free Atlassian account. Bitbucket homepage
2. Create Workspace Set up your workspace name. Bitbucket Cloud UI (after login)
3. Generate SSH Key (optional) Create and add an SSH key for Git access. Local terminal and Bitbucket SSH Key setup
4. Generate App Password Create an App Password for API access. Bitbucket App Passwords documentation
5. First Git Call Clone a repository (if using SSH/HTTPS). Local terminal
6. First API Call Execute a simple REST API request. Local terminal (cURL) or programming environment

Create an account and get keys

To begin, you need an Atlassian account. This account serves as your login for all Atlassian products, including Bitbucket Cloud. If you already have an account from Jira or Confluence, you can use those credentials.

1. Sign up for an Atlassian account

  1. Navigate to the Bitbucket website.
  2. Click on "Get it free" or "Sign up."
  3. Follow the prompts to create your Atlassian account. This typically involves providing an email address, setting a password, and confirming your email.
  4. Once logged in, you will be guided to create a workspace, which is your primary organizational unit in Bitbucket. Choose a unique name for your Bitbucket workspace.

2. Set up authentication credentials

Bitbucket supports different authentication methods depending on whether you are interacting with Git repositories directly or calling the Bitbucket Cloud REST API. For Git operations, SSH keys are recommended for security and convenience. For API calls, App Passwords provide granular control over permissions.

a. Generate SSH keys for Git access (recommended for command-line Git)

SSH (Secure Shell) keys provide a secure way to connect to Bitbucket without repeatedly entering your password. This is generally preferred for command-line Git operations.

  1. Generate a new SSH key pair: Open your terminal or Git Bash and run:ssh-keygen -t rsa -b 4096 -C "[email protected]"
    Follow the prompts to save the key to a default location (e.g., ~/.ssh/id_rsa) and optionally set a passphrase.
  2. Copy your public SSH key: You need to copy the contents of your public key file (typically ~/.ssh/id_rsa.pub). On Linux/macOS, you can use:cat ~/.ssh/id_rsa.pub
    On Windows, use:Get-Content ~/.ssh/id_rsa.pub (PowerShell) or open the file in a text editor.
  3. Add the SSH key to Bitbucket:
    1. Log in to Bitbucket Cloud.
    2. Click on your avatar in the top right corner and select Personal settings.
    3. Under Security, click SSH keys.
    4. Click Add key, paste your public key string into the 'Key' field, and provide a descriptive 'Label'.
    5. Click Add key to save. For detailed instructions, refer to the Bitbucket SSH Key setup guide.

b. Generate App Passwords for API access (for REST API calls)

App Passwords are an alternative to your main Atlassian account password, designed for API access or integration with third-party applications. They allow you to grant specific permissions without exposing your primary login credentials.

  1. Log in to Bitbucket Cloud.
  2. Click on your avatar in the top right corner and select Personal settings.
  3. Under Access management, click App passwords.
  4. Click Create app password.
  5. Provide a descriptive 'Label' for your app password (e.g., "My API Integration").
  6. Select the specific permissions required for your API integration. For a first test, you might grant "Read" permissions for repositories. Granting only necessary permissions adheres to the principle of least privilege, a core security practice.
  7. Click Create.
  8. Important: Copy the generated App Password immediately. It will only be displayed once. Treat it like a sensitive password and store it securely.

Your first request

After setting up your credentials, you can make your first interaction with Bitbucket. This section covers both a Git operation and a REST API call.

a. First Git operation: Clone a repository

If you're interacting with Bitbucket via Git, cloning an existing repository is a fundamental first step.

  1. Create a new repository (if you don't have one):
    1. In Bitbucket Cloud, navigate to your workspace.
    2. Click Create repository.
    3. Provide a name, choose an access level (public/private), and optionally initialize with a README.
    4. Click Create repository.
  2. Get the clone URL:
    1. Navigate to your new or existing repository in Bitbucket.
    2. Click the Clone button on the top right.
    3. Copy either the SSH URL (e.g., [email protected]:<workspace>/<repo-name>.git) or the HTTPS URL (e.g., https://bitbucket.org/<workspace>/<repo-name>.git). If using HTTPS with an App Password, your username will be your Bitbucket username, and the password will be the App Password.
  3. Clone the repository locally: Open your terminal or Git Bash and run:git clone <your-repository-clone-url>
    If using SSH, you'll be prompted for your SSH key passphrase if you set one. If using HTTPS, you'll be prompted for your Bitbucket username and App Password.

b. First API request: List repositories

To verify your App Password and API access, you can make a simple cURL request to list your repositories. Replace <your-username> with your Bitbucket username and <your-app-password> with the App Password you generated.

curl -u "<your-username>:<your-app-password>" \
  https://api.bitbucket.org/2.0/repositories/<your-workspace-name>

If successful, this command will return a JSON array of repositories within your specified workspace. The Bitbucket Cloud REST API documentation provides comprehensive details on available endpoints and request formats Bitbucket Cloud REST API reference.

Common next steps

After successfully performing your first Git operation or API call, consider these next steps to deepen your integration with Bitbucket:

  • Explore Bitbucket Pipelines: Bitbucket Pipelines offers integrated CI/CD directly within Bitbucket. You can define build, test, and deploy steps in a bitbucket-pipelines.yml file in your repository Bitbucket Pipelines getting started guide.
  • Set up Webhooks: Configure webhooks to receive notifications when specific events occur in your repositories (e.g., pushes, pull requests). This is crucial for integrating Bitbucket with external services or custom automation Bitbucket webhook management.
  • Integrate with Jira: If your team uses Jira, link your Bitbucket repositories to your Jira projects. This enables seamless tracking of code changes, commits, and pull requests directly within Jira issues Jira Bitbucket integration.
  • Explore OAuth 2.0: For developing applications that access Bitbucket on behalf of users, investigate Bitbucket's OAuth 2.0 implementation. This provides a secure and standardized way for users to grant your application limited access to their Bitbucket data without sharing their credentials Bitbucket OAuth 2.0 Client Credentials. The OAuth 2.0 framework is widely adopted for secure delegation of authorization across many APIs, as detailed by the OAuth.net resource.
  • Review API Documentation: Familiarize yourself with the full Bitbucket Cloud REST API reference to understand the breadth of available endpoints for managing repositories, pull requests, issues, and more programmatically.

Troubleshooting the first call

Encountering issues during your first interaction with Bitbucket is common. Here are some troubleshooting tips:

  • Incorrect App Password/Username: Double-check that you are using the correct Bitbucket username (not your email) and the exact App Password generated. Remember that App Passwords are only shown once. If lost, you must generate a new one.
  • Insufficient App Password Permissions: Ensure the App Password has the necessary permissions for the API call you are attempting. For listing repositories, it generally needs at least "Repository: Read" permission.
  • Incorrect Repository/Workspace URL: Verify that the repository clone URL or API endpoint URL is accurate, including the correct workspace name and repository slug.
  • SSH Key Issues (for Git):
    • Key not added to Bitbucket: Confirm your public SSH key is correctly added to your Bitbucket personal settings.
    • Incorrect key permissions: Ensure your private key file has appropriate permissions (e.g., chmod 600 ~/.ssh/id_rsa on Unix-like systems).
    • SSH agent not running: On some systems, you might need to start the SSH agent and add your key: eval "$(ssh-agent -s)" and then ssh-add ~/.ssh/id_rsa.
    • Firewall/Proxy: Corporate firewalls or proxies can sometimes interfere with Git/SSH connections. Consult your network administrator if you suspect this is the case.
  • Network Connectivity: Confirm your internet connection is stable and you can reach api.bitbucket.org or bitbucket.org.
  • cURL Syntax Errors: Carefully review your cURL command for any typos in flags (e.g., -u for user:password authentication) or URLs.
  • Rate Limiting: While unlikely for a first call, if you're making multiple rapid requests, Bitbucket's API may impose rate limits. Refer to the Bitbucket rate limiting documentation for details.

If you continue to experience issues, the Bitbucket Cloud Support documentation is an extensive resource for common problems and solutions.