Use your Docker images in self-hosted runners

When you use a self-hosted runner, you may want to pull the Atlassian public Docker images from your own registry or use modified versions of our public Docker images.

To use Docker images from a custom Docker registry in your self-hosted runner, you can configure them using: PAUSE_IMAGE, AUTH_PROXY_IMAGE, and CLONE_IMAGE.

Example

The default Atlassian Docker images used by the self-hosted runners are:

• PAUSE_IMAGE – docker-hub.packages.atlassian.com/google/pause:latest

• AUTH_PROXY_IMAGE – docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-auth-proxy:prod-stable

• CLONE_IMAGE – docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-dvcs-tools:prod-stable

All of the above default images can be retrieved using docker pull without logging in (they are public images).

If your server is behind a firewall, don’t forget to allowlist the domains you’d like to pull images from.

Use images from a private Docker registry

The Docker-based runner can be configured to pull versions of the public Atlassian docker images from a private docker registry that allows authentication using a username and password.

To use a private Docker image hosted on a Docker registry (such as Docker Hub), create or update the .docker/config.json file with login credentials for the Docker registry. The use of authentication credentials other than basic authentication (a username with a password), such as tokens and timed passwords is not supported. The use of a credential store is also not supported.

A .docker/config.json file can be created either by:

• Using the Docker login command

• Manually creating the Docker config.json file

Using the Docker login command

To create or update the ~/.docker/config.json file with login credentials:

1. On the runner host, run the following command and provide your username and password when prompted:

   docker login <registry_hostname>

   • If the login is successful, you will receive a warning about unencrypted storage of your password and the message Login Succeeded.

   • If you don't receive the warning, the docker instance on the host may be configured to use a credential store, which is not supported.

2. Mount the host .docker/config.json file in the runner container using the volume flag (-v), such as:

   -v <path_to_docker_config_directory>/.docker:/root/.docker

   Where the default location for <path_to_docker_config_directory>/.docker is ~/.docker/.

   For example:

   docker container run \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /var/lib/docker/containers:/var/lib/docker/containers:ro \ -v <path_to_docker_config_directory>/.docker/config.json:/root/.docker/config.json \ -e ACCOUNT_UUID=<my-account-id> \ -e REPOSITORY_UUID=<my-repository-id> \ -e RUNNER_UUID=<my-runner-id> \ -e OAUTH_CLIENT_ID=<my-oauthclient-id> \ -e OAUTH_CLIENT_SECRET=<my-oauthclient-secret> \ -e WORKING_DIRECTORY=/tmp \ -e RUNTIME_PREREQUISITES_ENABLED=true \ -e PAUSE_IMAGE="my-private-registry/my-pause:latest" \ -e AUTH_PROXY_IMAGE="my-private-registry/my-auth-proxy:latest" \ -e CLONE_IMAGE="my-private-registry/my-clone:latest" \ --name my-runner-b0ae87b8-423b-5c24-9a95-84ddad9cdfae \ docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner

Manually creating the Docker config.json file

To manually create or update the ~/.docker/config.json file with login credentials:

1. On the runner host, use a plain text editor to create or open the .docker/config.json file in the user's home directory.

2. Add or append the auths top-level property, such as:

   { "auths": { "my-private-registry-uri": { "auth": "dXNlcjpwYXNzd29yZA==" }, "my-other-private-registry-uri": { "auth": "dXNlcjE6cGFzc3dvcmQx" } } }

   Where my-private-registry-uri and my-other-private-registry-uri are the URLs of two private registries, such as Docker Hub. The auth values are the username and password for registries (colon-separated) after they have been base64 encoded. To base64 encode the username and password on a macOS or Linux command line, run:

   echo -n 'user:password' | base64

    

3. Mount the host .docker/config.json file in the runner container using the volume flag (-v), such as:

   -v <path_to_docker_config_directory>/.docker:/root/.docker

   Where the default location for <path_to_docker_config_directory>/.docker is ~/.docker/.

   For example:

   docker container run \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /var/lib/docker/containers:/var/lib/docker/containers:ro \ -v <path_to_docker_config_directory>/.docker/config.json:/root/.docker/config.json \ -e ACCOUNT_UUID=<my-account-id> \ -e REPOSITORY_UUID=<my-repository-id> \ -e RUNNER_UUID=<my-runner-id> \ -e OAUTH_CLIENT_ID=<my-oauthclient-id> \ -e OAUTH_CLIENT_SECRET=<my-oauthclient-secret> \ -e WORKING_DIRECTORY=/tmp \ -e RUNTIME_PREREQUISITES_ENABLED=true \ -e PAUSE_IMAGE="my-private-registry/my-pause:latest" \ -e AUTH_PROXY_IMAGE="my-private-registry/my-auth-proxy:latest" \ -e CLONE_IMAGE="my-private-registry/my-clone:latest" \ --name my-runner-b0ae87b8-423b-5c24-9a95-84ddad9cdfae \ docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner

Limitations

This feature has the following limitations:

• Authentication using a credential store is not supported. Only login using basic authentication (username and password) is supported.

• The images must be hosted in a registry. The runner will always pull images from a remote host and can't use images on the host device.

• This feature is only available to Docker self-hosted runners. Other runners (such as shell-based runners) don't use containers.