Feature Preview: Debug Mode

I am excited to introduce a new feature that is available for preview called debug mode. When you execute a pipeline in debug mode, and a pipeline step fails, a remote tunnel is created that allows you to remotely ssh into the pipeline step’s container for debugging purposes (learn more below).

This feature requires the latest version of the drone server (drone/drone:latest) and the latest version of the docker runner (drone/drone-runner-docker:1). You must then pass DRONE_TMATE_ENABLED=true to the docker runner. This feature is not yet available to the kubernetes runner.

If you are upgrading the runner on an existing machine, we recommend you manually force pull drone/drone-runner-docker:1 to ensure you do not have a stale release in your local docker cache.


When a pipeline fails you can restart the pipeline in debug mode by clicking the debug button. This option is available to users with write or admin access to the repository only.

When the pipeline runs in debug mode, and a pipeline step fails, a tmate session is created that allows you to remotely ssh into the container to debug. This is only available to steps with commands; this cannot be used with plugin steps.

Copy the tmate session link to start your remote session and gain remote access to the pipeline step. Once you complete the debugging process you need to cancel the build, otherwise it will remain in a paused state until the pipeline timeout is reached.

This feature is experimental and is opt-in. We expect to eventually enable this feature by default once we have support for self-hosted tmate instances (done) and once we have support for tmate on kubernetes. We will make a formal announcement before enabling this feature by default.

Please join our gitter channel to discuss this feature and provide feedback.

We pushed an update today to drone/drone-runner-docker:latest that allows enabling and configuring a self-hosted tmate server. This is ideal for teams that want to leverage the live debug feature, but for security or data privacy reasons, do not want to use the tmate.io service.

Here is an example configuration to pass to the runner:

DRONE_TMATE_ENABLED=true
DRONE_TMATE_HOST=tmate.company.com
DRONE_TMATE_PORT=2200
DRONE_TMATE_FINGERPRINT_RSA=SHA256:iL3StSCmPU+7p2IoD8y0huMXRVFIZyGFZa8r+lO3U5I
DRONE_TMATE_FINGERPRINT_ED25519=SHA256:gXLaN8IUxUMmlm/xu7M2NEFMlbUr5UORUgMi86Kh+tI

You can follow the instructions for installing tmate at tmate.io/#host.