Pipeline steps are defined as a series of Docker containers. Each step must therefore define the Docker image used to create the container.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

kind: pipeline
type: docker
name: default

steps:
- name: build
  image: golang:1.12
  commands:
  - go build
  - go test

Drone supports any valid Docker image from any Docker registry:

image: golang
image: golang:1.7
image: library/golang:1.7
image: index.docker.io/library/golang
image: index.docker.io/library/golang:1.7
image: docker.company.com/golang

Pulling Images

If the image does not exist in the local cache, Drone instructs Docker to pull the image automatically. You will never need to manually pull images.

If the image is tagged with :latest either explicitly or implicitly, Drone attempts to pull the newest version of the image from the remote registry, even if the image exists in the local cache.

To only pull the image if not found in the local cache:

15
16
17
18

steps:
- name: build
  pull: if-not-exists
  image: golang

To always pull the newest version of the image:

15
16
17
18

steps:
- name: build
  pull: always
  image: golang:1.12

To never pull the image and always use the image in the local cache:

15
16
17
18

steps:
- name: build
  pull: never
  image: golang:1.12

Pulling Private Images

If the image is private you need to provide Drone with docker credentials, sourced from a secret. You can manage secrets in your repository settings screen in the web interface.

First create a secret that includes your Docker credentials in the format of a Docker config.json file. This file may provide credentials for multiple registries.

1
2
3
4
5
6
7

{
    "auths": {
        "docker.io": {
            "auth": "4452D71687B6BC2C9389C3..."
        }
    }
}

Next, define which secrets should be used to pull private images using the image_pull_secrets attribute:

 5
 6
 7
 8
 9
10
11
12
13

steps:
- name: build
  image: registry.internal.company.com/golang:1.12
  commands:
  - go build
  - go test

image_pull_secrets:
- dockerconfig

Google Container Registry Issues

If the config.json has entries for both gcr.io and https://gcr.io you should prune the file and remove the entry with the https:// prefix otherwise you will intermittently receive the following error message:

default: Error response from daemon: unauthorized: You don’t have the needed permissions to perform this operation, and you may have invalid credentials. To authenticate your request, follow the steps in: https://cloud.google.com/container-registry/docs/advanced-authentication

Image Caching Behavior

The Docker daemon caches all images that is pulls, including private images. Docker does not restrict the use of cached images. An image already in the local cache can be used by any pipeline.

It is therefore possible for a pipeline to pull a private image that is cached by Docker, and for another pipeline to use this image from the cache without having credentials. Keep this in mind when pulling private images in a shared or public environment.