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)



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

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.

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 VCS_ID=$VCS_ID \
--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 \

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:

# 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

Did this answer your question?