Getting Started

by bradrydzewski

Get started by placing a .drone.yml file in the root of your repository. The .drone.yml is a superset of the docker-compose file format. Below is an example configuration file with a single build step that runs tests against a Postgres service container.

pipeline:
  build:
    image: golang
    commands:
      - go get
      - go build
      - go test

services:
  postgres:
    image: postgres:9.4.5
    environment:
      - POSTGRES_USER=myapp

You can break your build into multiple named steps (see below example). Each step executes in a separate Docker container with shared disk access to your project workspace.

pipeline:
  backend:
    image: golang
    commands:
      - go get
      - go build
      - go test

  frontend:
    image: node:6
    commands:
      - npm install
      - npm test

  notify:
    image: plugins/slack
    channel: developers
    username: drone

Note that the above step names are completely arbitrary. You can call them whatever you like.

Images

Drone executes your build inside an ephemeral Docker image. This means you don’t have to setup or install any repository dependencies on your host machine. Use any valid Docker image in any Docker registry as your build environment.

pipeline:
  build:
    image: golang:1.6

Cloning

Drone automatically clones your repository into a local volume that is mounted into each Docker container. This volume is generally referred to as the workspace. The workspace is available to all steps in your build process, including plugins and service containers.

git clone --depth=50 --recusive=true \
    https://github.com/octocat/hello-world.git \
    /drone/src/github.com/octocat/hello-world

git checkout 7fd1a60

Commands

Drone previously cloned your source code into the workspace. Drone mounts the workspace into your build containers (golang) and executes bash commands inside your build container, using the root of your repository as the working directory.

pipeline:
  build:
    image: golang
    commands:
      - go get
      - go build
      - go test

There is no magic here. Drone converts the above Yaml into a simple shell script that gets executed as the entrypoint to your build container. The above Yaml file is roughly translated into the below shell script:

#!/bin/sh
set -e

go get
go build
go test

Services

Drone supports launching service containers as part of the build process. This can be very helpful when your unit tests require database access, for example. Service containers share the same network (ie localhost) as your build containers.

Example Yaml configuration using a Postgres database:

pipeline:
  build:
    image: golang
    commands:
      - go get
      - go build
      - go test

services:
  database:
    image: postgres
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=mysecretpassword

Plugins

Drone supports publish, deployment and notification capabilities through external plugins. Plugins are Docker containers that are automatically downloaded, attach to your build, and perform a specific task.

Example Yaml configuration published a Docker image:

pipeline:
  build:
    image: golang
    commands:
      - go get
      - go build
      - go test

  publish:
    image: plugins/docker
    repo: octocat/hello-world
    tags: [ latest, 1, 1.0, 1.0.0 ]

Example Yaml configuration triggers a Slack notification:

pipeline:
  …

  notify:
    image: plugins/slack
    channel: developers
    username: drone

Constraints

Drone gives you the ability to conditionally limit the execution of build steps at runtime. The below example limits execution of Heroku plugin steps based on branch:

pipeline:
  …

  prod:
    image: plugins/heroku
    app: foo.com
    when:
      branch: master

  stage:
    image: plugins/heroku
    app: dev.foo.com
    when:
      branch:
        exclude: master

Failures

Drone uses the container exit code to determine the success or failure status of a build. Non-zero exit codes fail the build and cause the pipeline to immediately exit.

There are use cases for executing pipeline steps on failure, such as sending notifications for failed builds. Use the status constraint to override the default behavior and execute steps even when the build status is failure:

pipeline:
  build:
    …

  notify:
    image: plugins/slack
    when:
      status: [ success, failure ]