updated drone docs

This commit is contained in:
Brad Rydzewski 2015-07-07 18:08:43 -07:00
parent 817eab7cae
commit a6f67474f8
10 changed files with 451 additions and 17 deletions

7
doc/build/README.md vendored
View file

@ -1,10 +1,9 @@
* [Overview](overview.md)
* [Environment](env.md)
* [Environment](environment.md)
* [Clone](clone.md)
* [Build](build.md)
* [Matrix](martrix.md)
* [Services](services.md)
* [Publish](publish.md)
* [Deploy](deploy.md)
* [Notify](notify.md)
* [Services](services.md)
* [Selenium](selenium.md)
* [Matrix](martrix.md)

63
doc/build/build.md vendored
View file

@ -0,0 +1,63 @@
# Build
Drone uses the `build` section of the `.drone.yml` to describe your Docker build environment and specify your build and test instructions. The following is an example build definition:
```yaml
build:
image: golang
environment:
- GOBIN=/drone/bin
commands:
- go get
- go build
- go test
```
## Build options
The build configuration options:
* `image` - any valid Docker image name
* `pull` - if true, will always attempt to pull the latest image
* `environment` - list of environment variables, declared in `name=value` format
* `privileged` - if true, runs the container with extended privileges [1]
* `volumes` - list of bind mounted volumes on the host machine [1]
* `net` - sets the container [network mode](https://docs.docker.com/articles/networking/#container-networking) [1]
* `commands` - list of build commands
[1] Some build options are disabled for security reasons, including `volumes`, `privileged` and `net`. To enable these options, a system administrator must white-list your repository as trusted. This can be done via the repository settings screen.
## Build image
The `image` attribute supports any valid Docker image name:
```yaml
# Docker library image
image: golang
# Docker library image, with tag
image: golang:1.4
# Docker image, full name, with tag
image: library/golang:1.4
# fully qualified Docker image URI, with tag
image: index.docker.io/library/golang:1.4
```
## Build environment
The build environment has access to the following environment variables:
* `CI=true`
* `DRONE=true`
* `DRONE_REPO` - repository name for the current build
* `DRONE_BUILD` - build number for the current build
* `DRONE_BRANCH` - branch name for the current build
* `DRONE_COMMIT` - git sha for the current build
* `DRONE_DIR` - working directory for the current build
## Skipping builds
Skip a build by including the text `[CI SKIP]` in your commit message.

26
doc/build/clone.md vendored
View file

@ -1,25 +1,25 @@
# Clone
Drone automatically clones your repository and submodules at the start of your build. No configuration is required, however, you can use the `clone` section of the `.drone.yml` to customize this behavior.
Drone automatically clones your repository and submodules at the start of your build. No configuration is required. You can, however, use the `clone` section of the `.drone.yml` to customize this behavior as needed.
## Clone Options
The custom clone options are:
* `depth` creates a shallow clone with truncated history
* `recursive` recursively clones git submodules
* `path` relative path inside `/drone/src` where the repository is cloned
* `depth` - creates a shallow clone with truncated history
* `recursive` - recursively clones git submodules
* `path` - relative path inside `/drone/src` where the repository is cloned
This is an example yaml configuration:
```
```yaml
clone:
depth: 50
recursive: true
path: github.com/drone/drone
```
resulting in the following clone command:
Which results in the following command:
```
git clone --depth=50 --recusive=true \
@ -27,23 +27,23 @@ git clone --depth=50 --recusive=true \
/drone/src/github.com/drone/drone
```
## Authentication
## Clone Private Repos
Cloning a private repository requires authentication to the remote system. Drone prefers `git+https` and `netrc` files to authenticate, but will fallback to `git+ssh` and deploy keys if not supported.
Cloning a private repository requires authentication to the remote system. Drone prefers `git+https` and `netrc` to authenticate, but will fallback to `git+ssh` and deploy keys if not supported.
Drone prefers using `netrc` files for authentication because they allow you to clone other private repositories. This is helpful when you have third party dependencies you need to download (via `go get` or `npm install` or others) that are sourced from a private repository.
Drone prefers `git+ssh` for authentication because it allows you to clone multiple private repositories. This is helpful when you have git submodules or third party dependencies you need to download (via `go get` or `npm install` or others) that are sourced from a private repository.
Drone only injects the `.netrc` file and `ssh` keys into your build environment if your repository is private, or if the remote system is running in private mode. We do this for security reasons to avoid leaking sensitive data.
Drone only injects the `netrc` and `id_rsa` files into your build environment if your repository is private, or running in private mode. We do this for security reasons to avoid leaking sensitive data.
## Custom Plugin
## Clone Plugins
You can override the default `git` plugin by specifying an alternative plugin image. An example use case may be integrating with alternate version control systems, such as mercurial:
```yml
```yaml
clone:
image: bradrydzewski/hg
# below are plubin-specific parameters
# below are plugin-specific parameters
path: override/default/clone/path
insecure: false
verbose: true

85
doc/build/deploy.md vendored
View file

@ -0,0 +1,85 @@
# Deploy
Drone uses the `deploy` section of the `.drone.yml` to configure deployment steps. Drone does not have any built-in deployment capabilities. This functionality is outsourced to [plugins](http://addons.drone.io). See the [plugin marketplace](http://addons.drone.io) for a list of official plugins.
An example plugin that deploys to Heroku:
```yaml
deploy:
heroku:
app: pied_piper
token: f10e2821bbbea5
```
## Deploy plugins
Deployment plugins are Docker images that attach to your build environment at runtime. They are declared in the `.drone.yml` using the following format:
```
deploy:
[step_name:]
[image:]
[options]
```
An example `heroku` plugin configuration:
```yaml
deploy:
heroku:
image: plugins/heroku
app: pied_piper
token: f10e2821bbbea5
```
The `image` attribute is optional. If the `image` is not specified Drone attempts to use the `step_name` as the `image` name. The below examples both produce identical output:
```yaml
# this step specifies an image
heroku:
image: plubins/heroku
app: pied_piper
token: f10e2821bbbea5
# and this step infers the image from the step_name
heroku:
app: pied_piper
token: f10e2821bbbea5
```
The `image` attribute is useful when you need to invoke the same plugin multiple times. For example, we may want to deploy to multiple `heroku` environments depending on branch:
```yaml
# deploy master to our production heroku environment
heroku_prod:
image: plugins/heroku
when:
branch: master
# deploy to our staging heroku environment
heroku_staging:
image: plugins/heroku
when:
branch: stage
```
## Deploy conditions
Use the `when` attribute to limit deployments to a specific branch:
```yaml
deploy:
heroku:
when:
branch: master
# you can also do simple matching
google_appengine:
when:
branch: feature/*
```

36
doc/build/env.md vendored
View file

@ -0,0 +1,36 @@
# Environment
The build environment is largely defined by the Docker image you specify in the `.drone.yml`. In addition, Drone will inject default environment variable and private variables.
## Environment Variables
The build environment has access to the following environment variables:
* `CI=true`
* `DRONE=true`
* `DRONE_REPO` - repository name for the current build
* `DRONE_BUILD` - build number for the current build
* `DRONE_BRANCH` - branch name for the current build
* `DRONE_COMMIT` - git sha for the current build
* `DRONE_DIR` - working directory for the current build
## Private Variables
Drone allows you to store sensitive data external to the `.drone.yml` and inject at runtime. You can declare private variables in the repository settings screen. These variables are injected into the `.drone.yml` at runtime using the `$$` notation.
An example `.drone.yml` expecting the `HEROKU_TOKEN` private variable:
```yaml
build:
image: golang
commands:
- go get
- go build
- go test
publish:
heroku:
app: pied_piper
token: $$HEROKU_TOKEN
```

83
doc/build/matrix.md vendored
View file

@ -0,0 +1,83 @@
# Matrix Builds
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.
Below is an example `.drone.yml` that tests a single commit against multiple versions of Go and Redis, resulting in a total of 6 different build permutations:
```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
```
## Matrix Variables
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.
This is an 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
REDIS_VERSION:
- 3.0
```
And this is the `.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
```
## Matrix 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
```

36
doc/build/notify.md vendored
View file

@ -0,0 +1,36 @@
# Notify
Drone uses the `notify` section of the `.drone.yml` to configure notification steps. Drone does not have any built-in notification capabilities. This functionality is outsourced to [plugins](http://addons.drone.io). See the [plugin marketplace](http://addons.drone.io) for a list of official plugins.
An example configuration that sends a Slack notification on build completion:
```yaml
notify:
slack:
webhook_url: https://hooks.slack.com/services/f10e2821bbb/200352313bc
channel: dev
username: drone
```
## Notification conditions
Use the `when` attribute to limit execution to a specific branch:
```yaml
publish:
slack:
when:
branch: master
```
> **NOTE** the ability to limit notifications by status (ie success, failure, etc) is not yet implemented
Or limit execution based on the build status. The below example will only send the notification when the build fails:
```yaml
publish:
slack:
when:
success: false
failure: true
```

41
doc/build/overview.md vendored
View file

@ -0,0 +1,41 @@
# Overview
In order to configure your build, you must include a `.drone.yml` file in the root of your repository. This documentation describes the `.drone.yml` configuration file format.
Example `.drone.yml` file for a Go repository:
```yaml
build:
image: golang
commands:
- go get
- go build
- go test
```
A more comprehensive example with linked service containers, deployment plugins and notification plugins:
```yaml
build:
image: golang
commands:
- go get
- go build
- go test
compose:
cache:
image: redis
database:
image: mysql
deploy:
heroku:
app: pied_piper
when:
branch: master
notify:
slack:
channel: myteam
```

33
doc/build/publish.md vendored
View file

@ -0,0 +1,33 @@
# Publish
Drone uses the `publish` section of the `.drone.yml` to configure publish steps. Drone does not have any built-in publish or artifact capabilities. This functionality is outsourced to [plugins](http://addons.drone.io). See the [plugin marketplace](http://addons.drone.io) for a list of official plugins.
An example configuration that builds a Docker image and publishes to the registry:
```yaml
pubish:
docker:
username: kevinbacon
password: pa55word
email: kevin.bacon@mail.com
repo: foo/bar
tag: latest
file: Dockerfile
```
## Publish conditions
Use the `when` attribute to limit execution to a specific branch:
```yaml
publish:
docker:
when:
branch: master
# you can also do simple matching
bintray:
when:
branch: feature/*
```

58
doc/build/services.md vendored
View file

@ -0,0 +1,58 @@
# Services
Drone uses the `compose` section of the `.drone.yml` to specify supporting containers (ie service containers) that should be started and linked to your build container. The `compose` section of the `.drone.yml` is modeled after `docker-compose`:
```
compose:
[container_name:]
image: [image_name]
[options]
```
Example configuration that composes a Postgres and Redis container:
```yaml
compose:
cache:
image: redis
database:
image: postgres
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=mysecretpassword
```
## Service linking
Service containers share the same network as the build container (using `--net=<container>`). This means that you can access your service container using `localhost` or `127.0.0.1`.
## Service options
The service container configuration options:
* `image` - any valid Docker image name
* `pull` - if true, will always attempt to pull the latest image
* `environment` - list of environment variables, declared in `name=value` format
* `privileged` - if true, runs the container with extended privileges [1]
* `volumes` - list of bind mounted volumes on the host machine [1]
* `net` - sets the container [network mode](https://docs.docker.com/articles/networking/#container-networking) [1]
[1] Some build options are disabled for security reasons, including `volumes`, `privileged` and `net`. To enable these options, a system administrator must white-list your repository as trusted. This can be done via the repository settings screen.
## Service images
The `image` attribute supports any valid Docker image name:
```yaml
# Docker library image
image: postgres
# Docker library image, with tag
image: postgres:9.2
# Docker image, full name, with tag
image: library/postgres:9.2
# fully qualified Docker image URI, with tag
image: index.docker.io/library/postgres:9.2
```