Pipeline docs

docs/docs/environment-variables.md

@@ -0,0 +1,151 @@
+
+# Environment variables
+
+Woodpecker provides the ability to define environment variables scoped to individual build steps. Example pipeline step with custom environment variables:
+
+```diff
+pipeline:
+  build:
+    image: golang
++   environment:
++     - CGO=0
++     - GOOS=linux
++     - GOARCH=amd64
+    commands:
+      - go build
+      - go test
+```
+
+Please note that the environment section is not able to expand environment variables. If you need to expand variables they should be exported in the commands section.
+
+```diff
+pipeline:
+  build:
+    image: golang
+-   environment:
+-     - PATH=$PATH:/go
+    commands:
++     - export PATH=$PATH:/go
+      - go build
+      - go test
+```
+
+Please be warned that `${variable}` expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped:
+
+```diff
+pipeline:
+  build:
+    image: golang
+    commands:
+-     - export PATH=${PATH}:/go
++     - export PATH=$${PATH}:/go
+      - go build
+      - go test
+```
+
+## Built-in environment variables
+
+This is the reference list of all environment variables available to your build environment. These are injected into your build and plugins containers, at runtime.
+
+| NAME                         | DESC                                   |
+| ---------------------------- | -------------------------------------- |
+| `CI=drone`                   | environment is drone                   |
+| `DRONE=true`                 | environment is drone                   |
+| `DRONE_ARCH`                 | environment architecture (linux/amd64) |
+| `DRONE_REPO`                 | repository full name                   |
+| `DRONE_REPO_OWNER`           | repository owner                       |
+| `DRONE_REPO_NAME`            | repository name                        |
+| `DRONE_REPO_SCM`             | repository scm (git)                   |
+| `DRONE_REPO_LINK`            | repository link                        |
+| `DRONE_REPO_AVATAR`          | repository avatar                      |
+| `DRONE_REPO_BRANCH`          | repository default branch (master)     |
+| `DRONE_REPO_PRIVATE`         | repository is private                  |
+| `DRONE_REPO_TRUSTED`         | repository is trusted                  |
+| `DRONE_REMOTE_URL`           | repository clone url                   |
+| `DRONE_COMMIT_SHA`           | commit sha                             |
+| `DRONE_COMMIT_REF`           | commit ref                             |
+| `DRONE_COMMIT_BRANCH`        | commit branch                          |
+| `DRONE_COMMIT_LINK`          | commit link in remote                  |
+| `DRONE_COMMIT_MESSAGE`       | commit message                         |
+| `DRONE_COMMIT_AUTHOR`        | commit author username                 |
+| `DRONE_COMMIT_AUTHOR_EMAIL`  | commit author email address            |
+| `DRONE_COMMIT_AUTHOR_AVATAR` | commit author avatar                   |
+| `DRONE_BUILD_NUMBER`         | build number                           |
+| `DRONE_BUILD_EVENT`          | build event (push, pull_request, tag)  |
+| `DRONE_BUILD_STATUS`         | build status (success, failure)        |
+| `DRONE_BUILD_LINK`           | build result link                      |
+| `DRONE_BUILD_CREATED`        | build created unix timestamp           |
+| `DRONE_BUILD_STARTED`        | build started unix timestamp           |
+| `DRONE_BUILD_FINISHED`       | build finished unix timestamp          |
+| `DRONE_PREV_BUILD_STATUS`    | prior build status                     |
+| `DRONE_PREV_BUILD_NUMBER`    | prior build number                     |
+| `DRONE_PREV_COMMIT_SHA`      | prior build commit sha                 |
+| `DRONE_JOB_NUMBER`           | job number                             |
+| `DRONE_JOB_STATUS`           | job status                             |
+| `DRONE_JOB_STARTED`          | job started                            |
+| `DRONE_JOB_FINISHED`         | job finished                           |
+| `DRONE_BRANCH`               | commit branch                          |
+| `DRONE_TARGET_BRANCH`        | The target branch of a Pull Request    |
+| `DRONE_SOURCE_BRANCH`        | The source branch of a Pull Request    |
+| `DRONE_COMMIT`               | commit sha                             |
+| `DRONE_TAG`                  | commit tag                             |
+| `DRONE_PULL_REQUEST`         | pull request number                    |
+| `DRONE_DEPLOY_TO`            | deployment target (ie production)      |
+
+## String Substitution
+
+Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic build or commit details in our pipeline configuration.
+
+Example commit substitution:
+
+```diff
+pipeline:
+  docker:
+    image: plugins/docker
++   tags: ${DRONE_COMMIT_SHA}
+```
+
+Example tag substitution:
+
+```diff
+pipeline:
+  docker:
+    image: plugins/docker
++   tags: ${DRONE_TAG}
+```
+
+## String Operations
+
+Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values.
+
+| OPERATION          | DESC                                             |
+| ------------------ | ------------------------------------------------ |
+| `${param}`         | parameter substitution                           |
+| `${param,}`        | parameter substitution with lowercase first char |
+| `${param,,}`       | parameter substitution with lowercase            |
+| `${param^}`        | parameter substitution with uppercase first char |
+| `${param^^}`       | parameter substitution with uppercase            |
+| `${param:pos}`     | parameter substitution with substring            |
+| `${param:pos:len}` | parameter substitution with substring and length |
+| `${param=default}` | parameter substitution with default              |
+| `${param##prefix}` | parameter substitution with prefix removal       |
+| `${param%%suffix}` | parameter substitution with suffix removal       |
+| `${param/old/new}` | parameter substitution with find and replace     |
+
+Example variable substitution with substring:
+
+```diff
+pipeline:
+  docker:
+    image: plugins/docker
++   tags: ${DRONE_COMMIT_SHA:0:8}
+```
+
+Example variable substitution strips `v` prefix from `v.1.0.0`:
+
+```diff
+pipeline:
+  docker:
+    image: plugins/docker
++   tags: ${DRONE_TAG##v}
+```

