You can use the command line tools to run Docker pipelines locally, on your laptop or personal computer, for development and debugging purposes. This is our answer to the common complaint that it works fine on my computer.
Install the command line tools on OSX using Homebrew:
$ brew install drone-cli
Install the command line tools on Windows using Scoop:
$ scoop install drone
The command line runner requires a working Docker installation. Drone executes your pipeline locally on your host machine using your local Docker daemon. Local execution does not have any communication with the Drone server.
Navigate to the root directory of your git repository where your
.drone.ymlfile is located. Here is a basic configuration you can use for testing purposes:
kind: pipeline type: docker name: default steps: - name: test image: alpine commands: - echo hello - echo world
Execute your pipeline from the command line:
$ drone exec
The command streams the pipeline logs to your terminal for analysis. The command returns a non-zero exit code if the pipeline fails.
$ drone exec [test:1] + echo hello [test:2] hello [test:3] + echo world [test:4] world
The command line runner mounts your current working directory, using docker volumes, as the working directory of your pipeline steps. The exposes your code to your pipeline. The clone step is therefore skipped when running locally.
Run Specific Pipelines
The command line runner runs the default pipeline. If you use a different name for you pipeline, or you define multiple pipelines in your yaml, you can execute a named pipeline using the
Example configuration with a pipeline named test
kind: pipeline type: docker name: test steps: - name: dist image: node commands: - npm install - npm run dist
Example command executes the test pipeline
drone exec --pipeline=test
Run Specific Steps
When running pipelines locally you can limit which pipeline steps are executed and which pipeline steps are skipped.
Execute only pipeline steps build and test
drone exec --include=build --include=test
Execute all pipeline steps except deploy
drone exec --exclude=deploy
The command line runner does not have read access to secrets stored in your server. You can provide secrets to your local pipeline by passing secrets to the command line runner via text file.
Example pipeline that requires username and password environment variables, sourced from secrets.
kind: pipeline type: docker name: default steps: - name: test environment: USERNAME: from_secret: USERNAME PASSWORD: from_secret: PASSWORD
Create a simple text file with secrets defined one per line in key value format. For the purposes of this demo we name the file
Provide your secrets file via command line flags when executing your pipeline.
$ drone exec --secret-file=secrets.txt
The command line runner uses the dotenv package to read and parse the secrets file. If you are having problems with the secrets file please consult the official package documentation.
The command line runner does not communicate with the Drone server and therefore do not have access to repository, commit and build metadata that are otherwise available to your pipeline.
You can emulate repository metadata by passing repository and build information to the command line runner using command line flags and environment variables.
Example command sets the branch:
$ drone exec --branch=master
Example command sets the build event:
$ drone exec --event=pull_request
Example command set metadata using environment variables:
$ DRONE_SYSTEM_HOST=drone.company.com drone exec
If your pipeline uses configurations that require trusted mode, you can enable trusted mode locally using the
--trusted flag. Trusted mode grants a pipeline elevated privileges to your host machine. Please use with caution.
Example command enables trusted mode:
$ drone exec --trusted
Local vs Remote
The command line runner makes reasonable effort to emulate the server environment, however, there are notable differences that can impact execution:
The server clones your repository, while the command line runner mounts your current working directory. Any files or dependencies that already exist in your working directory are mounted into your pipeline as well.
The server has access to more data (commit details, repository details, etc). This data needs to be provided to the command line runner to more closely emulate the server environment.
The server has access to your oauth credentials and uses these credentials to generate a netrc file. These credentials need to be provided to the command line runner to more closely emulate the server environment.
The server has access to repository, organization and encrypted secrets. The command line runner does not have access to secrets or decryption keys stored in the server environment.