Bitbucket Server

Updated 2 years ago by Admin

This article explains how to install the Drone server for Bitbucket Server, formerly known as Atlassian Stash. The server is packaged as a minimal Docker image distributed on DockerHub.

Step 1 : Preparation

Create a Personal Access Token

Create a personal access token that is capable of cloning all repositories in the system. The token and associated username are used for all clone operations. We recommend creating a machine account for this purpose.

Navigate to the Personal Access Tokens page in the account settings, and click the Create Token button.

Token List

Create the personal access token. The creation form should indicate pull and clone access as pictured below. Click the Create button and copy the generated token.

Token Create

Create a Key Pair

Create a key pair on your server. The key pair is used to setup an authentication provide with Bitbucket and authorize API access.

Generate the private key:

$ openssl genrsa -out /etc/bitbucket/key.pem 1024
Generating RSA private key, 1024 bit long modulus
e is 65537 (0x10001)

Generate a public key:

$ openssl rsa \
-in /etc/bitbucket/key.pem \
-pubout >> /etc/bitbucket/

Create a Bitbucket Application Link. The link will provide a Consumer ID and Private Key used to authorize access to Bitbucket resources. The Bitbucket application creation process is convoluted and error prone. Please bear with us.

Navigate the administrator panel and click the Application Links settings page. Enter your Drone server URL and click Create New Link.


Please fill out the form using the values specified below. Once complete click Continue to create your application.

  • Set the application name to Drone
  • Set the application type to Generic Application
  • Set the provider name to Drone
  • Set the consumer key to OauthKey
  • Set the shared secret to any random alphanumeric value
  • Set the request token url to your Drone server URL
  • Set the access token url to your Drone server URL
  • Set the authorize token url to your Drone server URL


Once the application is created it needs to be edited so that we can configure the Incoming Authentication. Please fill out the form using the values specified below and save your changes.

  • Set the consumer key to OauthKey
  • Set the consumer name to Drone
  • Paste the contents of /etc/bitbucket/ in the public key textarea
  • Leave Consumer Callback empty
  • Leave Allow 2-Legged Oauth unchecked


Congratulations, you have made it through the most painful part of the installation. With luck, everything will work as expected and you will never have to do this again.

Create a Shared Secret

Create a shared secret to authenticate communication between runners and your central Drone server.

You can use openssl to generate a shared secret:

$ openssl rand -hex 16

Step 2 : Download

The Drone server is distributed as a lightweight Docker image. The image is self-contained and does not have any external dependencies.

$ docker pull drone/drone:1

Step 3 : Configuration

The Drone server is configured using environment variables. This article references a subset of configuration options, defined below. See Configuration for a complete list of configuration options.

    Required string value set to username associated with the Personal Account token. This username is used to authenticate and clone all private repositories.
    Required string value set to your Personal Account Token. The token is used to authenticate and clone all private repositories.
    Optional boolean value configures Drone to authenticate when cloning public repositories. This should only be enabled when using GitHub Enterprise with private mode enable.
    Required string value configures your Bitbucket Server consumer key.
    Required string value configures the path to your Bitbucket Server private key file. Note that this file needs to also be mounted into the Drone server container as a volume.
    Required string value provides the Bitbucket Server address. For example
    Required string value provides the shared secret generated in the previous step. This is used to authenticate the rpc connection between the server and runners. The server and runner must be provided the same secret value.
    Required string value provides your external hostname or IP address. If using an IP address you may include the port.
    Required string value provides your external protocol scheme. This value should be set to http or https. This field defaults to https if you configure ssl or acme.

Step 4 : Start the Server

The server container can be started with the below command. The container is configured through environment variables. Remember to replace the placeholder values below with the appropriate values.

1 docker run \
2 --volume=/var/lib/drone:/data \
3 --volume=/etc/bitbucket/key.pem:/etc/bitbucket/key.pem \
6 --env=DRONE_GIT_ALWAYS_AUTH=false \
9 --env=DRONE_STASH_PRIVATE_KEY=/etc/bitbucket/key.pem \
13 --publish=80:80 \
14 --publish=443:443 \
15 --restart=always \
16 --detach=true \
17 --name=drone \
18 drone/drone:1

Step 5 : Install Runners

Once your server is up and running you will need to install runners to execute your build pipelines. See our runner installation documentation for detailed installation instructions.

How did we do?