How do I connect to my on-premise Bitbucket Server?

If your server is not accessible from the public internet, and instead requires on-premise installation, please use the following instructions.

(NOTE: we do not import personal repositories for BitBucket Server)

Requirements

Requirements for on-premise servers

Setup

1. Generate a Personal Access Token

Bitbucket server does not support OAuth2, so a personal access token is used for authorization.

From your Bitbucket instance, go to your account settings.
Manage Account -> Personal Access Tokens -> Create a Token
Give your token a name and admin permissions to projects and repositories.

---

Why are admin permissions required?

Velocity will automatically install a webhook for each repository to ensure its data stays up-to-date, and allow support for concepts that Bitbucket Server does not provide natively, such as pushes. Webhook installations require admin permissions.

---

After creation, copy your token for future use.

2. Create a Velocity Version Control System using the Personal Access Token

Navigate to https://velocity.codeclimate.com/settings/vcs/new
Settings -> Version Control Systems -> Add version control system

Fill in the following attributes:

Type (choose Bitbucket Server)
Hostname (ex: bitbucketserver.internal.example.net)

Then click Create version control system

You should see your new VCS.

3. Create an Agent for the VCS

Option 1: without persistent data

Next we want to setup the Agent which will be communicating with your configured VCS.

Navigate to the Agents settings section: https://velocity.codeclimate.com/settings/agents/new
Click "Create agent"

You should now see setup instructions for the agent.

Option 2: with persistent data

(uses Personal Access Tokens for authentication, so use the flags below)

docker pull codeclimate/velocity-agent:latest-v2 && 
  docker volume create velocity_agent_data && 
  docker run 
    --name velocity-agent 
    --env AGENT_ID=$AGENT_ID 
    --env AGENT_TOKEN=$AGENT_TOKEN 
    --env VCS_ID=$VCS_ID 
    --env VCS_PERSONAL_ACCESS_TOKEN_USERNAME=$PERSONAL_ACCESS_TOKEN_USERNAME 
    --env VCS_PERSONAL_ACCESS_TOKEN=$PERSONAL_ACCESS_TOKEN 
    --detach 
    --restart=always 
    --volume velocity_agent_data:/data 
    --log-driver json-file 
    --log-opt max-size=10m 
    --log-opt max-file=10 
    --publish 5050:5050 
    --publish 4040:80 
    codeclimate/velocity-agent:latest-v2

4. Run the Agent

On your provisioned server where the agent will operate:

Run the provided setup commands.
The agent will start and run in the background.
Verify that the agent is up and running:

bash
# verify that the container is running
$ docker ps# follow the agent logs
$ docker ps | grep velocity-agent | cut -d " " -f1 | head -n 1 | xargs docker logs --follow --tail=20

5. Setup your VCS in the Agent

Copy the docker command under Bitbucket Server.
Replace the VELOCITY_VCS_ID with the ID listed for your VCS in the Available VCS table at the bottom of the Agents settings page.
Replace the BBS_PERSONAL_ACCESS_TOKEN and BBS_PERSONAL_ACCESS_TOKEN_USERNAME with the values you were provided from Bitbucket.
- NOTE: The BBS_PERSONAL_ACCESS_TOKEN_USERNAME is the Bitbucket Server username of the account where you created the private key. It is not the name of the private key.
RUN the command in the agent and you should see the response "Vcs created."

6. Add repositories

Navigate to Settings > Repositories
Choose repositories to import