Bitbucket

Connect a private Bitbucket repository to Valohai using SSH access keys

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:

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.

💡 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: [email protected]:username/repository.git)

In Valohai:

1. Go to Settings → Repository

2. Paste the SSH URL into the URL field:

   [email protected]: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.

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 [email protected]:...)

• 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 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 to exclude large files

• Manage Commits to organize visible commits

• Git Submodules for accessing multiple repos