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

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

You should now see setup instructions for the agent.

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?