docs/docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting started
+
+## Repository Activation
+
+To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your version control system (e.g. GitHub).
+
+Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
+
+![repository list](/images/repo_list.png)
+
+> Required Permissions
+>
+>The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook.
+>
+> Note that manually creating webhooks yourself is not possible. This is because webhooks are signed using a per-repository secret key which is not exposed to end users.
+
+# Webhooks
+
+When you activate your repository Woodpecker automatically add webhooks to your version control system (e.g. GitHub). There is no manual configuration required.
+
+Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
+
+
+
+## Configuration
+
+To configure you pipeline you should place a `.drone.yml` file in the root of your repository. The .drone.yml file is used to define your pipeline steps. It is a superset of the widely used docker-compose file format.
+
+Example pipeline configuration:
+
+```yaml
+pipeline:
+  build:
+    image: golang
+    commands:
+      - go get
+      - go build
+      - go test
+
+services:
+  postgres:
+    image: postgres:9.4.5
+    environment:
+      - POSTGRES_USER=myapp
+```
+
+Example pipeline configuration with multiple, serial steps:
+
+```yaml
+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
+```
+
+## Execution
+
+To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your version control system and execute your pipeline.

docs/docs/matrix-builds.md

@@ -0,0 +1,113 @@
+# Matrix builds
+
+Woodpecker has integrated support for matrix builds. Woodpecker executes a separate build task for each combination in the matrix, allowing you to build and test a single commit against multiple configurations.
+
+Example matrix definition:
+
+```yaml
+matrix:
+  GO_VERSION:
+    - 1.4
+    - 1.3
+  REDIS_VERSION:
+    - 2.6
+    - 2.8
+    - 3.0
+```
+
+Example matrix definition containing only specific combinations:
+
+```yaml
+matrix:
+  include:
+    - GO_VERSION: 1.4
+      REDIS_VERSION: 2.8
+    - GO_VERSION: 1.5
+      REDIS_VERSION: 2.8
+    - GO_VERSION: 1.6
+      REDIS_VERSION: 3.0
+```
+
+## Interpolation
+
+Matrix variables are interpolated in the yaml using the `${VARIABLE}` syntax, before the yaml is parsed. This is an example yaml file before interpolating matrix parameters:
+
+```yaml
+pipeline:
+  build:
+    image: golang:${GO_VERSION}
+    commands:
+      - go get
+      - go build
+      - go test
+
+services:
+  database:
+    image: ${DATABASE}
+
+matrix:
+  GO_VERSION:
+    - 1.4
+    - 1.3
+  DATABASE:
+    - mysql:5.5
+    - mysql:6.5
+    - mariadb:10.1
+```
+
+Example Yaml file after injecting the matrix parameters:
+
+```diff
+pipeline:
+  build:
+-   image: golang:${GO_VERSION}
++   image: golang:1.4
+    commands:
+      - go get
+      - go build
+      - go test
++   environment:
++     - GO_VERSION=1.4
++     - DATABASE=mysql:5.5
+
+services:
+  database:
+-   image: ${DATABASE}
++   image: mysql:5.5
+```
+
+## Examples
+
+Example matrix build based on Docker image tag:
+
+```yaml
+pipeline:
+  build:
+    image: golang:${TAG}
+    commands:
+      - go build
+      - go test
+
+matrix:
+  TAG:
+    - 1.7
+    - 1.8
+    - latest
+```
+
+Example matrix build based on Docker image:
+
+```yaml
+pipeline:
+  build:
+    image: ${IMAGE}
+    commands:
+      - go build
+      - go test
+
+matrix:
+  IMAGE:
+    - golang:1.7
+    - golang:1.8
+    - golang:latest
+```