## 1. Project Overview & Quickstart (appleboy/README.zh-cn)

# README.zh-cn

Open-source repository appleboy/README.zh-cn

### Repository Details
- **Repository:** [appleboy/README.zh-cn](https://github.com/appleboy/README.zh-cn)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (appleboy/docs)

## File: README.md

[](https://gitter.im/drone/drone?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

Documentation for the [Drone](https://github.com/drone/drone) continuous integration server, found at [readme.drone.io](http://readme.drone.io)

## Setup

This website uses the [Hugo](https://github.com/spf13/hugo) static site generator. If you are planning to contribute you'll want to download and install Hugo on your local machine.

Install on OSX with brew:

```
brew install hugo
```

Install using the Go tool:

```
go get github.com/spf13/hugo
```

Or follow these instructions for your platform: http://gohugo.io/overview/installing/

## Build

Generate the website and output to `./public`

```
hugo
```

Generate the website, serve on localhost:1313/installation/overview, and automatically refresh the browser when a change is detected:

```
hugo server -b localhost
```


## Generate

Generate plugin documentation:

```
go run contrib/plugin-gen.go --repo drone-s3
```

Generate the swagger documentation:


```
go run contrib/swagger-gen.go --input $GOPATH/src/github.com/drone/drone/docs/swagger.yml
```

---

## File: content/usage/artifacts.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Publishing Artifacts"
weight = 11
menu = "usage"
toc = true
+++


# Overview

Publishing files or build artifacts is triggered at the end of a successful build. Note that publish steps are not executed for pull requests or failed builds.

Example to publish a Node package to the [npmjs.com](/plugins/npm/) registry using the NPM plugin:

```yaml
---
publish:
  npm:
    username: octocat
    password: password
    email: octocat@github.com
```

# Plugins

Drone does not have any builtin publishing or artifact capabilities. Drone instead offers a large library of plugins for publish to [DockerHub](/plugins/docker/), [S3](/plugins/s3/), [Google Storage](/plugins/google_cloudstorage/) and more. Please see the [plugin documentation](/plugins/) for a complete list.

# Docker

Building and publishing a Docker image to the registry is handled by plugins. We have multiple plugins for building and publishing Docker images to [DockerHub](/plugins/docker/), [Google Container Registry](/plugins/gcr/), and more.

# Conditions

Use the `when` block to limit publish step execution:

```yaml
---
publish:
  heroku:
    app: mycompany.com
    when:
      branch: master
```

Execute a publish step if the branch is `master` or `release`:

```yaml
---
publish:
  rubygems:
    api_key: e123f83113f79eb17308bbf1ca8885bb
    when:
      branch: [master, release]
```

Execute a publish step if the branch is _not_ `master`:

```yaml
---
publish:
  rubygems:
    api_key: e123f83113f79eb17308bbf1ca8885bb
    when:
      branch: "!master"
```

Execute a publish step when the commit is a `tag`:

```yaml
---
publish:
  rubygems:
    api_key: e123f83113f79eb17308bbf1ca8885bb
    when:
      event: tag
```

Execute a publish step for a single matrix permutation:

```yaml
---
publish:
  rubygems:
    api_key: e123f83113f79eb17308bbf1ca8885bb
    when:
      matrix:
        RUBY_VERSION: 2.3
        REDIS_VERSION: 2.8
```

---

## File: content/usage/build_test.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Build & Test"
weight = 7
menu = "usage"
toc = true
+++

# Overview

Drone uses the `build` section of the `.drone.yml` to define your Docker build environment and your build and test instructions. The following is an example build definition:

```yaml
---
build:
  image: golang
  commands:
    - go get
    - go build
    - go test
```

This example downloads and runs a `golang` container and executes the specified commands inside the container. Your source code, previously fetched during the `clone` step, is provided to the container as a Docker volume.

# Images

Drone supports any valid Docker image from any Docker registry:

```yaml
---
image: golang
image: golang:1.5
image: library/golang:1.5
image: index.docker.io/library/golang:1.5
```

Provide your registry credentials if your build image is private:

```yaml
---
build:
  image: foo/bar
  auth_config:
    username: octocat
    password: password
    email: octocat@github.com
```

Use the `pull` attribute to instruct Drone to always pull the latest Docker image. This helps ensure you are always testing your code against the latest image:

```yaml
---
build:
  image: golang
  pull: true
```

# Workspace

The build workspace is located in the `/drone/src/<repository>` directory inside the `/drone` volume. You cannot change the volume location, however, you can change the subdirectory.

The below example overrides the default workspace to `/drone/src/github.com/octocat/hello-world`:

```yaml
---
clone:
  path: github.com/octocat/hello-world
```

# Environment

Use the environment section to inject environment variables into your build environment:

```yaml
---
build:
  image: golang:1.5
  environment:
    - GO15VENDOREXPERIMENT=0
    - GOOS=linux
    - GOARCH=amd64
    - CGO_ENABLED=0
```

Variable expansion is not supported. The following example __will not work__:

```yaml
---
environment:
  - PATH=$PATH:/go
```

# Commands

Build commands execute sequentially in a shell environment with the `-e` flag. The `-e` flag instructs the shell environment to exit immediately if a command returns a non-zero exit code.

```yaml
---
build:
  image: golang:1.5
  commands:
    - go get
    - go build
    - go test
```

Please be aware that chaining commands together with `&&` may result in the build not exiting on failure. This is not a bug with Drone. This is the default bash `-e` behavior. See [this stackoverflow](http://stackoverflow.com/questions/25794905/why-does-set-e-true-false-true-not-exit#25795239) for more details.

# Multiple Steps

Build commands can be split into multiple named steps. The below example let's us split our frontend build (node) and our backend build (go). Each step executes in its own isolated container environment while sharing the same build workspace.

```yaml
---
build:
  frontend:
    image: node:5.3.0
    commands:
      - npm install
      - npm test
  backend:
    image: golang:1.5
    commands:
      - go get
      - go build
      - go test
```

# Conditions

Limit when a build step should is executed using conditional logic. The below example splits our build into two steps. The second build step, building the distribution, is only executed when we tag a release. This reduces the build time for `push` and `pull_request` events by removing un-necessary steps:

```yaml
---
build:
  test:
    image: golang:1.5
    commands:
      - go get
      - go test
  bundle:
    image: golang:1.5
    commands:
      - go build
      - tar -cvf bundle.tar myapp
    when:
      event: tag
```

Only execute a step when building a `push` or `tag` event:

```yaml
---
build:
  bundle:
    when:
      event: [push, tag]
```

Only executes a step when building the `master` branch:

```yaml
---
build:
  bundle:
    when:
      branch: master
```

There are a number of other conditions which can be used in whens: `repo` (a full repo path) and `success`, `failure` and `change` (all booleans based on the previous job status).

```yaml
---
build:
  bundle:
    when:
      repo: drone/drone
      success: true
      failure: true
      change: true
```

# Dependencies

Cloning private submodules or private dependencies (using `npm` or `go get`) requires remote authentication. We recommend using `git+https` for submodules or dependencies, allowing Drone to authenticate to your remote repository using a `.netrc` file injected by default into your build environment.

Instead of using the `git+ssh` url in your `package.json` file:

```js
{
    "library": "git+ssh://git@github.com:octocat/library.git"
}
```

Use the `git+https` url in your `package.json` file:

```js
{
    "library": "https://github.com/octocat/library.git"
}
```

# Volumes

Use the `volumes` attribute to mount folders on your host machine into your build container. These are [Docker volumes](https://docs.docker.com/engine/userguide/dockervolumes/) and therefore use the same `<host>:<container>` declaration conventions:

```yaml
---
build:
  image: golang
  volumes:
    - /some/path/on/host:/path/in/container
```

For security reasons this option is only available to trusted repositories. Trusted repositories are enabled on a per-repository basis by a Drone administrator from your repository settings screen.

# Devices

Use the `devices` attribute to map devices from your host machine into your build container. These are [Docker devices](https://docs.docker.com/compose/compose-file/#devices) and therefore use the same declaration conventions:

```yaml
---
build:
  image: golang
  devices:
    - "/dev/ttyUSB0:/dev/ttyUSB0"
```

For security reasons this option is only available to trusted repositories. Trusted repositories are enabled on a per-repository basis by a Drone administrator from your repository settings screen.

# Privileged

Use the `privileged` attribute to run your build in a privileged Docker container:

```yaml
---
build:
  image: golang
  privileged: true
```

For security reasons this option is only available to trusted repositories. Trusted repositories are enabled on a per-repository basis by a Drone administrator from your repository settings screen.

# Timeouts

There is a default 60 minute timeout for your build. This can be increased by a Drone administrator from your repository settings screen.

# Triggers

Builds are triggered primarily by `push` and `pull_request` hooks from your remote system (ie GitHub). Sometimes changes to an upstream project have a cascading impact on downstream projects. You can trigger cascading builds using the [trigger](/plugins/downstream/) plugin.

# Scheduling

Drone does not have any builtin scheduling capabilities. For scheduled builds (ie nightly builds) we recommend using the Drone command line tools with cron to trigger builds at scheduled intervals.

# Skip Commits

Instruct Drone to skip builds by by including any combination of `ci` and `skip` wrapped in square brackets in your commit message. Examples: `[skip CI]` `[ci skip]`

# Skip Branches

Instruct Drone to skip branches by including a branch white-list in your `.drone.yml`

```yaml
---
branches:
  - master
  - develop
```

---

## File: content/usage/caching.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Caching"
weight = 5
menu = "usage"
toc = true
+++

# Overview

Drone allows you to cache directories within the build workspace (inside the `/drone` volume). When a build successfully completes, the named directories are gzipped and stored on the host machine. When a new build starts, the named directories are restored from the gzipped files. This can be used to improve the performance of your builds.

Example configuration to cache the `.git` and the `node_modules` directory:

```yaml
---
cache:
  mount:
    - node_modules
    - .git
```

# Branches and Matrix

Drone keeps a separate cache for each Branch and Matrix combination. Let’s say, for example, you are using matrix builds to test node `0.11.x` and node `0.12.x` and you are caching `node_modules`. Drone will separately cache `node_modules` for each version of node.

# Pull Requests

Pull requests have read-only access to the cache. This means pull requests are not permitted to re-build the cache. This is done for security and stability purposes, to prevent a pull request from corrupting your cache.


# Deleting the Cache

There is currently no mechanism to automatically delete or flush the cache. This must be done manually, on each worker node. The cache is located in `/var/lib/drone/cache/`.

# Distributed Cache

This is outside the scope of Drone. You may, for example, use a distributed filesystem such as `ceph` or `gluster` mounted to `/var/lib/drone/cache/` to share the cache across nodes.

# Common Issues

The most common issue occurs when you try to cache files or folders that are not children of the `/drone` volume. The below example **will not work**:

```yaml
---
cache:
  mount:
    - /root/node_modules
    - /usr/lib/python3.2/site-packages
```

You should instead only cache directories in `/drone`:


```yaml
---
cache:
  mount:
    - /drone/node_modules
    - /drone/site-packages
```

To work around this limitation we can cache files or folders in `/drone` and copy they to the expected location at the start of the build, and then copy them back to `/drone` at the end fo the build:

```yaml
---
build:
  image: node
  commands:
    - cp -a /drone/node_modules /root
    - rm -rf /drone/node_modules
    - npm -g install
    - npm run build
    - npm run tests
    - cp -a /root/node_modules /drone
```

---

## File: content/usage/cloning.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Cloning"
weight = 4
menu = "usage"
toc = true
+++

# Overview

Drone will automatically clone your repository during the build lifecycle. You can customize this behavior in the **clone** section of the yaml file. This section is entirely optional.

This is an example yaml configuration:

```yaml
---
clone:
  depth: 50
  recursive: true
  path: github.com/drone/drone
```

Which results in the following command:

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

# Authentication

Drone uses `git+https` combined with a `.netrc` file to authenticate and clone private repositories. This allows Drone to clone private Git submodules that also use `git+https`.

# Customization

Limit the amount of git history that is fetched from the remote repository:

```yaml
---
clone:
  depth: 50
```

Fetch all tags from the remote repository:

```yaml
---
clone:
  tags: true
```

Disable tls verification when cloning the remote repository:

```yaml
---
clone:
  skip_verify: true
```

Recursively clone all submodules:

```yaml
---
clone:
  recursive: true
```

Recursively clone and update all submodules:

```yaml
---
clone:
  recursive: true
  submodule_update_remote: true
```

# Private Submodules

Private submodules may encounter the following error:

```
Warning: Permanently added 'github.com,192.30.252.130' (RSA) to the list of known hosts.
ERROR: Repository not found.
fatal: Could not read from remote repository.
```

This happens when a private submodule uses a git+ssh url:

```git
[submodule "hello-world"]
    path = hello-world
    url = git@github.com:octocat/hello-world.git
```

This can be mitigated by overriding the submodule url to use git+https:

```yaml
---
clone:
  recursive: true
  submodule_override:
    hello-world: https://github.com/octocat/hello-world.git
```

Overriding the submodule url to force `git+https` allows us to take advantage of the `netrc` file and automatically authenticate to the submodule repository.

---

## File: content/usage/deploy.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Deployments"
weight = 8
menu = "usage"
toc = true
+++

# Overview

Deployments are triggered at the end of a successful build. Note that deployment steps are not executed for pull requests or failed builds.

Example Heroku deployment using the Heroku plugin:

```yaml
---
deploy:
  heroku:
    app: petstore
```

# Plugins

Drone does not have any builtin deployment capabilities. Drone instead offers a large library of plugins for deploying to [Heroku](/plugins/heroku/), [Tutum](/plugins/tutum/), [Amazon](/plugins/aws_codedeploy/) and more. Please see the [plugin documentation](/plugins/) for a complete list.

# Docker

Building and deploying a Docker image to the registry is handled by plugins. We have multiple plugins for building and publishing Docker images to [DockerHub](/plugins/docker/), [Google Container Registry](/plugins/gcr/), and more.

# Conditions

Use the `when` block to limit deployment step execution:

```yaml
---
deploy:
  heroku:
    app: mycompany.com
    when:
      branch: master
```

Execute a deployment step if the branch is `master` or `develop`:

```yaml
---
deploy:
  heroku:
    app: mycompany.com
    when:
      branch: [master, develop]
```

Execute a deployment step if the branch is _not_ `master`:

```yaml
---
deploy:
  heroku:
    app: mycompany.com
    when:
      branch: "!master"
```

Execute a deployment step if the branch is starts with `prefix/*`:

```yaml
---
deploy:
  heroku:
    app: mycompany.com
    when:
      branch: prefix/*
```

Execute a deployment step when the commit is a `tag`:

```yaml
---
deploy:
  heroku:
    app: mycompany.com
    when:
      event: tag
```

Execute a deployment step for a single matrix permutation:

```yaml
---
deploy:
  heroku:
    app: mycompany.com
    when:
      matrix:
        GO_VERSION: 1.5
        REDIS_VERSION: 2.8
```

Define the same deployment step multiple times, using different configuration based on branch:

```yaml
---
deploy:
  heroku:
    app: test.mycompany.com
    when:
      branch: develop

  heroku:
    app: mycompany.com
    when:
      branch: master
```

---

## File: content/usage/matrix.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Matrix"
weight = 11
menu = "usage"
toc = true
+++

# Overview

Drone uses the `matrix` section of the `.drone.yml` to define the build matrix. Drone executes a build for each permutation in the matrix, allowing you to build and test a single commit against many configurations.

Example matrix definition for testing multiple Go and Redis versions. This matrix results in a total of 6 different build permutations:

```yaml
---
matrix:
  GO_VERSION:
    - 1.4
    - 1.3
  REDIS_VERSION:
    - 2.6
    - 2.8
    - 3.0
```

# Interpolation

Matrix variables are injected into the `.drone.yml` file using the `$$` syntax, performing a simple find / replace. Matrix variables are also injected into your build container as environment variables.

Example `.drone.yml` file before injecting the matrix parameters:

```yaml
---
build:
  image: golang:$$GO_VERSION
  commands:
    - go get
    - go build
    - go test

compose:
  redis:
    image: redis:$$REDIS_VERSION

matrix:
  GO_VERSION:
    - 1.4
    - 1.3
  REDIS_VERSION:
    - 2.6
    - 2.8
    - 3.0
```

Example `.drone.yml` file after injecting the matrix parameters:

```yaml
---
build:
  image: golang:1.4
  environment:
    - GO_VERSION=1.4
    - REDIS_VERSION=3.0
  commands:
    - go get
    - go build
    - go test

compose:
  redis:
    image: redis:3.0
```

# Deployments

Matrix builds execute the same `.drone.yml` multiple times, but with different parameters. This means that publish and deployment steps are executed multiple times as well, which is typically undesired. To restrict a publish or deployment step to a single permutation you can add the following condition:

```yaml
---
deploy:
  heroku:
    app: foo
    when:
      matrix:
        GO_VERSION: 1.4
        REDIS_VERSION: 3.0
```

---

## File: content/usage/notify.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Notifications"
weight = 9
menu = "usage"
toc = true
+++

# Overview

Notifications are triggered at the end of your entire build. If you are running a matrix build the notification is sent after all matrix jobs complete.

Example Slack notification using the Slack plugin:

```yaml
---
notify:
  slack:
    webhook_url: https://hooks.slack.com/services/...
    channel: dev
    username: drone
```

Please note notifications are executed after a build is already terminated and will not write any output to your build logs. For troubleshooting failed notifications please contact your system administrator to research errors in the Drone server logs.

# Plugins

Drone does not have any builtin notification capabilities. Drone instead offers a large library of plugins for sending [Slack](/plugins/slack/), [Hipchat](/plugins/hipchat/), [Email](/plugins/email/) notifications and more. Please see the [plugin documentation](/plugins/) for a complete list.

# Conditions

Use the `when` block to limit notification step execution:

```yaml
---
notify:
  slack:
    channel: foo
    when:
      success: false
      failure: false
      change: true
```

Execute a notification step if the branch is `master`:

```yaml
---
notify:
  slack:
    channel: foo
    when:
      branch: master
```

Execute a notification step if the branch is `master` or `develop`:

```yaml
---
notify:
  slack:
    channel: foo
    when:
      branch: [master, develop]
```

Execute a notification step if the branch is _not_ `develop`:

```yaml
---
notify:
  slack:
    channel: foo
    when:
      branch: "!develop"
```

Execute a notification step if the branch is starts with `prefix/*`:

```yaml
---
notify:
  slack:
    channel: foo
    when:
      branch: prefix/*
```

Execute a notification step when the commit is a `pull_request`, `push` or `tag`:

```yaml
---
notify:
  slack:
    channel: foo
    when:
      event: pull_request
```

Define the same notification step multiple times, using different configuration based on branch:

```yaml
---
notify:
  slack:
    channel: foo
    when:
      branch: develop

  slack:
    channel: bar
    when:
      branch: master
```

# Templates

Many of the Drone notifications support [handlebars](http://handlebarsjs.com/) templates for customizing notification messages. This example demonstrates a custom hipchat notification message:

```yaml
---
notify:
  hipchat:
    template: |
      {{ repo.full_name }} finished build {{ build.number }}
      with a status of {{ build.status }}
```

Example template that generates a different message based on build status:

```yaml
---
notify:
  hipchat:
    template: |
      {{#success build.status}}
        {{ build.author }} successfully pushed to {{ build.branch}}
      {{else}}
        {{ build.author }} broke the build. Hang your head in shame.
      {{/success}}
```

# Template Data

This is an example data structure passed to the template engine. Any of the below variables may be referenced in your template:

```js
{
    "build": {
        "number": 22,
        "status": "success",
        "started_at": 1421029603,
        "finished_at": 1421029813,
        "event": "push",
        "commit": "7fd1a60",
        "branch": "master",
        "message": "Update README",
        "author": "octocat",
        "author_email": "octocat@github.com",
        "link_url": "https://github.com/octocat/Hello-World/commit/7fd1a60"
    },
    "repo": {
        "owner": "octocat",
        "name": "hello-world",
        "full_name": "octocat/hello-world",
        "link_url": "https://github.com/octocat/hello-world",
        "clone_url": "https://github.com/octocat/hello-world.git"
    },
    "system": {
        "link_url": "https://drone.mycompany.com"
    }
}
```

# Template Builtins

Drone includes a number of builtin handlebars functions to help format your messages. This is an example builtin function that converts a string to all uppercase characters:

```handlebars
{{uppercase build.status}}
```

Converts a string to all lowercase characters:

```handlebars
{{uppercase build.author}}
```

Truncates a string to N characters:

```handlebars
{{ truncate build.commit 8 }}
```

Calculates a duration and returns a human readable string:

```handlebars
{{ duration build.started_at build.finished_at }}
```

Converts a timestamp to a human readable string:

```handlebars
finished at {{ datetime build.finished_at "3:04PM" "UTC" }}
```

Returns true if the build is successful:

```handlebars
{{#success build.status}}
  It works
{{/success}}
```

Returns true if the build failed:

```handlebars
{{#failure build.status}}
  Something is busted
{{/failure}}
```

---

## File: content/usage/overview.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Quick Start"
weight = 1
menu = "usage"
toc = true
+++

# Overview

In order to configure your build you must include a `.drone.yml` file in the root of your repository. This section provides a brief overview of the configuration file and build process.

Example .drone.yml configuration:

```yaml
---
build:
  image: golang
  commands:
    - go get
    - go build
    - go test
```

# Hooks

Once activated, every commit and pull request automatically send a hook from your version control system (ie GitHub) to Drone. These hooks instruct Drone to execute a new build.

When Drone receives a hook it fetches the `.drone.yml` from your repository and uses this as a blueprint for build execution. For the purposes of this tutorial let's assume your repository uses the following configuration:

```yaml
---
build:
  image: golang
  commands:
    - go get
    - go build
    - go test
```

# Cloning

Hooks specify commit details including branch and commit hash. Drone will automatically clone and checkout the commit into the build workspace:

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

git checkout 7fd1a60
```

# 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.

Example .drone.yml configuration uses the official Go Docker image:

```yaml
---
build:
  image: golang
```

# Commands

Drone previously cloned your source code into the build workspace. The build workspace is mounted into your Docker container at runtime as a volume. This means your code is cloned **outside** of the build container but your build commands are run **inside** of the build container.

Drone executes the following bash commands inside your build container:

```yaml
---
build:
  image: golang
  commands:
    - go get
    - go build
    - go test
```

# Services

Drone supports launching separate, ephemeral Docker containers as part of the build process. This is useful, for example, if you require a database for running your unit tests.

Example .drone.yml configuration with a Postgres database:

```yaml
---
build:
  image: golang
  commands:
    - go get
    - go build
    - go test

compose:
  database:
    image: postgres
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=mysecretpassword
```

# Deployments

Drone supports a large number of publish and deployment capabilities through external plugins. Plugins are Docker containers that are automatically downloaded, attach to your build, and execute a very specific publish or deployment task.

Example .drone.yml configuration with the Docker publish plugin:

```yaml
---
build:
  image: golang
  commands:
    - go get
    - go build
    - go test

publish:
  docker:
    username: octocat
    password: password
    email: octocat@github.com
    repo: octocat/hello-world
```

First Drone runs your build commands inside the Golang container:

```yaml
---
build:
  image: golang
  commands:
    - go get
    - go build
    - go test
```

Drone executes publish and deployment plugins upon successful completion of the build step. Plugins are executed in separate Docker containers but have access to your build workspace. This means any files created and stored in the `/drone` workspace are available to plugins.

The Docker plugin in our example runs `docker build` and `docker publish` after the build step successfully completes using the configuration parameters in the .drone.yml file:

```yaml
---
publish:
  docker:
    username: octocat
    password: password
    email: octocat@github.com
    repo: octocat/hello-world
```

# Local Testing

Download the [command line tools](/devs/cli) to build and test your code locally inside a Docker environment using the exact same build process as Drone. You should think of your `.drone.yml` file as a `docker-compose.yml` alternative that is optimized for repeatable, local testing.

Command to execute a local build from the command line:

```
drone exec
```

# Getting Help

For help troubleshooting **failed builds** please use [Stackoverflow](https://stackoverflow.com). The Stackoverflow community will be able to answer questions unique to your programming language and technology stack that the Drone maintainers are unqualified to answer.

For all other questions or issues please use the community [chat room](https://gitter.im/drone/drone) for support.

---

## File: content/usage/secrets.md

+++
date = "2015-12-05T16:00:21-08:00"
draft = false
title = "Secrets"
weight = 3
menu = "usage"
toc = true
+++

> WARNING: drone does not prevent you from inadvertently exposing your secrets to the world. Please read this section of the documentation carefully to ensure you follow best practices and avoid exposing sensitive data.


# Overview

Drone lets you store secret variables in an encrypted `.drone.sec` file in the root of your repository. This is useful when your build requires sensitive information that should not be stored in plaintext in your yaml file. This document assumes you have installed the Drone [command line tools](/devs/cli).

Start with a plaintext YAML file that defines your secrets. For demonstration purposes let's assume this file is stored on disk and named `secrets.yml`. Secrets are defined in the `environment` section of this file:

```yaml
---
environment:
  HEROKU_TOKEN: pa$$word
```

Reference secrets in your `.drone.yml` file using the `$$` notation:

```yaml
---
deploy:
  heroku:
    app: petstore
    token: $$HEROKU_TOKEN
```

Encrypt the `secrets.yml` file and generate a `.drone.sec` file:

```
drone secure --repo octocat/hello-world --in secrets.yml
```

Commit the encrypted `.drone.sec` file to the root of your repository:

```
git add .drone.sec
git commit -m "added .drone.sec file"
```

# Interpolation

Secrets are injected directly into the YAML at runtime using the `$$` notation:

```yaml
---
deploy:
  heroku:
    app: foo
    token: $$HEROKU_TOKEN
```

Note that secrets are not automatically exposed to your build environment as
environment variables. For security purposes, you be must explicit when and
where to inject secrets.

This example demonstrates explicitly injecting a secret as an environment variable:

```yaml
---
build:
  image: golang
  commands:
    - go build
    - go test
  environment:
    - PRIVATE_KEY=$$PRIVATE_KEY
```

Secrets that are multiple lines or contain special characters should be escaped to
avoid YAML parsing errors post-interpolation. You can escape strings by wrapping
the variable in quotes as shown below:

```yaml
---
build:
  image: golang
  commands:
    - go build
    - go test
  environment:
    - PRIVATE_KEY="$$PRIVATE_KEY"
```

# Checksums

Drone automatically calculates and stores a checksum of your `.drone.yml` file inside your `.drone.sec` file. Secrets are not injected into your build if the checksum cannot be verified. This means you must re-generate your `.drone.sec` file every time you `.drone.yml` changes (yes security is inconvenient).

Invalid checksums result in the following error at the top of your build logs:

```
Unable to validate YAML checksum.
2ca66eb7be89f31afdebb197174abfa6dd14866ecbf9e552f44be5bd3244d08a
```

# Pull Requests

Drone injects secrets for all build types, including pull requests, as long as the checksum validation passes. You should avoid injecting secrets into the build section of the YAML and inadvertently exposing your secrets to malicious pull requests.

**This is bad** because a malicious pull request could gain access to your secrets:

```yaml
---
build:
  image: node
  environment:
    PASSWORD: $$PASSWORD
  commands:
    - npm install
    - npm run tests
    - npm run integration
```

**This is better** because the build is split into sections. Secrets are injected into a section of the build that is not executed for pull requests:

```yaml
---
build:
  unit_tests:
    image: node
    commands:
      - npm install
      - npm run tests

  integration_tests:
    image: node
    environment:
      PASSWORD: $$PASSWORD
    commands:
      - npm run integration
    when:
      event: push
```


# Global Secrets

Global secrets are stored in the `PLUGIN_PARAMS` environment variable declared in your Drone server configuration file. Global secrets are passed to every single build and should therefore only be used in trusted environments with trusted developers.

Example global secret declaration:

```bash
PLUGIN_PARAMS=SMTP_PASSWORD=foo SLACK_TOKEN=bar
```

Example injecting global secrets into your `.drone.yml` file:

```yaml
---
deploy:
  slack:
    channel: foo
    token: $$SLACK_TOKEN
```


# Common Issues

Secrets are not injected into your build if the checksum cannot be validated. This happens when you change your `.drone.yml` file without re-generating a `.drone.sec` file resulting in the following error message at the top of your build logs:

```
Unable to validate YAML checksum.
2ca66eb7be89f31afdebb197174abfa6dd14866ecbf9e552f44be5bd3244d08a
```