Version 0.9.0
Language EN

Secrets

The top-level secrets declaration defines or references secrets that can be granted to steps in your pipeline. The source of the secret is either an encrypted string, stored directly in the yaml, or a pointer to an external secret.

Example configuration using encrypted secrets:

kind: pipeline
name: default

steps:
- name: build
  image: alpine
  environment:
    USERNAME:
      $secret: username
    PASSWORD:
      $secret: password

---
kind: secret
type: encrypted

data:
  username: hl3v+FODjduX0UpXBHgYzPzVTppQblg51CVgCbgDk4U=
  password: d37QyWi+E5FknFQN3ysygWmKx86L03Vk/rQV5g4pRiQ=

You can pass secrets to your pipeline steps as environment variables using the following syntax:

kind: pipeline
name: default

steps:
- name: build
  image: alpine
  environment:
    USERNAME:
      $secret: username
    PASSWORD:
      $secret: password

Encrypted Secrets

Secrets are encrypted using the command line utility and stored directly in your yaml configuraiton file. The drone server encrypts the secret with a per-repository key using secretbox or aesgcm encryption.

drone encrypt secret <repository> <secret>

Example command encrypts the secret:

$ drone encrypt secret octocat/hello-world correct-horse-battery-staple
hl3v+FODjduX0UpXBHgYzPzVTppQblg51CVgCbgDk4U=

Example configuraiton with the secret inline:

kind: pipeline
name: default

steps:
- name: build
  image: alpine
  environment:
    USERNAME:
      $secret: username
    PASSWORD:
      $secret: password

---
kind: secret
type: encrypted

data:
  username: hl3v+FODjduX0UpXBHgYzPzVTppQblg51CVgCbgDk4U=
  password: d37QyWi+E5FknFQN3ysygWmKx86L03Vk/rQV5g4pRiQ=

For security reasons, encrypted secrets are never exposed to pull requests by default. You can override this default behavior with the following flags:

drone encrypt secret <repository> <secret> --allow-pull-request

External Secrets

External secrets are stored in a third party system, such as Vault or the AWS Secrets Manager, and are requested at runtime. In order to use external secrets your Drone system administrator must install a storage driver for your secret manager.

Example external secret declaration:

kind: pipeline
name: default

steps:
- name: build
  image: alpine
  environment:
    USERNAME:
      $secret: username
    PASSWORD:
      $secret: password

---
kind: secret
type: encrypted

data:
  username: secrets/data/username
  password: secrets/data/password

Security

Encrypted secrets are not exposed to pull requests by default. This prevents a bad actor from sending a pull request and attempting to expose your secrets. You can override this default behavior, at your own risk, with the following flags:

drone encrypt <repository> <secret> --allow-pull-request

External secrets provide their own mechanism to limit when and how secrets are granted to pipeline steps. Please see the respective driver documentation for your secret provider to learn more about limiting access.

Pull Secrets

Pull secrets are a special category of secret that can be used to authenticate and pull private Docker images defined in your pipeline.

Example pipeline steps using a private image:

kind: pipeline
name: default

steps:
- name: build
  image: testing/test-image
  commands:
  - go build
  - go test

Docker Config File

In order to download this private image, you will need to provide a docker registry config file, which embeds the authentication credentials to the registry.

Example .docker/config.json file:

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "b2N0b2NhdDpjb3JyZWN0LWhvcnNlLWJhdHRlcnktc3RhcGxl"
    }
  }
}

The registry config file is declared in the secrets block, either as an encrypted or external secret, and must be named docker_auth_config. This is a reserved name in the system, and signifies the secret should be used to authorize image downloads.

kind: pipeline
name: default

steps:
- name: build
  image: testing/test-image
  commands:
  - go build
  - go test

---
kind: secret
type: encrypted

data:
  docker_auth_config: hl3v+FODjduX0UpXBHgYzPzVTppQblg51CVgCbgDk4U=

Security

Registry secrets are never exposed to your pipeline containers and are generally safe to use with pull requests. The caveat is that any private images you pull are stored in the local Docker cache. A pipeline can use any image in the local Docker cache, which means your private image may be accessible to unauthorized projects.

On This Page:

Getting Help

Enterprise Support
Real-time chat support from the developers that wrote the code.
Mailing List
Search for information in the mailing list archives, or post a question.