# Bitbucket
Connect your private Bitbucket repository to Valohai using SSH authentication. Bitbucket access keys provide secure, read-only access and can be reused across multiple repositories.
## Requirements
* A private Bitbucket repository
* A Valohai project
* Admin access to the repository (to add access keys)
## Overview
You'll complete three steps:
1. Generate an SSH key pair (in Valohai)
2. Add the public key to Bitbucket as an access key
3. Add the private key to Valohai
## Step 1: Generate SSH Key Pair
The easiest way is to generate the key pair directly in Valohai.
**In Valohai:**
1. Open your project
2. Go to **Settings** → **Repository**
3. Click **Generate SSH Key**
4. Download or copy both keys:
* `valohai-public_xxx.pub` (public key)
* `valohai-private_xxx.pem` (private key)
Keep these files handy—you'll need them in the next steps.
### Alternative: Generate Locally
If you prefer, generate keys on your local machine:
```shell
ssh-keygen -t rsa -b 4096 -f valohai-deploy-key
```
This creates:
* `valohai-deploy-key.pub` – Public key for Bitbucket
* `valohai-deploy-key` – Private key for Valohai
> **Don't commit these keys to Git.** Anyone with the private key can access your repository.
## Step 2: Add Public Key to Bitbucket
Navigate to your repository's access keys settings:
1. Go to your Bitbucket repository
2. Click **Settings** → **Access Keys** → **Add key**
**Configure the access key:**
* **Label:** `Valohai` (or any descriptive name)
* **Key:** Paste the entire contents of the `.pub` file
* Should start with `ssh-rsa AAAA...`
Click **Add key** to save.
> :bulb: **Bitbucket access keys are read-only by default**—no additional configuration needed.
## Step 3: Add Private Key to Valohai
Now connect the repository in Valohai.
**Get your SSH repository URL from Bitbucket:**
1. Go to your repository on Bitbucket
2. Click **Clone** (top right)
3. Ensure **SSH** is selected (not HTTPS)
4. Copy the URL (format: `git@bitbucket.org:username/repository.git`)
**In Valohai:**
1. Go to **Settings** → **Repository**
2. Paste the SSH URL into the **URL** field:
```
git@bitbucket.org:username/repository.git
```
3. Paste the **entire contents** of the private key file into **SSH private key**:
* Should start with `-----BEGIN RSA PRIVATE KEY-----`
* Include all lines, including the header and footer
4. Click **Save**
Valohai will immediately attempt to fetch your repository. If successful, you'll see your commits in the execution dialog.
## Verify Connection
Test that everything works:
1. Go to **Executions** → **Create Execution**
2. The **Commit** dropdown should show your commits
3. If not, click **Fetch Repository** in settings
## Keep Code Updated
After pushing new commits to Bitbucket, update Valohai:
1. Go to **Settings** → **Repository**
2. Click **Fetch Repository**
**Automate with webhooks** (coming soon).
## Reuse Access Keys Across Repositories
Bitbucket allows access keys to be reused across multiple repositories—useful if you're using [Git submodules](/git-integration/advanced-topics/submodules.md).
**Add the same access key to another repository:**
1. Go to the second repository
2. Navigate to **Settings** → **Access Keys** → **Add key**
3. Paste the same public key
Now the same SSH key works for both repositories.
## Troubleshooting
**"Permission denied (publickey)"**
* The public key wasn't added correctly to Bitbucket
* Make sure you copied the entire `.pub` file contents
* Verify the access key shows in Bitbucket's settings
**"Repository not found"**
* Check the repository URL format (should be `git@bitbucket.org:...`)
* Don't use HTTPS format for private repos with SSH
* Ensure the access key is added to the correct repository
**"Invalid private key format"**
* Make sure you pasted the private key, not the public key
* Include the header (`-----BEGIN RSA PRIVATE KEY-----`) and footer
* Don't add extra spaces or line breaks
**"My commits don't appear"**
* Click **Fetch Repository** after pushing new commits
* Check if you're on the correct branch
* Use [Manage Commits](/git-integration/manage-commits.md) to unhide old commits
**"Access key already exists"**
* Bitbucket prevents duplicate keys
* If you need to use the same key, add it to the other repository
* Or generate a new key pair for this repository
## Security Best Practices
**Use repository access keys, not personal SSH keys**
* Access keys are repository-specific
* They provide read-only access by default
* They don't expose your entire Bitbucket account
**Rotate keys periodically**
* Generate new keys every 6-12 months
* Delete old access keys from Bitbucket
**Don't share private keys**
* Each environment should have its own key pair
* Never commit keys to your repository
* Store keys securely (password manager, secrets vault)
**Monitor key usage**
* Review which access keys are active
* Delete unused keys to minimize security risks
## Next Steps
* [Use .vhignore](/git-integration/use-vhignore.md) to exclude large files
* [Manage Commits](/git-integration/manage-commits.md) to organize visible commits
* [Git Submodules](/git-integration/advanced-topics/submodules.md) for accessing multiple repos
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.valohai.com/git-integration/private-repositories/bitbucket.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.