Command Line Runner

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.

Installation

  • 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
    

Usage

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.

  1. Navigate to the root directory of your git repository where your .drone.yml file 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
    
  2. Execute your pipeline from the command line:

    $ drone exec
    
  3. 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
    

Workspace

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 --pipeline flag.

  • 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,test
    
  • Execute all pipeline steps except deploy

    drone exec --exclude=deploy
    

Emulate Secrets

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.

  1. 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
    
  2. 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 secrets.txt.

    USERNAME=root
    PASSWORD=password
    
  3. 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.

Emulate Metadata

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
    

Trusted Mode

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.