[Docs] Migrate docs framework to Docusaurus (#282)

- Replace mkdocs with docosaurus (improved menu structure, ...)
- Structure docs into `Usage` and `Server Setup / Administration`
- Update favicon
- Create new pipeline-syntax page with all options and links to more detailed docs if available
- Add ci to publish to `woodpecker-ci.github.io`
- Deploy docs preview to surge for review
- Update start-page

Co-authored-by: 6543 <6543@obermui.de>
This commit is contained in:
Anbraten 2021-09-11 17:10:32 +02:00 committed by GitHub
parent 4e721c07cc
commit 9267a46d5c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
65 changed files with 10237 additions and 969 deletions

3
.gitignore vendored
View file

@ -40,3 +40,6 @@ server/swagger/files/*.json
server/swagger/swagger_gen.go
docs/venv
dist/
node_modules/

37
.woodpecker/docs.yml Normal file
View file

@ -0,0 +1,37 @@
clone:
git:
image: plugins/git:next
branches: master
pipeline:
deploy-docs:
image: node:14-alpine
secrets:
- BOT_PRIVATE_KEY
environment:
- USE_SSH=true
- GIT_USER=woodpecker-bot
- DEPLOYMENT_BRANCH=master
commands:
- mkdir -p $HOME/.ssh
- ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts
- echo "$BOT_PRIVATE_KEY > $HOME/.ssh/id_rsa"
- chmod 0600 $HOME/.ssh/id_rsa
- cd docs/
- yarn install --frozen-lockfile
- yarn deploy
when:
event: push
branch: master
path: "docs/*"
build-docs-pr:
image: node:14-alpine
commands:
- cd docs/
- yarn install --frozen-lockfile
- yarn build
when:
event: [pull_request]
path: "docs/*"

20
docs/.gitignore vendored Normal file
View file

@ -0,0 +1,20 @@
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*

33
docs/README.md Normal file
View file

@ -0,0 +1,33 @@
# Website
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
### Installation
```
$ yarn
```
### Local Development
```
$ yarn start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
### Build
```
$ yarn build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
### Deployment
```
$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

3
docs/babel.config.js Normal file
View file

@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

View file

@ -2,16 +2,16 @@
Woodpecker is a simple CI engine with great extensibility.
![woodpecker](/images/woodpecker.png)
![woodpecker](woodpecker.png)
## .drone.yml
## .woodpecker.yml
- Place your pipeline in a file named `.drone.yml` in your repository
- Place your pipeline in a file named `.woodpecker.yml` in your repository
- Pipeline steps can be named as you like
- Run any command in the commands section
```yaml
# .drone.yml
# .woodpecker.yml
pipeline:
build:
image: debian
@ -43,7 +43,7 @@ pipeline:
- Changes to files are persisted through steps as the same volume is mounted to all steps
```yaml
# .drone.yml
# .woodpecker.yml
pipeline:
build:
image: debian
@ -75,11 +75,11 @@ kubectl apply -f $PLUGIN_TEMPLATE
```
```yaml
# .drone.yml
# .woodpecker.yml
pipeline:
deploy-to-k8s:
image: laszlocloud/my-k8s-plugin
template: config/k8s/service.yml
```
See a [detailed plugin example](/usage/bash-plugin).
See [plugin docs](/docs/usage/plugins/plugins).

View file

@ -6,7 +6,7 @@ To activate your project navigate to your account settings. You will see a list
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)
![repository list](repo-list.png)
> Required Permissions
>
@ -24,7 +24,7 @@ Webhooks are used to trigger pipeline executions. When you push code to your rep
## 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.
To configure you pipeline you should place a `.woodpecker.yml` file in the root of your repository. The .woodpecker.yml file is used to define your pipeline steps. It is a superset of the widely used docker-compose file format.
Example pipeline configuration:
@ -64,7 +64,7 @@ pipeline:
notify:
image: plugins/slack
channel: developers
username: drone
username: woodpecker
```
## Execution

View file

@ -1,4 +1,4 @@
# Pipelines
# Pipeline syntax
The pipeline section defines a list of steps to build, test and deploy your code. Pipeline steps are executed serially, in the order in which they are defined. If a step returns a non-zero exit code, the pipeline immediately aborts and returns a failure status.
@ -21,9 +21,10 @@ pipeline:
In the above example we define two pipeline steps, `frontend` and `backend`. The names of these steps are completely arbitrary.
## Build Steps
## Steps
Build steps are steps in your pipeline that execute arbitrary commands inside the specified docker container. The commands are executed using the workspace as the working directory.
Every step of your pipeline executes arbitrary commands inside a specified docker container. The defined commands are executed serially.
The associated commit of a current pipeline run is checked out with git to a workspace which is mounted to every step of the pipeline as the working directory.
```diff
pipeline:
@ -34,25 +35,7 @@ pipeline:
+ - go test
```
There is no magic here. The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script:
```diff
#!/bin/sh
set -e
go build
go test
```
The above shell script is then executed as the docker entrypoint. The below docker command is an (incomplete) example of how the script is executed:
```
docker run --entrypoint=build.sh golang
```
> Please note that only build steps can define commands. You cannot use commands with plugins or services.
## Images
## Step `image`
Woodpecker uses Docker images for the build environment, for plugins and for service containers. The image field is exposed in the container blocks in the Yaml:
@ -125,39 +108,235 @@ Example registry hostname matching logic:
- Hostname `docker.io` matches `bradyrydzewski/golang`
- Hostname `docker.io` matches `bradyrydzewski/golang:latest`
#### Global registry setting
#### Global registry support
If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration.
Point it to your server's docker config.
To make a private registry globally available check the [server configuration docs](/docs/administration/server-config#global-registry-setting).
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
volumes:
- woodpecker-server-data:/var/lib/drone/
restart: always
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
+ - WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json
```
#### GCR Registry Support
#### GCR registry support
For specific details on configuring access to Google Container Registry, please view the docs [here](https://cloud.google.com/container-registry/docs/advanced-authentication#using_a_json_key_file).
## Parallel Execution
## Step `commands`
Commands of every pipeline step are executed serially as if you would enter them into your local shell.
```diff
pipeline:
backend:
image: golang
commands:
+ - go build
+ - go test
```
There is no magic here. The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script:
```diff
#!/bin/sh
set -e
go build
go test
```
The above shell script is then executed as the docker entrypoint. The below docker command is an (incomplete) example of how the script is executed:
```
docker run --entrypoint=build.sh golang
```
> Please note that only build steps can define commands. You cannot use commands with plugins or services.
## Step `environment`
Woodpecker provides the ability to pass environment variables to individual pipeline steps.
For more details check the [environment docs](/docs/usage/environment/).
## Step `secrets`
Woodpecker provides the ability to store named parameters external to the Yaml configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime.
For more details check the [secrets docs](/docs/usage/secrets/).
## Step `when` - Conditional Execution
Woodpecker supports defining conditional pipeline steps in the `when` block. If all conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped.
### `branch`
Example conditional execution by branch:
```diff
pipeline:
slack:
image: plugins/slack
channel: dev
+ when:
+ branch: master
```
> The step now triggers on master, but also if the target branch of a pull request is `master`. Add an event condition to limit it further to pushes on master only.
Execute a step if the branch is `master` or `develop`:
```diff
when:
branch: [master, develop]
```
Execute a step if the branch starts with `prefix/*`:
```diff
when:
branch: prefix/*
```
Execute a step using custom include and exclude logic:
```diff
when:
branch:
include: [ master, release/* ]
exclude: [ release/1.0.0, release/1.1.* ]
```
### `event`
Execute a step if the build event is a `tag`:
```diff
when:
event: tag
```
Execute a step if the build event is a `tag` created from the specified branch:
```diff
when:
event: tag
+ branch: master
```
Execute a step for all non-pull request events:
```diff
when:
event: [push, tag, deployment]
```
Execute a step for all build events:
```diff
when:
event: [push, pull_request, tag, deployment]
```
### `tag`
Execute a step if the tag name starts with `release`:
```diff
when:
tag: release*
```
### `status`
Execute a step when the build status changes:
```diff
when:
status: changed
```
Woodpecker uses the container exit code to determine the success or failure status of a build. Non-zero exit codes fail the build and cause the pipeline to immediately exit.
There are use cases for executing pipeline steps on failure, such as sending notifications for failed builds. Use the status constraint to override the default behavior and execute steps even when the build status is failure:
Execute a step when the build is passing or failing:
```diff
pipeline:
slack:
image: plugins/slack
channel: dev
+ when:
+ status: [ success, failure ]
```
### `plattform`
Execute a step for a specific platform:
```diff
when:
platform: linux/amd64
```
Execute a step for a specific platform using wildcards:
```diff
when:
platform: [ linux/*, windows/amd64 ]
```
### `environment`
Execute a step for deployment events matching the target deployment environment:
```diff
when:
environment: production
event: deployment
```
### `matrix`
Execute a step for a single matrix permutation:
```diff
when:
matrix:
GO_VERSION: 1.5
REDIS_VERSION: 2.8
```
### `instance`
Execute a step only on a certain Woodpecker instance matching the specified hostname:
```diff
when:
instance: stage.woodpecker.company.com
```
### `path`
Execute a step only on commit with certain files added/removed/modified:
> NOTE: Feature is only available for GitHub and Gitea repositories.
```diff
when:
path: "src/*"
```
Execute a step only on commit excluding certain files added/removed/modified:
> NOTE: Feature is only available for GitHub and Gitea repositories.
```diff
when:
path:
exclude: [ '*.md', '*.ini' ]
ignore_message: "[ALL]"
```
** Note for `path` conditions: passing `[ALL]` inside the commit message will ignore all path conditions. **
## Step `group` - Parallel execution
Woodpecker supports parallel step execution for same-machine fan-in and fan-out. Parallel steps are configured using the `group` attribute. This instructs the pipeline runner to execute the named group in parallel.
@ -185,9 +364,15 @@ pipeline:
In the above example, the `frontend` and `backend` steps are executed in parallel. The pipeline runner will not execute the `publish` step until the group completes.
## Conditional Pipeline Execution
## Step `volumes`
Woodpecker supports defining conditional pipelines to skip commits based on the target branch. If the branch matches the `branches:` block the pipeline is executed, otherwise it is skipped.
Woodpecker gives the ability to define Docker volumes in the Yaml. You can use this parameter to mount files or folders on the host machine into your containers.
For more details check the [volumes docs](/docs/usage/volumes/).
## `branches`
Woodpecker gives the ability to skip commits based on the target branch. If the branch matches the `branches:` block the pipeline is executed, otherwise it is skipped.
Example skipping a commit when the target branch is not master:
@ -256,198 +441,7 @@ pipeline:
+ exclude: [ develop, feature/* ]
```
## Conditional Step Execution
Woodpecker supports defining conditional pipeline steps in the `when` block. If all conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped.
Example conditional execution by branch:
```diff
pipeline:
slack:
image: plugins/slack
channel: dev
+ when:
+ branch: master
```
> The step now triggers on master, but also if the target branch of a pull request is `master`. Add an event condition to limit it further to pushes on master only.
Execute a step if the branch is `master` or `develop`:
```diff
when:
branch: [master, develop]
```
Execute a step if the branch starts with `prefix/*`:
```diff
when:
branch: prefix/*
```
Execute a step using custom include and exclude logic:
```diff
when:
branch:
include: [ master, release/* ]
exclude: [ release/1.0.0, release/1.1.* ]
```
Execute a step if the build event is a `tag`:
```diff
when:
event: tag
```
Execute a step if the build event is a `tag` created from the specified branch:
```diff
when:
event: tag
+ branch: master
```
Execute a step for all non-pull request events:
```diff
when:
event: [push, tag, deployment]
```
Execute a step for all build events:
```diff
when:
event: [push, pull_request, tag, deployment]
```
Execute a step if the tag name starts with `release`:
```diff
when:
tag: release*
```
Execute a step when the build status changes:
```diff
when:
status: changed
```
Execute a step when the build is passing or failing:
```diff
when:
status: [ failure, success ]
```
Execute a step for a specific platform:
```diff
when:
platform: linux/amd64
```
Execute a step for a specific platform using wildcards:
```diff
when:
platform: [ linux/*, windows/amd64 ]
```
Execute a step for deployment events matching the target deployment environment:
```diff
when:
environment: production
event: deployment
```
Execute a step for a single matrix permutation:
```diff
when:
matrix:
GO_VERSION: 1.5
REDIS_VERSION: 2.8
```
Execute a step only on a certain Woodpecker instance:
```diff
when:
instance: stage.drone.company.com
```
Execute a step only on commit with certain files added/removed/modified:
**NOTE: Feature is only available for Github and Gitea repositories.**
```diff
when:
path: "src/*"
```
Execute a step only on commit excluding certain files added/removed/modified:
**NOTE: Feature is only available for Github and Gitea repositories.**
```diff
when:
path:
exclude: [ '*.md', '*.ini' ]
ignore_message: "[ALL]"
```
> Note for `path` conditions: passing `[ALL]` inside the commit message will ignore all path conditions.
#### Failure Execution
Woodpecker uses the container exit code to determine the success or failure status of a build. Non-zero exit codes fail the build and cause the pipeline to immediately exit.
There are use cases for executing pipeline steps on failure, such as sending notifications for failed builds. Use the status constraint to override the default behavior and execute steps even when the build status is failure:
```diff
pipeline:
slack:
image: plugins/slack
channel: dev
+ when:
+ status: [ success, failure ]
```
## Skip Commits
Woodpecker gives the ability to skip individual commits by adding `[CI SKIP]` to the commit message. Note this is case-insensitive.
```diff
git commit -m "updated README [CI SKIP]"
```
## Skip Branches
Woodpecker gives the ability to skip commits based on the target branch. The below example will skip a commit when the target branch is not master.
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
+branches: master
```
Please see the pipeline conditions [documentation]({{< ref "usage/config/pipeline-conditions.md" >}}) for more options and details.
## Workspace
## `workspace`
The workspace defines the shared volume and working directory shared by all pipeline steps. The default workspace matches the below pattern, based on your repository url.
@ -511,7 +505,13 @@ git clone https://github.com/octocat/hello-world \
/go/src/github.com/octocat/hello-world
```
## Cloning
## `matrix`
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.
For more details check the [matrix build docs](/docs/usage/matrix-builds/).
## `clone`
Woodpecker automatically configures a default clone step if not explicitly defined. You can manually configure the clone step in your pipeline for customization:
@ -565,7 +565,7 @@ To use the credentials that cloned the repository to clone it's submodules, upda
+ url = https://github.com/octocat/my-module.git
```
To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use the https url in drone, add `submodule_override`:
To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use the https url in Woodpecker, add `submodule_override`:
```diff
clone:
@ -579,11 +579,25 @@ pipeline:
...
```
## `services`
Woodpecker can provide service containers. They can for example be used to run databases or cache containers during the execution of pipeline.
For more details check the [services docs](/docs/usage/services/).
## Skip Commits
Woodpecker gives the ability to skip individual commits by adding `[CI SKIP]` to the commit message. Note this is case-insensitive.
```diff
git commit -m "updated README [CI SKIP]"
```
## Privileged mode
Woodpecker gives the ability to configure privileged mode in the Yaml. You can use this parameter to launch containers with escalated capabilities.
> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments.
> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](/docs/usage/project-settings#trusted) to enable trusted mode.
```diff
pipeline:
@ -600,22 +614,3 @@ services:
command: [ "--storage-driver=vfs", "--tls=false" ]
+ privileged: true
```
# Badges
Woodpecker has integrated support for repository status badges. These badges can be added to your website or project readme file to display the status of your code.
Badge endpoint:
```text
<scheme>://<hostname>/api/badges/<owner>/<repo>/status.svg
```
The status badge displays the status for the latest build to your default branch (e.g. master). You can customize the branch by adding the `branch` query parameter.
```diff
-<scheme>://<hostname>/api/badges/<owner>/<repo>/status.svg
+<scheme>://<hostname>/api/badges/<owner>/<repo>/status.svg?branch=<branch>
```
Please note status badges do not include pull request results, since the status of a pull request does not provide an accurate representation of your repository state.

View file

@ -1,11 +1,10 @@
# Multi pipelines
# Multi-pipeline builds
> NOTE: This Feature is only available for GitHub & Gitea repositories. Follow [this](https://github.com/woodpecker-ci/woodpecker/issues/131) issue to support further development.
**NOTE: Feature is only available for Github repositories. Follow [this](https://github.com/woodpecker-ci/woodpecker/issues/131) issue to support further development.**
By default, Woodpecker looks for the pipeline definition in `.woodpecker.yml` in the project root.
By default, Woodpecker looks for the pipeline definition in `.drone.yml` in the project root.
The Multi-Pipeline feature allows the pipeline to be splitted to several files and placed in the `.drone/` folder
The Multi-Pipeline feature allows the pipeline to be split into several files and placed in the `.woodpecker/` folder. Only `.yml` files will we used and files in any subfolders like `.woodpecker/sub-folder/test.yml` will be ignored. You can set some custom path like `.my-ci/pipelines/` instead of `.woodpecker/` in the [project settings](/docs/usage/project-settings).
## Rational
@ -16,14 +15,14 @@ The Multi-Pipeline feature allows the pipeline to be splitted to several files a
## Example multi-pipeline definition
```bash
.drone
.woodpecker/
├── .build.yml
├── .deploy.yml
├── .lint.yml
└── .test.yml
```
.drone/.build.yml
.woodpecker/.build.yml
```yaml
pipeline:
@ -34,7 +33,7 @@ pipeline:
- sleep 5
```
.drone/.deploy.yml
.woodpecker/.deploy.yml
```yaml
pipeline:
@ -49,7 +48,7 @@ depends_on:
- test
```
.drone/.test.yml
.woodpecker/.test.yml
```yaml
pipeline:
@ -63,7 +62,7 @@ depends_on:
- build
```
.drone/.lint.yml
.woodpecker/.lint.yml
```yaml
pipeline:
@ -76,14 +75,15 @@ pipeline:
## Status lines
Each pipeline has its own status line on Github.
Each pipeline has its own status line on GitHub.
## Flow control
The pipelines run in parallel on a separate agents and share nothing.
The pipelines run in parallel on separate agents and share nothing.
Dependencies between pipelines can be set with the `depends_on` element. A pipeline doesn't execute until its dependencies did not complete succesfully.
Dependencies between pipelines can be set with the `depends_on` element. A pipeline doesn't execute until its dependencies did not complete successfully.
The name for a `depends_on` entry is the filename without the path, leading dots and without the file extension `.yml`. If the project config for example uses `.woodpecker/` as path for ci files with a file named `.woodpecker/.lint.yml` the corresponding `depends_on` entry would be `lint`.
```diff
pipeline:

View file

@ -1,7 +1,6 @@
# Secrets
Woodpecker provides the ability to store named parameters external to the Yaml configuration file, in a central secret store. Individual steps in the yaml can request access to these named parameters at runtime.
Woodpecker provides the ability to store named parameters external to the Yaml configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime.
Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline.
@ -12,7 +11,7 @@ pipeline:
commands:
+ - echo $DOCKER_USERNAME
+ - echo $DOCKER_PASSWORD
secrets: [ docker_username, docker_password ]
+ secrets: [ docker_username, docker_password ]
```
Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
@ -53,7 +52,7 @@ pipeline:
Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type.
```diff
drone secret add \
woodpecker-cli secret add \
-repository octocat/hello-world \
-image plugins/docker \
+ -event pull_request \
@ -70,7 +69,7 @@ Please be careful when exposing secrets to pull requests. If your repository is
Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events).
```diff
drone secret add \
woodpecker-cli secret add \
-repository octocat/hello-world \
-name aws_access_key_id \
-value <value>
@ -79,7 +78,7 @@ drone secret add \
Create the secret and limit to a single image:
```diff
drone secret add \
woodpecker-cli secret add \
-repository octocat/hello-world \
+ -image plugins/s3 \
-name aws_access_key_id \
@ -89,10 +88,10 @@ drone secret add \
Create the secrets and limit to a set of images:
```diff
drone secret add \
woodpecker-cli secret add \
-repository octocat/hello-world \
+ -image plugins/s3 \
+ -image peloton/drone-ecs \
+ -image peloton/woodpecker-ecs \
-name aws_access_key_id \
-value <value>
```
@ -100,7 +99,7 @@ drone secret add \
Create the secret and enable for multiple hook events:
```diff
drone secret add \
woodpecker-cli secret add \
-repository octocat/hello-world \
-image plugins/s3 \
+ -event pull_request \
@ -113,7 +112,7 @@ drone secret add \
Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines:
```diff
drone secret add \
woodpecker-cli secret add \
-repository octocat/hello-world \
-name ssh_key \
+ -value @/root/ssh/id_rsa

View file

@ -1,7 +1,6 @@
# Environment variables
Woodpecker provides the ability to define environment variables scoped to individual build steps. Example pipeline step with custom environment variables:
Woodpecker provides the ability to pass environment variables to individual pipeline steps. Example pipeline step with custom environment variables:
```diff
pipeline:
@ -30,7 +29,7 @@ pipeline:
- 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:
> 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:

View file

@ -28,4 +28,4 @@ Plugins are executed in Docker containers and are isolated from the other steps
## Creating a plugin
See a [detailed plugin example](/usage/bash-plugin).
See a [detailed plugin example](/docs/usage/plugins/sample-plugin).

View file

@ -1,4 +1,4 @@
# Writing a plugin
# Example plugin
This provides a brief tutorial for creating a Woodpecker webhook plugin, using simple shell scripting, to make an http requests during the build pipeline.

View file

@ -0,0 +1,4 @@
label: 'Plugins'
# position: 2
collapsible: true
collapsed: true

View file

@ -1,4 +1,3 @@
# Services
Woodpecker provides a services section in the Yaml file used for defining service containers. The below configuration composes database and cache containers.

View file

@ -2,7 +2,7 @@
Woodpecker gives the ability to define Docker volumes in the Yaml. You can use this parameter to mount files or folders on the host machine into your containers.
> Volumes are only available to trusted repositories and for security reasons should only be used in private environments.
> Volumes are only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](/docs/usage/project-settings#trusted) to enable trusted mode.
```diff
pipeline:

View file

@ -0,0 +1,38 @@
# Project settings
As the owner of a project in Woodpecker you can change some project related settings via the Webinterface.
![project settings](./project-settings.png)
## Pipeline path
The path to the pipeline file or folder. By default it point `.woodpecker.yml`. To use a [multi pipeline](/docs/usage/multi-pipeline) you have to change it to a folder path ending with `/` like `.woodpecker/`.
If you enable the fallback check, Woodpecker will first try to load the configuration from the defined path and if it fails to find that file it will try to use `.drone.yml`.
## Repository hooks
Your Version-Control-System will notify Woodpecker about some events via webhooks. If you want your pipeline to only run on specific webhooks, you can check them by this setting.
## Project settings
### Protected
Every build initiated by a user (not including the project owner) needs to be approved by the owner before being executed. This can be used if your repository is public to protect the pipeline configuration from running unauthorized changes on third-party pull requests.
### Trusted
If you set your project to trusted, a pipeline step and by this the underlying containers gets access to escalated capabilities like mounting volumes.
## Project visibility
You can change the visibility of your project by this setting. If a user has access to a project he can see all builds and their logs and artifacts. Settings, Secrets and Registries can only be accessed by owners.
- `Public` Every user can see your project without being logged in.
- `Private` Only authenticated users of the Woodpecker instance can see this project.
- `Internal` Only you and other owners of the repository can see this project.
## Timeout
After this timeout a pipeline has to finish or will be treated as timed out.

View file

@ -0,0 +1,18 @@
# Status Badges
Woodpecker has integrated support for repository status badges. These badges can be added to your website or project readme file to display the status of your code.
## Badge endpoint
```text
<scheme>://<hostname>/api/badges/<owner>/<repo>/status.svg
```
The status badge displays the status for the latest build to your default branch (e.g. master). You can customize the branch by adding the `branch` query parameter.
```diff
-<scheme>://<hostname>/api/badges/<owner>/<repo>/status.svg
+<scheme>://<hostname>/api/badges/<owner>/<repo>/status.svg?branch=<branch>
```
Please note status badges do not include pull request results, since the status of a pull request does not provide an accurate representation of your repository state.

View file

@ -0,0 +1,4 @@
label: 'Usage'
# position: 2
collapsible: true
collapsed: false

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

View file

Before

Width:  |  Height:  |  Size: 128 KiB

After

Width:  |  Height:  |  Size: 128 KiB

View file

@ -0,0 +1,160 @@
# Server Setup
## Installation
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start Woodpecker with a single agent.
It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below.
```yaml
# docker-compose.yml
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 8000:8000
volumes:
- woodpecker-server-data:/var/lib/drone/
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on:
- woodpecker-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
volumes:
woodpecker-server-data:
```
> Each agent is able to process one build by default.
>
> If you have 4 agents installed and connected to the Woodpecker server, your system will process 4 builds in parallel.
>
> You can add more agents to increase the number of parallel builds or set the agent's `WOODPECKER_MAX_PROCS=1` environment variable to increase the number of parallel builds for that agent.
Woodpecker needs to know its own address.
You must therefore provide the address in `<scheme>://<hostname>` format. Please omit trailing slashes.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
Agents require access to the host machine's Docker daemon.
```diff
services:
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on: [ woodpecker-server ]
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Agents require the server address for agent-to-server communication.
```diff
services:
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on: [ woodpecker-server ]
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
+ - WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
The server and agents use a shared secret to authenticate communication.
This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
+ - WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_DEBUG=true
+ - WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Authentication
Authentication is done using OAuth and is delegated to one of multiple version control providers, configured using environment variables. The example above demonstrates basic GitHub integration.
See the complete reference for [GitHub](/docs/administration/vcs/github), [Bitbucket Cloud](/docs/administration/vcs/bitbucket), [Bitbucket Server](/docs/administration/vcs/bitbucket_server) and [Gitlab](/docs/administration/vcs/gitlab).
## Database
Woodpecker mounts a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the sqlite database.
See the [database settings](/docs/administration/database) page to configure Postgresql or MySQL as database.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
+ volumes:
+ - woodpecker-server-data:/var/lib/drone/
restart: always
```
## SSL
Woodpecker supports ssl configuration by mounting certificates into your container. See the [SSL guide](/docs/administration/ssl).
Automated [Lets Encrypt](/docs/administration/lets-encrypt) is also supported.
## Metrics
A [Prometheus endpoint](/docs/administration/prometheus) is exposed.
## Behind a proxy
See the [proxy guide](/docs/administration/proxy) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
## Deploy to Kubernetes
See the [Kubernetes guide](/docs/administration/kubernetes) if you want to deploy Woodpecker to your Kubernetes cluster.

View file

@ -0,0 +1,90 @@
# Server configuration
## User registration
Registration is closed by default.
This example enables open registration for users that are members of approved GitHub organizations.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
+ - WOODPECKER_OPEN=true
+ - WOODPECKER_ORGS=dolores,dogpatch
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Administrators
Administrators should also be enumerated in your configuration.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_ORGS=dolores,dogpatch
+ - WOODPECKER_ADMIN=johnsmith,janedoe
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Filtering repositories
Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of GitHub, you may end up syncing more repos into Woodpecker than preferred.
Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_ORGS=dolores,dogpatch
+ - WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Global registry setting
If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration.
Point it to your server's docker config.
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
volumes:
- woodpecker-server-data:/var/lib/drone/
restart: always
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
+ - WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json
```

View file

@ -0,0 +1,13 @@
# Overview
## Supported features
| Feature | [GitHub](github/) | [Gitea](gitea/) | [Gitlab](gitlab/) | [Bitbucket](bitbucket/) | [Bitbucket Server](bitbucket_server/) | Gogs | Coding | Gerrit |
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| Event: Push | :white_check_mark: | :white_check_mark: |
| Event: Tag | :white_check_mark: | :white_check_mark: |
| Event: Pull-Request | :white_check_mark: | :white_check_mark: |
| Event: Deploy | :white_check_mark: | :white_check_mark: |
| OAuth | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [Multi pipeline](/docs/usage/multi-pipeline) | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | :x: |
| [when-path filter](/docs/usage/pipeline-syntax#path) | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | :x: |

View file

@ -1,4 +1,4 @@
# Github
# GitHub
Woodpecker comes with built-in support for GitHub and GitHub Enterprise. To enable GitHub you should configure the Woodpecker container using the following environment variables:
@ -15,12 +15,12 @@ services:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
+ - DRONE_GITHUB=true
+ - DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
+ - DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
+ - WOODPECKER_GITHUB=true
+ - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
+ - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
@ -30,8 +30,8 @@ services:
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=woodpecker-server:9000
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Registration
@ -46,35 +46,35 @@ Please use this screenshot for reference:
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_GITHUB=true
WOODPECKER_GITHUB=true
: Set to true to enable the GitHub driver.
DRONE_GITHUB_URL=`https://github.com`
WOODPECKER_GITHUB_URL=`https://github.com`
: GitHub server address.
DRONE_GITHUB_CLIENT
: Github oauth2 client id.
WOODPECKER_GITHUB_CLIENT
: GitHub oauth2 client id.
DRONE_GITHUB_SECRET
: Github oauth2 client secret.
WOODPECKER_GITHUB_SECRET
: GitHub oauth2 client secret.
DRONE_GITHUB_SCOPE=repo,repo:status,user:email,read:org
: Comma-separated Github oauth scope.
WOODPECKER_GITHUB_SCOPE=repo,repo:status,user:email,read:org
: Comma-separated GitHub oauth scope.
DRONE_GITHUB_GIT_USERNAME
WOODPECKER_GITHUB_GIT_USERNAME
: Optional. Use a single machine account username to clone all repositories.
DRONE_GITHUB_GIT_PASSWORD
WOODPECKER_GITHUB_GIT_PASSWORD
: Optional. Use a single machine account password to clone all repositories.
DRONE_GITHUB_PRIVATE_MODE=false
: Set to true if Github is running in private mode.
WOODPECKER_GITHUB_PRIVATE_MODE=false
: Set to true if GitHub is running in private mode.
DRONE_GITHUB_MERGE_REF=true
WOODPECKER_GITHUB_MERGE_REF=true
: Set to true to use the `refs/pulls/%d/merge` vs `refs/pulls/%d/head`
DRONE_GITHUB_CONTEXT=continuous-integration/drone
WOODPECKER_GITHUB_CONTEXT=continuous-integration/drone
: Customize the GitHub status message context
DRONE_GITHUB_SKIP_VERIFY=false
WOODPECKER_GITHUB_SKIP_VERIFY=false
: Set to true to disable SSL verification.

View file

@ -0,0 +1,71 @@
# Gitea
Woodpecker comes with built-in support for Gitea. To enable Gitea you should configure the Woodpecker container using the following environment variables:
```diff
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
+ - WOODPECKER_GITEA=true
+ - WOODPECKER_GITEA_URL=${WOODPECKER_GITEA_URL}
+ - WOODPECKER_GITEA_CLIENT=${WOODPECKER_GITEA_CLIENT}
+ - WOODPECKER_GITEA_SECRET=${WOODPECKER_GITEA_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
restart: always
depends_on:
- woodpecker-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Registration
TODO
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
WOODPECKER_GITEA=true
: Set to true to enable the Gitea driver.
WOODPECKER_GITEA_URL=`https://try.gitea.io`
: Gitea server address.
WOODPECKER_GITEA_CLIENT
: Gitea oauth2 client id.
WOODPECKER_GITEA_SECRET
: Gitea oauth2 client secret.
WOODPECKER_GITEA_CONTEXT=continuous-integration/drone
: Customize the Gitea status message context
WOODPECKER_GITEA_GIT_USERNAME
: Optional. Use a single machine account username to clone all repositories.
WOODPECKER_GITEA_GIT_PASSWORD
: Optional. Use a single machine account password to clone all repositories.
WOODPECKER_GITEA_PRIVATE_MODE=true
: Set to true if Gitea is running in private mode.
WOODPECKER_GITEA_SKIP_VERIFY=false
: Set to true to disable SSL verification.

View file

@ -15,11 +15,11 @@ services:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
+ - DRONE_GITLAB=true
+ - DRONE_GITLAB_CLIENT=95c0282573633eb25e82
+ - DRONE_GITLAB_SECRET=30f5064039e6b359e075
+ - DRONE_GITLAB_URL=http://gitlab.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
+ - WOODPECKER_GITLAB=true
+ - WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82
+ - WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075
+ - WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
@ -29,36 +29,36 @@ services:
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=woodpecker-server:9000
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_GITLAB=true
WOODPECKER_GITLAB=true
: Set to true to enable the GitLab driver.
DRONE_GITLAB_URL=`https://gitlab.com`
WOODPECKER_GITLAB_URL=`https://gitlab.com`
: GitLab Server address.
DRONE_GITLAB_CLIENT
WOODPECKER_GITLAB_CLIENT
: GitLab oauth2 client id.
DRONE_GITLAB_SECRET
WOODPECKER_GITLAB_SECRET
: GitLab oauth2 client secret.
DRONE_GITLAB_GIT_USERNAME
WOODPECKER_GITLAB_GIT_USERNAME
: Optional. Use a single machine account username to clone all repositories.
DRONE_GITLAB_GIT_PASSWORD
WOODPECKER_GITLAB_GIT_PASSWORD
: Optional. Use a single machine account password to clone all repositories.
DRONE_GITLAB_SKIP_VERIFY=false
WOODPECKER_GITLAB_SKIP_VERIFY=false
: Set to true to disable SSL verification.
DRONE_GITLAB_PRIVATE_MODE=false
WOODPECKER_GITLAB_PRIVATE_MODE=false
: Set to true if GitLab is running in private mode.
## Registration

View file

@ -15,12 +15,12 @@ services:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
+ - DRONE_BITBUCKET=true
+ - DRONE_BITBUCKET_CLIENT=95c0282573633eb25e82
+ - DRONE_BITBUCKET_SECRET=30f5064039e6b359e075
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
+ - WOODPECKER_BITBUCKET=true
+ - WOODPECKER_BITBUCKET_CLIENT=95c0282573633eb25e82
+ - WOODPECKER_BITBUCKET_SECRET=30f5064039e6b359e075
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
@ -30,21 +30,21 @@ services:
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=woodpecker-server:9000
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_BITBUCKET=true
WOODPECKER_BITBUCKET=true
: Set to true to enable the Bitbucket driver.
DRONE_BITBUCKET_CLIENT
WOODPECKER_BITBUCKET_CLIENT
: Bitbucket oauth2 client id
DRONE_BITBUCKET_SECRET
WOODPECKER_BITBUCKET_SECRET
: Bitbucket oauth2 client secret
## Registration
@ -54,7 +54,7 @@ You must register your application with Bitbucket in order to generate a client
Please use the Authorization callback URL:
```nohighlight
http://drone.mycompany.com/authorize
http://woodpecker.mycompany.com/authorize
```
Please also be sure to check the following permissions:
@ -69,4 +69,4 @@ Webhooks:Read and Write
## Missing Features
Merge requests are not currently supported. We are interested in patches to include this functionality. If you are interested in contributing to Woodpecker and submitting a patch please [contact us](https://discourse.drone.io).
Merge requests are not currently supported. We are interested in patches to include this functionality. If you are interested in contributing to Woodpecker and submitting a patch please [contact us](https://discord.gg/fcMQqSMXJy).

View file

@ -15,15 +15,15 @@ services:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
+ - DRONE_STASH=true
+ - DRONE_STASH_GIT_USERNAME=foo
+ - DRONE_STASH_GIT_PASSWORD=bar
+ - DRONE_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - DRONE_STASH_CONSUMER_RSA=/etc/bitbucket/key.pem
+ - DRONE_STASH_URL=http://stash.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
+ - WOODPECKER_STASH=true
+ - WOODPECKER_STASH_GIT_USERNAME=foo
+ - WOODPECKER_STASH_GIT_PASSWORD=bar
+ - WOODPECKER_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - WOODPECKER_STASH_CONSUMER_RSA=/etc/bitbucket/key.pem
+ - WOODPECKER_STASH_URL=http://stash.mycompany.com
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
volumes:
+ - /path/to/key.pem:/path/to/key.pem
@ -35,8 +35,8 @@ services:
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DRONE_SERVER=woodpecker-server:9000
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Private Key File
@ -64,15 +64,15 @@ services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_STASH=true
- DRONE_STASH_GIT_USERNAME=foo
- DRONE_STASH_GIT_PASSWORD=bar
- DRONE_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - DRONE_STASH_CONSUMER_RSA=/etc/bitbucket/key.pem
- DRONE_STASH_URL=http://stash.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_STASH=true
- WOODPECKER_STASH_GIT_USERNAME=foo
- WOODPECKER_STASH_GIT_PASSWORD=bar
- WOODPECKER_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - WOODPECKER_STASH_CONSUMER_RSA=/etc/bitbucket/key.pem
- WOODPECKER_STASH_URL=http://stash.mycompany.com
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
+ volumes:
+ - /etc/bitbucket/key.pem:/etc/bitbucket/key.pem
```
@ -86,15 +86,15 @@ services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_STASH=true
- DRONE_STASH_GIT_USERNAME=foo
- DRONE_STASH_GIT_PASSWORD=bar
- DRONE_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - DRONE_STASH_CONSUMER_RSA_STRING=contentOfPemKeyAsString
- DRONE_STASH_URL=http://stash.mycompany.com
- DRONE_SECRET=${DRONE_SECRET}
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_STASH=true
- WOODPECKER_STASH_GIT_USERNAME=foo
- WOODPECKER_STASH_GIT_PASSWORD=bar
- WOODPECKER_STASH_CONSUMER_KEY=95c0282573633eb25e82
+ - WOODPECKER_STASH_CONSUMER_RSA_STRING=contentOfPemKeyAsString
- WOODPECKER_STASH_URL=http://stash.mycompany.com
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Service Account
@ -105,7 +105,7 @@ Woodpecker uses `git+https` to clone repositories, however, Bitbucket Server doe
You must register your application with Bitbucket Server in order to generate a consumer key. Navigate to your account settings and choose Applications from the menu, and click Register new application. Now copy & paste the text value from `/etc/bitbucket/key.pub` into the `Public Key` in the incoming link part of the application registration.
Please use http://drone.mycompany.com/authorize as the Authorization callback URL.
Please use http://woodpecker.mycompany.com/authorize as the Authorization callback URL.
## Configuration
@ -113,23 +113,23 @@ Please use http://drone.mycompany.com/authorize as the Authorization callback UR
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
DRONE_STASH=true
WOODPECKER_STASH=true
: Set to true to enable the Bitbucket Server (Stash) driver.
DRONE_STASH_URL
WOODPECKER_STASH_URL
: Bitbucket Server address.
DRONE_STASH_CONSUMER_KEY
WOODPECKER_STASH_CONSUMER_KEY
: Bitbucket Server oauth1 consumer key
DRONE_STASH_CONSUMER_RSA
WOODPECKER_STASH_CONSUMER_RSA
: Bitbucket Server oauth1 private key file
DRONE_STASH_CONSUMER_RSA_STRING
WOODPECKER_STASH_CONSUMER_RSA_STRING
: Bibucket Server oauth1 private key as a string
DRONE_STASH_GIT_USERNAME
WOODPECKER_STASH_GIT_USERNAME
: Machine account username used to clone repositories.
DRONE_STASH_GIT_PASSWORD
WOODPECKER_STASH_GIT_PASSWORD
: Machine account password used to clone repositories.

View file

@ -0,0 +1,3 @@
label: 'Version control systems'
collapsible: true
collapsed: true

View file

Before

Width:  |  Height:  |  Size: 154 KiB

After

Width:  |  Height:  |  Size: 154 KiB

View file

@ -13,8 +13,8 @@ services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
+ DRONE_DATABASE_DRIVER: mysql
+ DRONE_DATABASE_DATASOURCE: root:password@tcp(1.2.3.4:3306)/drone?parseTime=true
+ WOODPECKER_DATABASE_DRIVER: mysql
+ WOODPECKER_DATABASE_DATASOURCE: root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
```
## Configure Postgres
@ -28,8 +28,8 @@ services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
+ DRONE_DATABASE_DRIVER: postgres
+ DRONE_DATABASE_DATASOURCE: postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
+ WOODPECKER_DATABASE_DRIVER: postgres
+ WOODPECKER_DATABASE_DATASOURCE: postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
```
## Database Creation

View file

@ -16,16 +16,16 @@ services:
- /var/lib/drone:/var/lib/drone/
restart: always
environment:
- DRONE_OPEN=true
- DRONE_HOST=${DRONE_HOST}
- DRONE_GITHUB=true
- DRONE_GITHUB_CLIENT=${DRONE_GITHUB_CLIENT}
- DRONE_GITHUB_SECRET=${DRONE_GITHUB_SECRET}
- DRONE_SECRET=${DRONE_SECRET}
+ - DRONE_LETS_ENCRYPT=true
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
+ - WOODPECKER_LETS_ENCRYPT=true
```
Note that Woodpecker uses the hostname from the `DRONE_HOST` environment variable when requesting certificates. For example, if `DRONE_HOST=https://foo.com` the certificate is requested for `foo.com`.
Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://foo.com` the certificate is requested for `foo.com`.
>Once enabled you can visit your website at both the http and the https address

View file

@ -16,8 +16,8 @@ services:
+ - /etc/certs/woodpecker.foo.com/server.key:/etc/certs/woodpecker.foo.com/server.key
restart: always
environment:
+ - DRONE_SERVER_CERT=/etc/certs/woodpecker.foo.com/server.crt
+ - DRONE_SERVER_KEY=/etc/certs/woodpecker.foo.com/server.key
+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.foo.com/server.crt
+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.foo.com/server.key
```
Update your configuration to expose the following ports:
@ -64,8 +64,8 @@ services:
- /etc/certs/woodpecker.foo.com/server.key:/etc/certs/woodpecker.foo.com/server.key
restart: always
environment:
+ - DRONE_SERVER_CERT=/etc/certs/woodpecker.foo.com/server.crt
+ - DRONE_SERVER_KEY=/etc/certs/woodpecker.foo.com/server.key
+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.foo.com/server.crt
+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.foo.com/server.key
```
## Certificate Chain

View file

@ -1,3 +1,5 @@
# Proxy
## Apache
This guide provides a brief overview for installing Woodpecker server behind the Apache2 webserver. This is an example configuration:
@ -139,4 +141,4 @@ After installing [ngrok](https://ngrok.com/), open a new console and run:
ngrok http 80
```
Set `DRONE_HOST` (for example in `docker-compose.yml`) to the ngrok url (usually xxx.ngrok.io) and start the server.
Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the ngrok url (usually xxx.ngrok.io) and start the server.

View file

@ -0,0 +1,175 @@
# Kubernetes
Woodpecker does not support Kubernetes natively, but being a container first CI engine, it can be deployed to Kubernetes.
## Deploy with HELM
TODO
## Deploy with kubectl
The following yamls represent a server (backed by sqlite and Persistent Volumes) and an agent deployment. The agents can be scaled by the `replica` field.
By design, Woodpecker spins up a new container for each workflow step. It talks to the Docker agent to do that.
However in Kubernetes, the Docker agent is not accessible, therefore this deployment follows a Docker in Docker setup and we deploy a DinD sidecar with the agent.
Build step containers are started up within the agent pod.
Warning: this approach requires `privileged` access. Also DinD's reputation hasn't been too high in the early days of Docker - this changed somewhat over time, and there are organizations succeeding with this approach.
server.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: woodpecker
namespace: tools
labels:
app: woodpecker
spec:
replicas: 1
selector:
matchLabels:
app: woodpecker
template:
metadata:
labels:
app: woodpecker
annotations:
prometheus.io/scrape: 'true'
spec:
containers:
- image: woodpeckerci/woodpecker-server:latest
imagePullPolicy: Always
name: woodpecker
env:
- name: "WOODPECKER_ADMIN"
value: "xxx"
- name: "WOODPECKER_HOST"
value: "https://xxx"
- name: "WOODPECKER_GITHUB"
value: "true"
- name: "WOODPECKER_GITHUB_CLIENT"
value: "xxx"
- name: "WOODPECKER_GITHUB_SECRET"
value: "xxx"
- name: "WOODPECKER_SECRET"
value: "xxx"
volumeMounts:
- name: sqlite-volume
mountPath: /var/lib/drone
volumes:
- name: sqlite-volume
persistentVolumeClaim:
claimName: woodpecker-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: woodpecker-pvc
namespace: tools
spec:
accessModes:
- ReadWriteOnce
storageClassName: local-path
resources:
requests:
storage: 10Gi
---
kind: Service
apiVersion: v1
metadata:
name: woodpecker
namespace: tools
spec:
type: ClusterIP
selector:
app: woodpecker
ports:
- protocol: TCP
name: http
port: 80
targetPort: 8000
- protocol: TCP
name: grpc
port: 9000
targetPort: 9000
---
kind: Ingress
apiVersion: extensions/v1beta1
metadata:
name: woodpecker
namespace: tools
spec:
tls:
- hosts:
- xxx
secretName: xxx
rules:
- host: xxx
http:
paths:
- backend:
serviceName: woodpecker
servicePort: 80
```
agent.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: woodpecker-agent
namespace: tools
labels:
app: woodpecker-agent
spec:
selector:
matchLabels:
app: woodpecker-agent
replicas: 2
template:
metadata:
annotations:
labels:
app: woodpecker-agent
spec:
containers:
- name: agent
image: woodpeckerci/woodpecker-agent:latest
imagePullPolicy: Always
ports:
- name: http
containerPort: 3000
protocol: TCP
env:
- name: WOODPECKER_SERVER
value: woodpecker.tools.svc.cluster.local:9000
- name: WOODPECKER_SECRET
value: "xxx"
resources:
limits:
cpu: 2
memory: 2Gi
volumeMounts:
- name: sock-dir
path: /var/run
- name: dind
image: "docker:19.03.5-dind"
env:
- name: DOCKER_DRIVER
value: overlay2
resources:
limits:
cpu: 1
memory: 2Gi
securityContext:
privileged: true
volumeMounts:
- name: sock-dir
mountPath: /var/run
volumes:
- name: sock-dir
emptyDir: {}
```

View file

@ -0,0 +1,4 @@
label: 'Administration'
# position: 3
collapsible: true
collapsed: false

3
docs/docs/40-cli.md Normal file
View file

@ -0,0 +1,3 @@
# CLI
TODO

24
docs/docs/80-downloads.md Normal file
View file

@ -0,0 +1,24 @@
# Downloads
## Executables
[Latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
## Docker images
``` bash
# server
docker pull woodpecker-ci/woodpecker-server:latest
docker pull woodpecker-ci/woodpecker-server:latest-alpine
# agent
docker pull woodpecker-ci/woodpecker-agent:latest
docker pull woodpecker-ci/woodpecker-agent:latest-alpine
# cli
docker pull woodpecker-ci/woodpecker-cli:latest
docker pull woodpecker-ci/woodpecker-cli:latest-alpine
```
## APK, DEB, RPM
TODO

11
docs/docs/90-faq.md Normal file
View file

@ -0,0 +1,11 @@
# FAQ
## What are the differences to Drone?
Apart from Woodpecker staying free and OpenSource forever, the growing community already introduced some nifty features like:
- [Multi pipelines](/docs/usage/multi-pipeline)
- [Conditional step execution on file changes](/docs/usage/pipeline-syntax#path)
- [More features are already in the pipeline :wink:](https://github.com/woodpecker-ci/woodpecker/pulls) ...
## Why is Woodpecker a fork of Drone version 0.8?
The Drone CI license was changed after the 0.8 release from Apache 2 to a proprietary license. Woodpecker is based on this lastest freely available version.

View file

@ -0,0 +1,16 @@
# Migrations
Some versions need some changes to the server configuration or the pipeline configuration files.
## 0.15.0
- Default pipeline path changed to `.woodpecker/`
**Solution:** Set configuration location via [project settings](/docs/usage/project-settings#pipeline-path).
There is still a default fallback mechanism in following order: `.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml`
- ...
## 0.14.0
No breaking changes

View file

@ -1,116 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
viewBox="0 0 22.453405 50.000439"
preserveAspectRatio="xMidYMid meet"
version="1.1"
id="svg45"
sodipodi:docname="logo.svg"
width="22.453405"
height="50.000439"
inkscape:version="0.92.4 (5da689c313, 2019-01-14)">
<metadata
id="metadata51">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title />
</cc:Work>
</rdf:RDF>
</metadata>
<defs
id="defs49">
<linearGradient
inkscape:collect="always"
id="linearGradient5953">
<stop
style="stop-color:#000000;stop-opacity:1;"
offset="0"
id="stop5949" />
<stop
style="stop-color:#000000;stop-opacity:0;"
offset="1"
id="stop5951" />
</linearGradient>
<radialGradient
inkscape:collect="always"
xlink:href="#linearGradient5953"
id="radialGradient5957"
cx="8.2885551"
cy="24.835812"
fx="8.2885551"
fy="24.835812"
r="6.5211034"
gradientTransform="matrix(1,0,0,3.3690306,0,-58.836801)"
gradientUnits="userSpaceOnUse" />
</defs>
<sodipodi:namedview
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1"
objecttolerance="10"
gridtolerance="10"
guidetolerance="10"
inkscape:pageopacity="0"
inkscape:pageshadow="2"
inkscape:window-width="3840"
inkscape:window-height="2032"
id="namedview47"
showgrid="false"
inkscape:zoom="28.768"
inkscape:cx="-4.6954753"
inkscape:cy="29.45752"
inkscape:window-x="0"
inkscape:window-y="54"
inkscape:window-maximized="1"
inkscape:current-layer="g43"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0" />
<g
id="g43"
transform="translate(-13.01027,-34.240175)">
<path
fillRule="evenodd"
clipRule="evenodd"
d="m 15.10726,34.707434 c 1.148,1.088 1.582,2.188 2.855,2.337 l 0.036,0.007 c -0.588,0.606 -1.089,1.402 -1.443,2.423 -0.379,1.096 -0.488,2.285 -0.614,3.659 -0.189,2.046 -0.401,4.364001 -1.556,7.269001 -2.486,6.258 -1.119,11.631 0.332,17.317 0.664,2.604 1.348,5.297 1.642,8.107 0.035,0.355 0.287,0.652 0.633,0.744 0.346,0.095 0.709,-0.035 0.922,-0.323 0.227,-0.313 0.524,-0.797 0.86,-1.424 0.84,3.323 1.355,6.131 1.783,8.697 0.126,0.73 1.048,0.973 1.517,0.41 2.881,-3.463 3.763,-8.636 2.184,-12.674 0.459,-2.433 1.402,-4.45 2.398,-6.583 0.536,-1.15 1.08,-2.318 1.55,-3.566 0.228,-0.084 0.569,-0.314 0.791,-0.441 l 1.706,-0.981 -0.256,1.052 c -0.112,0.461 0.171,0.929 0.635,1.04 0.457,0.118 0.93,-0.173 1.043,-0.632 l 0.68,-2.858 1.285,-2.95 c 0.19,-0.436 -0.009,-0.943 -0.446,-1.135 -0.44,-0.189 -0.947,0.01 -1.135,0.448 l -1.152,2.669 -2.383,1.372 c 0.235,-0.932 0.414,-1.919 0.508,-2.981 0.432,-4.859 -0.718,-9.074 -3.066,-11.266001 -0.163,-0.157 -0.208,-0.281 -0.247,-0.26 0.095,-0.119 0.249,-0.26 0.358,-0.374 2.283,-1.693 6.047,-0.147 8.319,0.751 0.589,0.231 0.876,-0.338 0.316,-0.67 -1.949,-1.154 -5.948,-4.197 -8.188,-6.194 -0.313,-0.275 -0.527,-0.607 -0.89,-0.913 -2.415,-4.266 -8.168,-1.764 -10.885,-2.252 -0.102,-0.018 -0.166,0.103 -0.092,0.175 m 10.98,5.899 c -0.059,1.242 -0.603,1.8 -0.999,2.208 -0.218,0.224 -0.427,0.436 -0.525,0.738 -0.236,0.714 0.008,1.51 0.66,2.143 1.974,1.840001 2.925,5.527001 2.538,9.861001 -0.291,3.287 -1.448,5.762 -2.671,8.384 -1.031,2.207 -2.096,4.489 -2.577,7.259 -0.027,0.161 -0.01,0.33 0.056,0.481 1.021,2.433 1.135,6.196 -0.672,9.46 -0.461,-2.553 -1.053,-5.385 -1.97,-8.712 1.964,-4.488 4.203,-11.75 2.919,-17.668 -0.325,-1.497 -1.304,-3.276 -2.387,-4.207 -0.208,-0.179 -0.402,-0.237 -0.495,-0.167 -0.084,0.061 -0.151,0.238 -0.062,0.444 0.55,1.266 0.879,2.599 1.226,4.276 1.125,5.443 -0.956,12.49 -2.835,16.782 l -0.116,0.259 -0.457,0.982 c -0.356,-2.014 -0.849,-3.95 -1.33,-5.839 -1.379,-5.407 -2.679,-10.516 -0.401,-16.255 1.247,-3.137 1.483,-5.692001 1.672,-7.746001 0.116,-1.263 0.216,-2.355 0.526,-3.252 0.905,-2.605 3.062,-3.178 4.744,-2.852 1.632,0.316 3.24,1.593 3.156,3.421 z m -2.868,0.621 c 0.617,0.204 1.283,-0.131 1.487,-0.75 0.202,-0.617 -0.134,-1.283 -0.751,-1.487 -0.618,-0.204 -1.285,0.134 -1.487,0.751 -0.204,0.618 0.133,1.284 0.751,1.486 z"
id="path41"
inkscape:connector-curvature="0"
style="fill-opacity:0.80505413;fill:#000000" />
<path
style="fill:none;fill-opacity:0.45487366;stroke-width:0.03476084"
d="m 8.8842581,46.780405 c -0.00984,-0.02868 -0.043593,-0.200744 -0.07501,-0.38237 C 8.4763396,44.473449 7.7181134,41.102144 7.1052676,38.821624 6.9172743,38.122066 6.9016277,38.264623 7.2593269,37.417928 8.0964501,35.436405 8.9270313,32.875565 9.4145271,30.773035 9.9595591,28.422357 10.217352,26.34615 10.216584,24.313443 10.215805,22.251865 9.9744538,20.591945 9.498671,19.375911 9.0317793,18.1826 8.2453903,16.986888 7.5080846,16.349203 7.2367529,16.114532 7.075992,16.057499 6.9494079,16.151001 c -0.1421016,0.104964 -0.1340253,0.292719 0.029806,0.692922 0.5587528,1.364905 1.1597396,3.812745 1.345981,5.482227 0.1196583,1.072627 0.1022399,2.945469 -0.04025,4.327725 -0.3165378,3.070644 -1.2552235,6.666418 -2.6225028,10.045885 -0.3049354,0.753701 -0.9032999,2.08565 -0.9369566,2.08565 -0.010457,0 -0.071712,-0.277652 -0.1361227,-0.617005 C 4.3814427,37.072962 4.0766926,35.764206 3.4055815,33.084632 2.3483469,28.863365 2.0696096,27.483313 1.8504628,25.385104 1.7724073,24.637766 1.7613535,22.252386 1.8329049,21.596172 2.020212,19.878339 2.3327524,18.561065 2.9256931,16.99036 3.4476314,15.607742 3.6667338,14.93025 3.9205869,13.914025 4.2747692,12.496163 4.4364363,11.439039 4.672405,8.9979684 4.8581198,7.0767681 4.9877272,6.3328495 5.2591921,5.6299378 5.7590756,4.3355744 6.6580043,3.4365659 7.8182844,3.0706178 c 1.8817993,-0.5935124 4.1273166,0.2744263 4.9488076,1.912816 0.216989,0.4327636 0.28057,0.726569 0.277694,1.2832057 -0.0021,0.4050386 -0.01731,0.5424868 -0.09075,0.8195898 -0.149766,0.5650768 -0.347811,0.8982425 -0.851308,1.4321305 -0.383946,0.4071208 -0.482686,0.5499718 -0.567933,0.8216553 -0.142224,0.4532665 -0.07886,1.0131629 0.165548,1.4629149 0.149896,0.275827 0.292306,0.454857 0.649791,0.81688 1.264032,1.280076 2.046753,3.233166 2.375194,5.926724 0.08934,0.732644 0.08886,3.068816 -7.92e-4,3.910595 -0.187862,1.763856 -0.575201,3.30088 -1.292091,5.127225 -0.317479,0.808808 -0.607504,1.468137 -1.330279,3.024193 -1.073206,2.310498 -1.480594,3.288763 -1.903564,4.571051 -0.3741818,1.13438 -0.7116474,2.525048 -0.7116474,2.932641 0,0.122527 0.042139,0.288666 0.1355513,0.534427 0.4394061,1.156048 0.6382171,2.302871 0.6403271,3.693666 0.0021,1.388675 -0.183399,2.532213 -0.6146444,3.788933 -0.2500385,0.728653 -0.7268454,1.759218 -0.7639255,1.65114 z M 11.103329,6.9363781 C 11.427791,6.7684832 11.640819,6.5015439 11.730501,6.1504868 11.875505,5.582877 11.547419,4.9637853 10.99024,4.7536271 c -0.280381,-0.1057549 -0.678638,-0.085279 -0.939614,0.04831 -0.9383249,0.4803108 -0.8622845,1.8158861 0.124492,2.1865664 0.246485,0.092591 0.697485,0.067265 0.928211,-0.052125 z"
id="path5941"
inkscape:connector-curvature="0"
transform="translate(13.01027,34.240175)" />
<path
style="fill:none;fill-opacity:0.45487366;stroke-width:0.03476084"
d="m 8.8842581,46.780405 c -0.00984,-0.02868 -0.043593,-0.200744 -0.07501,-0.38237 C 8.4763396,44.473449 7.7181134,41.102144 7.1052676,38.821624 6.9172743,38.122066 6.9016277,38.264623 7.2593269,37.417928 8.0964501,35.436405 8.9270313,32.875565 9.4145271,30.773035 9.9595591,28.422357 10.217352,26.34615 10.216584,24.313443 10.215805,22.251865 9.9744538,20.591945 9.498671,19.375911 9.0317793,18.1826 8.2453903,16.986888 7.5080846,16.349203 7.2367529,16.114532 7.075992,16.057499 6.9494079,16.151001 c -0.1421016,0.104964 -0.1340253,0.292719 0.029806,0.692922 0.5587528,1.364905 1.1597396,3.812745 1.345981,5.482227 0.1196583,1.072627 0.1022399,2.945469 -0.04025,4.327725 -0.3165378,3.070644 -1.2552235,6.666418 -2.6225028,10.045885 -0.3049354,0.753701 -0.9032999,2.08565 -0.9369566,2.08565 -0.010457,0 -0.071712,-0.277652 -0.1361227,-0.617005 C 4.3814427,37.072962 4.0766926,35.764206 3.4055815,33.084632 2.3483469,28.863365 2.0696096,27.483313 1.8504628,25.385104 1.7724073,24.637766 1.7613535,22.252386 1.8329049,21.596172 2.020212,19.878339 2.3327524,18.561065 2.9256931,16.99036 3.4476314,15.607742 3.6667338,14.93025 3.9205869,13.914025 4.2747692,12.496163 4.4364363,11.439039 4.672405,8.9979684 4.8581198,7.0767681 4.9877272,6.3328495 5.2591921,5.6299378 5.7590756,4.3355744 6.6580043,3.4365659 7.8182844,3.0706178 c 1.8817993,-0.5935124 4.1273166,0.2744263 4.9488076,1.912816 0.216989,0.4327636 0.28057,0.726569 0.277694,1.2832057 -0.0021,0.4050386 -0.01731,0.5424868 -0.09075,0.8195898 -0.149766,0.5650768 -0.347811,0.8982425 -0.851308,1.4321305 -0.383946,0.4071208 -0.482686,0.5499718 -0.567933,0.8216553 -0.142224,0.4532665 -0.07886,1.0131629 0.165548,1.4629149 0.149896,0.275827 0.292306,0.454857 0.649791,0.81688 1.264032,1.280076 2.046753,3.233166 2.375194,5.926724 0.08934,0.732644 0.08886,3.068816 -7.92e-4,3.910595 -0.187862,1.763856 -0.575201,3.30088 -1.292091,5.127225 -0.317479,0.808808 -0.607504,1.468137 -1.330279,3.024193 -1.073206,2.310498 -1.480594,3.288763 -1.903564,4.571051 -0.3741818,1.13438 -0.7116474,2.525048 -0.7116474,2.932641 0,0.122527 0.042139,0.288666 0.1355513,0.534427 0.4394061,1.156048 0.6382171,2.302871 0.6403271,3.693666 0.0021,1.388675 -0.183399,2.532213 -0.6146444,3.788933 -0.2500385,0.728653 -0.7268454,1.759218 -0.7639255,1.65114 z M 11.103329,6.9363781 C 11.427791,6.7684832 11.640819,6.5015439 11.730501,6.1504868 11.875505,5.582877 11.547419,4.9637853 10.99024,4.7536271 c -0.280381,-0.1057549 -0.678638,-0.085279 -0.939614,0.04831 -0.9383249,0.4803108 -0.8622845,1.8158861 0.124492,2.1865664 0.246485,0.092591 0.697485,0.067265 0.928211,-0.052125 z"
id="path5943"
inkscape:connector-curvature="0"
transform="translate(13.01027,34.240175)" />
<path
style="fill:none;fill-opacity:0.45487366;stroke-width:0.03476084"
d="m 8.8842581,46.780405 c -0.00984,-0.02868 -0.043593,-0.200744 -0.07501,-0.38237 C 8.4763396,44.473449 7.7181134,41.102144 7.1052676,38.821624 6.9172743,38.122066 6.9016277,38.264623 7.2593269,37.417928 8.0964501,35.436405 8.9270313,32.875565 9.4145271,30.773035 9.9595591,28.422357 10.217352,26.34615 10.216584,24.313443 10.215805,22.251865 9.9744538,20.591945 9.498671,19.375911 9.0317793,18.1826 8.2453903,16.986888 7.5080846,16.349203 7.2367529,16.114532 7.075992,16.057499 6.9494079,16.151001 c -0.1421016,0.104964 -0.1340253,0.292719 0.029806,0.692922 0.5587528,1.364905 1.1597396,3.812745 1.345981,5.482227 0.1196583,1.072627 0.1022399,2.945469 -0.04025,4.327725 -0.3165378,3.070644 -1.2552235,6.666418 -2.6225028,10.045885 -0.3049354,0.753701 -0.9032999,2.08565 -0.9369566,2.08565 -0.010457,0 -0.071712,-0.277652 -0.1361227,-0.617005 C 4.3814427,37.072962 4.0766926,35.764206 3.4055815,33.084632 2.3483469,28.863365 2.0696096,27.483313 1.8504628,25.385104 1.7724073,24.637766 1.7613535,22.252386 1.8329049,21.596172 2.020212,19.878339 2.3327524,18.561065 2.9256931,16.99036 3.4476314,15.607742 3.6667338,14.93025 3.9205869,13.914025 4.2747692,12.496163 4.4364363,11.439039 4.672405,8.9979684 4.8581198,7.0767681 4.9877272,6.3328495 5.2591921,5.6299378 5.7590756,4.3355744 6.6580043,3.4365659 7.8182844,3.0706178 c 1.8817993,-0.5935124 4.1273166,0.2744263 4.9488076,1.912816 0.216989,0.4327636 0.28057,0.726569 0.277694,1.2832057 -0.0021,0.4050386 -0.01731,0.5424868 -0.09075,0.8195898 -0.149766,0.5650768 -0.347811,0.8982425 -0.851308,1.4321305 -0.383946,0.4071208 -0.482686,0.5499718 -0.567933,0.8216553 -0.142224,0.4532665 -0.07886,1.0131629 0.165548,1.4629149 0.149896,0.275827 0.292306,0.454857 0.649791,0.81688 1.264032,1.280076 2.046753,3.233166 2.375194,5.926724 0.08934,0.732644 0.08886,3.068816 -7.92e-4,3.910595 -0.187862,1.763856 -0.575201,3.30088 -1.292091,5.127225 -0.317479,0.808808 -0.607504,1.468137 -1.330279,3.024193 -1.073206,2.310498 -1.480594,3.288763 -1.903564,4.571051 -0.3741818,1.13438 -0.7116474,2.525048 -0.7116474,2.932641 0,0.122527 0.042139,0.288666 0.1355513,0.534427 0.4394061,1.156048 0.6382171,2.302871 0.6403271,3.693666 0.0021,1.388675 -0.183399,2.532213 -0.6146444,3.788933 -0.2500385,0.728653 -0.7268454,1.759218 -0.7639255,1.65114 z M 11.103329,6.9363781 C 11.427791,6.7684832 11.640819,6.5015439 11.730501,6.1504868 11.875505,5.582877 11.547419,4.9637853 10.99024,4.7536271 c -0.280381,-0.1057549 -0.678638,-0.085279 -0.939614,0.04831 -0.9383249,0.4803108 -0.8622845,1.8158861 0.124492,2.1865664 0.246485,0.092591 0.697485,0.067265 0.928211,-0.052125 z"
id="path5945"
inkscape:connector-curvature="0"
transform="translate(13.01027,34.240175)" />
<path
style="fill:#a7ac93;fill-opacity:0.97111911;stroke-width:0.03476084;stroke:url(#radialGradient5957)"
d="m 8.8842581,46.780405 c -0.00984,-0.02868 -0.043593,-0.200744 -0.07501,-0.38237 C 8.4763396,44.473449 7.7181134,41.102144 7.1052676,38.821624 6.9172743,38.122066 6.9016277,38.264623 7.2593269,37.417928 8.0964501,35.436405 8.9270313,32.875565 9.4145271,30.773035 9.9595591,28.422357 10.217352,26.34615 10.216584,24.313443 10.215805,22.251865 9.9744538,20.591945 9.498671,19.375911 9.0317793,18.1826 8.2453903,16.986888 7.5080846,16.349203 7.2367529,16.114532 7.075992,16.057499 6.9494079,16.151001 c -0.1421016,0.104964 -0.1340253,0.292719 0.029806,0.692922 0.5587528,1.364905 1.1597396,3.812745 1.345981,5.482227 0.1196583,1.072627 0.1022399,2.945469 -0.04025,4.327725 -0.3165378,3.070644 -1.2552235,6.666418 -2.6225028,10.045885 -0.3049354,0.753701 -0.9032999,2.08565 -0.9369566,2.08565 -0.010457,0 -0.071712,-0.277652 -0.1361227,-0.617005 C 4.3814427,37.072962 4.0766926,35.764206 3.4055815,33.084632 2.3483469,28.863365 2.0696096,27.483313 1.8504628,25.385104 1.7724073,24.637766 1.7613535,22.252386 1.8329049,21.596172 2.020212,19.878339 2.3327524,18.561065 2.9256931,16.99036 3.4476314,15.607742 3.6667338,14.93025 3.9205869,13.914025 4.2747692,12.496163 4.4364363,11.439039 4.672405,8.9979684 4.8581198,7.0767681 4.9877272,6.3328495 5.2591921,5.6299378 5.7590756,4.3355744 6.6580043,3.4365659 7.8182844,3.0706178 c 1.8817993,-0.5935124 4.1273166,0.2744263 4.9488076,1.912816 0.216989,0.4327636 0.28057,0.726569 0.277694,1.2832057 -0.0021,0.4050386 -0.01731,0.5424868 -0.09075,0.8195898 -0.149766,0.5650768 -0.347811,0.8982425 -0.851308,1.4321305 -0.383946,0.4071208 -0.482686,0.5499718 -0.567933,0.8216553 -0.142224,0.4532665 -0.07886,1.0131629 0.165548,1.4629149 0.149896,0.275827 0.292306,0.454857 0.649791,0.81688 1.264032,1.280076 2.046753,3.233166 2.375194,5.926724 0.08934,0.732644 0.08886,3.068816 -7.92e-4,3.910595 -0.187862,1.763856 -0.575201,3.30088 -1.292091,5.127225 -0.317479,0.808808 -0.607504,1.468137 -1.330279,3.024193 -1.073206,2.310498 -1.480594,3.288763 -1.903564,4.571051 -0.3741818,1.13438 -0.7116474,2.525048 -0.7116474,2.932641 0,0.122527 0.042139,0.288666 0.1355513,0.534427 0.4394061,1.156048 0.6382171,2.302871 0.6403271,3.693666 0.0021,1.388675 -0.183399,2.532213 -0.6146444,3.788933 -0.2500385,0.728653 -0.7268454,1.759218 -0.7639255,1.65114 z M 11.103329,6.9363781 C 11.427791,6.7684832 11.640819,6.5015439 11.730501,6.1504868 11.875505,5.582877 11.547419,4.9637853 10.99024,4.7536271 c -0.280381,-0.1057549 -0.678638,-0.085279 -0.939614,0.04831 -0.9383249,0.4803108 -0.8622845,1.8158861 0.124492,2.1865664 0.246485,0.092591 0.697485,0.067265 0.928211,-0.052125 z"
id="path5947"
inkscape:connector-curvature="0"
transform="translate(13.01027,34.240175)" />
</g>
</svg>

Before

Width:  |  Height:  |  Size: 16 KiB

View file

@ -1,382 +0,0 @@
## Installation
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start Woodpecker with a single agent.
It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below.
```yaml
# docker-compose.yml
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
volumes:
- woodpecker-server-data:/var/lib/drone/
restart: always
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on:
- woodpecker-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
volumes:
woodpecker-server-data:
```
> Each agent is able to process one build by default.
>
> If you have 4 agents installed and connected to the Drone server, your system will process 4 builds in parallel.
>
> You can add more agents to increase the number of parallel builds or set the agent's `WOODPECKER_MAX_PROCS=1` environment variable to increase the number of parallel builds for that agent.
Woodpecker needs to know its own address.
You must therefore provide the address in `<scheme>://<hostname>` format. Please omit trailing slashes.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
Agents require access to the host machine's Docker daemon.
```diff
services:
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on: [ woodpecker-server ]
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Agents require the server address for agent-to-server communication.
```diff
services:
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on: [ woodpecker-server ]
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
+ - WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
The server and agents use a shared secret to authenticate communication.
This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
+ - WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_DEBUG=true
+ - WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
Registration is closed by default.
This example enables open registration for users that are members of approved GitHub organizations.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
+ - WOODPECKER_OPEN=true
+ - WOODPECKER_ORGS=dolores,dogpatch
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
Administrators should also be enumerated in your configuration.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_ORGS=dolores,dogpatch
+ - WOODPECKER_ADMIN=johnsmith,janedoe
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Authentication
Authentication is done using OAuth and is delegated to one of multiple version control providers, configured using environment variables. The example above demonstrates basic GitHub integration.
See the complete reference for [Github](/administration/github), [Bitbucket Cloud](/administration/bitbucket), [Bitbucket Server](/administration/bitbucket_server) and [Gitlab](/administration/gitlab).
## Database
Woodpecker mounts a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the sqlite database.
See the [database settings](/administration/database) page to configure Postgresql or MySQL as database.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
+ volumes:
+ - woodpecker-server-data:/var/lib/drone/
restart: always
```
## SSL
Woodpecker supports ssl configuration by mounting certificates into your container. See the [SSL guide](/administration/ssl).
Automated [Lets Encrypt](/administration/lets-encrypt) is also supported.
## Metrics
A [Prometheus endpoint](/administration/prometheus) is exposed.
## Behind a proxy
See the [proxy guide](/administration/proxy) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
## Deploying on Kubernetes
Woodpecker does not support Kubernetes natively, but being a container first CI engine, it can be deployed to Kubernetes.
The following yamls represent a server (backed by sqlite and Persistent Volumes) and an agent deployment. The agents can be scaled by the `replica` field.
By design, Woodpecker spins up a new container for each workflow step. It talks to the Docker agent to do that.
However in Kubernetes, the Docker agent is not accessible, therefore this deployment follows a Docker in Docker setup and we deploy a DinD sidecar with the agent.
Build step containers are started up within the agent pod.
Warning: this approach requires `privileged` access. Also DinD's reputation hasn't been too high in the early days of Docker - this changed somewhat over time, and there are organizations succeeding with this approach.
server.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: woodpecker
namespace: tools
labels:
app: woodpecker
spec:
replicas: 1
selector:
matchLabels:
app: woodpecker
template:
metadata:
labels:
app: woodpecker
annotations:
prometheus.io/scrape: 'true'
spec:
containers:
- image: woodpeckerci/woodpecker-server:latest
imagePullPolicy: Always
name: woodpecker
env:
- name: "WOODPECKER_ADMIN"
value: "xxx"
- name: "WOODPECKER_HOST"
value: "https://xxx"
- name: "WOODPECKER_GITHUB"
value: "true"
- name: "WOODPECKER_GITHUB_CLIENT"
value: "xxx"
- name: "WOODPECKER_GITHUB_SECRET"
value: "xxx"
- name: "WOODPECKER_SECRET"
value: "xxx"
volumeMounts:
- name: sqlite-volume
mountPath: /var/lib/drone
volumes:
- name: sqlite-volume
persistentVolumeClaim:
claimName: woodpecker-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: woodpecker-pvc
namespace: tools
spec:
accessModes:
- ReadWriteOnce
storageClassName: local-path
resources:
requests:
storage: 10Gi
---
kind: Service
apiVersion: v1
metadata:
name: woodpecker
namespace: tools
spec:
type: ClusterIP
selector:
app: woodpecker
ports:
- protocol: TCP
name: http
port: 80
targetPort: 8000
- protocol: TCP
name: grpc
port: 9000
targetPort: 9000
---
kind: Ingress
apiVersion: extensions/v1beta1
metadata:
name: woodpecker
namespace: tools
spec:
tls:
- hosts:
- xxx
secretName: xxx
rules:
- host: xxx
http:
paths:
- backend:
serviceName: woodpecker
servicePort: 80
```
agent.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: woodpecker-agent
namespace: tools
labels:
app: woodpecker-agent
spec:
selector:
matchLabels:
app: woodpecker-agent
replicas: 2
template:
metadata:
annotations:
labels:
app: woodpecker-agent
spec:
containers:
- name: agent
image: woodpeckerci/woodpecker-agent:latest
imagePullPolicy: Always
ports:
- name: http
containerPort: 3000
protocol: TCP
env:
- name: WOODPECKER_SERVER
value: woodpecker.tools.svc.cluster.local:9000
- name: WOODPECKER_SECRET
value: "xxx"
resources:
limits:
cpu: 2
memory: 2Gi
volumeMounts:
- name: sock-dir
path: /var/run
- name: dind
image: "docker:19.03.5-dind"
env:
- name: DOCKER_DRIVER
value: overlay2
resources:
limits:
cpu: 1
memory: 2Gi
securityContext:
privileged: true
volumeMounts:
- name: sock-dir
mountPath: /var/run
volumes:
- name: sock-dir
emptyDir: {}
```
## Filtering repositories
Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of Github, you may end up syncing more repos into Woodpecker than preferred.
Use the `WOODPECKER_REPO_OWNERS` variable to filter which Github user's repos should be synced only. You typically want to put here your company's Github name.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_ORGS=dolores,dogpatch
+ - WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```

View file

Before

Width:  |  Height:  |  Size: 156 KiB

After

Width:  |  Height:  |  Size: 156 KiB

117
docs/docusaurus.config.js Normal file
View file

@ -0,0 +1,117 @@
const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
/** @type {import('@docusaurus/types').DocusaurusConfig} */
module.exports = {
title: 'Woodpecker CI',
tagline: 'Woodpecker is a simple CI engine with great extensibility.',
url: 'https://woodpecker-ci.github.io',
baseUrl: '/',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.ico',
organizationName: 'woodpecker-ci',
projectName: 'woodpecker-ci.github.io',
trailingSlash: false,
themeConfig: {
navbar: {
title: 'Woodpecker',
logo: {
alt: 'Woodpecker Logo',
src: 'img/logo.svg',
srcDark: 'img/logo-darkmode.svg',
},
items: [
{
type: 'doc',
docId: 'intro',
position: 'left',
label: 'Docs',
},
{
type: 'doc',
docId: 'faq',
position: 'left',
label: 'FAQ',
},
// {to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/woodpecker-ci/woodpecker',
label: 'GitHub',
position: 'right',
},
],
},
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Usage',
to: '/docs/usage/intro',
},
{
label: 'Server setup',
to: '/docs/administration/server-setup',
},
{
label: 'FAQ',
to: '/docs/faq',
},
],
},
{
title: 'Community',
items: [
{
label: 'Discord',
href: 'https://discord.gg/fcMQqSMXJy',
},
],
},
{
title: 'More',
items: [
// {
// label: 'Blog',
// to: '/blog',
// },
{
label: 'GitHub',
href: 'https://github.com/woodpecker-ci/woodpecker',
},
{
href: 'https://wp.laszlo.cloud/woodpecker-ci/woodpecker',
label: 'CI',
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} Woodpecker CI. Built with Docusaurus.`,
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
},
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/master/docs/',
},
// blog: {
// showReadingTime: true,
// editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/master/docs/blog/',
// },
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
},
],
],
};

View file

@ -1,36 +0,0 @@
site_name: Woodpecker
repo_name: 'woodpecker-ci/woodpecker'
repo_url: 'https://github.com/woodpecker-ci/woodpecker'
edit_uri: 'blob/master/docs/docs/'
copyright: 'Creative Commons Attribution-ShareAlike 4.0 International Public License.<br />It is a derivative work of the https://github.com/drone/docs git repository'
nav:
- Home: index.md
- Server Setup: server-setup.md
- Getting Started: getting-started.md
- Pipelines: pipeline.md
- Services: services.md
- Plugins: plugins.md
- Environment Variables: environment-variables.md
- Secrets: secrets.md
- Volumes: volumes.md
- Matrix Builds: matrix-builds.md
- Multi Pipeline Builds: multi-pipeline.md
theme:
name: 'material'
logo: 'images/favicon.svg'
favicon: 'images/favicon.svg'
palette:
primary: 'green'
accent: 'red'
markdown_extensions:
- admonition
- codehilite:
linenums: true
- pymdownx.inlinehilite
extra:
social:
- type: globe
link: http://woodpecker.laszlo.cloud
- type: twitter
link: https://twitter.com/laszlocph

40
docs/package.json Normal file
View file

@ -0,0 +1,40 @@
{
"name": "woodpecker",
"version": "0.0.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.5",
"@docusaurus/preset-classic": "2.0.0-beta.5",
"@mdx-js/react": "^1.6.21",
"@svgr/webpack": "^5.5.0",
"clsx": "^1.1.1",
"file-loader": "^6.2.0",
"prism-react-renderer": "^1.2.1",
"react": "^17.0.1",
"react-dom": "^17.0.1",
"url-loader": "^4.1.1"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
}
}

View file

@ -1,20 +0,0 @@
backports-abc==0.5
Click==7.0
futures==3.3.0
htmlmin==0.1.12
Jinja2==2.10.3
jsmin==2.2.2
livereload==2.6.1
Markdown==3.1.1
MarkupSafe==1.1.1
mkdocs==1.0.4
mkdocs-markdownextradata-plugin==0.1.1
mkdocs-material==4.4.3
mkdocs-minify-plugin==0.2.1
pep562==1.0
Pygments==2.4.2
pymdown-extensions==6.1
PyYAML==5.1.2
singledispatch==3.4.0.3
six==1.13.0
tornado==5.1.1

4
docs/sidebars.js Normal file
View file

@ -0,0 +1,4 @@
module.exports = {
// let Docusaurus generates a sidebar from the docs folder structure
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};

View file

@ -0,0 +1,64 @@
import React from 'react';
import clsx from 'clsx';
import styles from './HomepageFeatures.module.css';
const FeatureList = [
{
title: 'OpenSource and free',
Svg: require('../../static/img/feat-opensource.svg').default,
description: (
<>
Woodpecker is and will be totally free for ever. As Woodpeckers <a href="https://github.com/woodpecker-ci/woodpecker" target="_blank">source code</a> is
OpenSource you can contribute to help evolving the project.
</>
),
},
{
title: 'Based on docker containers',
Svg: require('../../static/img/feat-docker.svg').default,
description: (
<>
Woodpecker uses docker containers to execute pipeline steps. If you need more than a normal docker image, you
can create plugins to extend the pipeline features. <a href="/docs/usage/plugins/plugins">How do plugins work?</a>
</>
),
},
{
title: 'Multi pipelines',
Svg: require('../../static/img/feat-multipipelines.svg').default,
description: (
<>
Woodpecker allows you to easily create multiple pipelines for your project. They can even depend on each other.
Check out the <a href="/docs/usage/multi-pipeline">docs</a>
</>
),
},
];
function Feature({Svg, title, description}) {
return (
<div className={clsx('col col--4')}>
<div className="text--center">
<Svg className={styles.featureSvg} alt={title} />
</div>
<div className="text--center padding-horiz--md">
<h3>{title}</h3>
<p>{description}</p>
</div>
</div>
);
}
export default function HomepageFeatures() {
return (
<section className={styles.features}>
<div className="container">
<div className="row">
{FeatureList.map((props, idx) => (
<Feature key={idx} {...props} />
))}
</div>
</div>
</section>
);
}

View file

@ -0,0 +1,11 @@
.features {
display: flex;
align-items: center;
padding: 2rem 0;
width: 100%;
}
.featureSvg {
height: 200px;
width: 200px;
}

28
docs/src/css/custom.css Normal file
View file

@ -0,0 +1,28 @@
/**
* Any CSS included here will be global. The classic template
* bundles Infima by default. Infima is a CSS framework designed to
* work well for content-centric websites.
*/
/* You can override the default Infima variables here. */
:root {
--ifm-color-primary: #4caf50; /* #25c2a0 */
--ifm-color-primary-dark: rgb(33, 175, 144);
--ifm-color-primary-darker: rgb(31, 165, 136);
--ifm-color-primary-darkest: rgb(26, 136, 112);
--ifm-color-primary-light: rgb(70, 203, 174);
--ifm-color-primary-lighter: rgb(102, 212, 189);
--ifm-color-primary-lightest: rgb(146, 224, 208);
--ifm-code-font-size: 95%;
}
.docusaurus-highlight-code-line {
background-color: rgba(0, 0, 0, 0.1);
display: block;
margin: 0 calc(-1 * var(--ifm-pre-padding));
padding: 0 var(--ifm-pre-padding);
}
html[data-theme='dark'] .docusaurus-highlight-code-line {
background-color: rgba(0, 0, 0, 0.3);
}

40
docs/src/pages/index.js Normal file
View file

@ -0,0 +1,40 @@
import React from 'react';
import clsx from 'clsx';
import Layout from '@theme/Layout';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import styles from './index.module.css';
import HomepageFeatures from '../components/HomepageFeatures';
function HomepageHeader() {
const {siteConfig} = useDocusaurusContext();
return (
<header className={clsx('hero hero--primary', styles.heroBanner)}>
<div className="container">
<h1 className="hero__title">{siteConfig.title}</h1>
<p className="hero__subtitle">{siteConfig.tagline}</p>
<div className={styles.buttons}>
<Link
className="button button--secondary button--lg"
to="/docs/intro">
Woodpecker Tutorial - 5min
</Link>
</div>
</div>
</header>
);
}
export default function Home() {
const {siteConfig} = useDocusaurusContext();
return (
<Layout
title={`${siteConfig.title}`}
description="Woodpecker is a simple CI engine with great extensibility.">
<HomepageHeader />
<main>
<HomepageFeatures />
</main>
</Layout>
);
}

View file

@ -0,0 +1,23 @@
/**
* CSS files with the .module.css suffix will be treated as CSS modules
* and scoped locally.
*/
.heroBanner {
padding: 4rem 0;
text-align: center;
position: relative;
overflow: hidden;
}
@media screen and (max-width: 966px) {
.heroBanner {
padding: 2rem;
}
}
.buttons {
display: flex;
align-items: center;
justify-content: center;
}

0
docs/static/.nojekyll vendored Normal file
View file

BIN
docs/static/img/favicon.ico vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

View file

Before

Width:  |  Height:  |  Size: 4.1 KiB

After

Width:  |  Height:  |  Size: 4.1 KiB

2
docs/static/img/feat-docker.svg vendored Normal file
View file

@ -0,0 +1,2 @@
<!-- https://raw.githubusercontent.com/Templarian/MaterialDesign/master/LICENSE -->
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--mdi" width="32" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 24 24"><path d="M21.81 10.25c-.06-.04-.56-.43-1.64-.43c-.28 0-.56.03-.84.08c-.21-1.4-1.38-2.11-1.43-2.14l-.29-.17l-.18.27c-.24.36-.43.77-.51 1.19c-.2.8-.08 1.56.33 2.21c-.49.28-1.29.35-1.46.35H2.62c-.34 0-.62.28-.62.63c0 1.15.18 2.3.58 3.38c.45 1.19 1.13 2.07 2 2.61c.98.6 2.59.94 4.42.94c.79 0 1.61-.07 2.42-.22c1.12-.2 2.2-.59 3.19-1.16A8.3 8.3 0 0 0 16.78 16c1.05-1.17 1.67-2.5 2.12-3.65h.19c1.14 0 1.85-.46 2.24-.85c.26-.24.45-.53.59-.87l.08-.24l-.19-.14m-17.96.99h1.76c.08 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16H3.85c-.09 0-.16.07-.16.16v1.58c.01.09.07.16.16.16m2.43 0h1.76c.08 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16H6.28c-.09 0-.16.07-.16.16v1.58c.01.09.07.16.16.16m2.47 0h1.75c.1 0 .17-.07.17-.16V9.5c0-.08-.06-.16-.17-.16H8.75c-.08 0-.15.07-.15.16v1.58c0 .09.06.16.15.16m2.44 0h1.77c.08 0 .15-.07.15-.16V9.5c0-.08-.06-.16-.15-.16h-1.77c-.08 0-.15.07-.15.16v1.58c0 .09.07.16.15.16M6.28 9h1.76c.08 0 .16-.09.16-.18V7.25c0-.09-.07-.16-.16-.16H6.28c-.09 0-.16.06-.16.16v1.57c.01.09.07.18.16.18m2.47 0h1.75c.1 0 .17-.09.17-.18V7.25c0-.09-.06-.16-.17-.16H8.75c-.08 0-.15.06-.15.16v1.57c0 .09.06.18.15.18m2.44 0h1.77c.08 0 .15-.09.15-.18V7.25c0-.09-.07-.16-.15-.16h-1.77c-.08 0-.15.06-.15.16v1.57c0 .09.07.18.15.18m0-2.28h1.77c.08 0 .15-.07.15-.16V5c0-.1-.07-.17-.15-.17h-1.77c-.08 0-.15.06-.15.17v1.56c0 .08.07.16.15.16m2.46 4.52h1.76c.09 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16h-1.76c-.08 0-.15.07-.15.16v1.58c0 .09.07.16.15.16" fill="currentColor"></path></svg>

After

Width:  |  Height:  |  Size: 1.7 KiB

View file

@ -0,0 +1,2 @@
<!--Font Awesome Free 5.15.4 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)-->
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--fa-solid" width="32" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 512 512"><path d="M12.41 148.02l232.94 105.67c6.8 3.09 14.49 3.09 21.29 0l232.94-105.67c16.55-7.51 16.55-32.52 0-40.03L266.65 2.31a25.607 25.607 0 0 0-21.29 0L12.41 107.98c-16.55 7.51-16.55 32.53 0 40.04zm487.18 88.28l-58.09-26.33l-161.64 73.27c-7.56 3.43-15.59 5.17-23.86 5.17s-16.29-1.74-23.86-5.17L70.51 209.97l-58.1 26.33c-16.55 7.5-16.55 32.5 0 40l232.94 105.59c6.8 3.08 14.49 3.08 21.29 0L499.59 276.3c16.55-7.5 16.55-32.5 0-40zm0 127.8l-57.87-26.23l-161.86 73.37c-7.56 3.43-15.59 5.17-23.86 5.17s-16.29-1.74-23.86-5.17L70.29 337.87L12.41 364.1c-16.55 7.5-16.55 32.5 0 40l232.94 105.59c6.8 3.08 14.49 3.08 21.29 0L499.59 404.1c16.55-7.5 16.55-32.5 0-40z" fill="currentColor"></path></svg>

After

Width:  |  Height:  |  Size: 1.1 KiB

2
docs/static/img/feat-opensource.svg vendored Normal file
View file

@ -0,0 +1,2 @@
<!-- http://elusiveicons.com/license/ -->
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--el" width="32" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 1200 1200"><path d="M600.073 17.426C268.728 17.426 0 286.008 0 617.353c0 260.49 166.117 482.172 398.146 565.076L546.04 791.313c-74.269-23.013-128.273-92.136-128.273-173.96c0-100.646 81.661-182.307 182.308-182.307c100.646 0 182.16 81.66 182.16 182.307c0 81.888-53.952 151.147-128.273 174.106l147.896 391.115C1033.938 1099.72 1200 877.909 1200 617.353c0-331.345-268.581-599.927-599.927-599.927z" fill="currentColor"></path></svg>

After

Width:  |  Height:  |  Size: 683 B

1
docs/static/img/logo-darkmode.svg vendored Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="22" height="22"><path d="M1.263 2.744C2.41 3.832 2.845 4.932 4.118 5.08l.036.007c-.588.606-1.09 1.402-1.443 2.423-.38 1.096-.488 2.285-.614 3.659-.19 2.046-.401 4.364-1.556 7.269-2.486 6.258-1.12 11.63.332 17.317.664 2.604 1.348 5.297 1.642 8.107a.857.857 0 00.633.744.86.86 0 00.922-.323c.227-.313.524-.797.86-1.424.84 3.323 1.355 6.13 1.783 8.697a.866.866 0 001.517.41c2.88-3.463 3.763-8.636 2.184-12.674.459-2.433 1.402-4.45 2.398-6.583.536-1.15 1.08-2.318 1.55-3.566.228-.084.569-.314.79-.441l1.707-.981-.256 1.052a.864.864 0 001.678.408l.68-2.858 1.285-2.95a.863.863 0 10-1.581-.687l-1.152 2.669-2.383 1.372a18.97 18.97 0 00.508-2.981c.432-4.86-.718-9.074-3.066-11.266-.163-.157-.208-.281-.247-.26.095-.12.249-.26.358-.374 2.283-1.693 6.047-.147 8.319.75.589.232.876-.337.316-.67-1.95-1.153-5.948-4.196-8.188-6.193-.313-.275-.527-.607-.89-.913C9.825.555 4.072 3.057 1.355 2.569c-.102-.018-.166.103-.092.175m10.98 5.899c-.06 1.242-.603 1.8-1 2.208-.217.224-.426.436-.524.738-.236.714.008 1.51.66 2.143 1.974 1.84 2.925 5.527 2.538 9.86-.291 3.288-1.448 5.763-2.671 8.385-1.031 2.207-2.096 4.489-2.577 7.259a.853.853 0 00.056.48c1.02 2.434 1.135 6.197-.672 9.46a96.586 96.586 0 00-1.97-8.711c1.964-4.488 4.203-11.75 2.919-17.668-.325-1.497-1.304-3.276-2.387-4.207-.208-.18-.402-.237-.495-.167-.084.06-.151.238-.062.444.55 1.266.879 2.599 1.226 4.276 1.125 5.443-.956 12.49-2.835 16.782l-.116.259-.457.982c-.356-2.014-.85-3.95-1.33-5.84-1.38-5.406-2.68-10.515-.401-16.254 1.247-3.137 1.483-5.692 1.672-7.746.116-1.263.216-2.355.526-3.252.905-2.605 3.062-3.178 4.744-2.852 1.632.316 3.24 1.593 3.156 3.42zm-2.868.62a1.177 1.177 0 10.736-2.236 1.178 1.178 0 10-.736 2.237z" fill="white" /></svg>

After

Width:  |  Height:  |  Size: 1.7 KiB

1
docs/static/img/logo.svg vendored Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="22" height="22"><path d="M1.263 2.744C2.41 3.832 2.845 4.932 4.118 5.08l.036.007c-.588.606-1.09 1.402-1.443 2.423-.38 1.096-.488 2.285-.614 3.659-.19 2.046-.401 4.364-1.556 7.269-2.486 6.258-1.12 11.63.332 17.317.664 2.604 1.348 5.297 1.642 8.107a.857.857 0 00.633.744.86.86 0 00.922-.323c.227-.313.524-.797.86-1.424.84 3.323 1.355 6.13 1.783 8.697a.866.866 0 001.517.41c2.88-3.463 3.763-8.636 2.184-12.674.459-2.433 1.402-4.45 2.398-6.583.536-1.15 1.08-2.318 1.55-3.566.228-.084.569-.314.79-.441l1.707-.981-.256 1.052a.864.864 0 001.678.408l.68-2.858 1.285-2.95a.863.863 0 10-1.581-.687l-1.152 2.669-2.383 1.372a18.97 18.97 0 00.508-2.981c.432-4.86-.718-9.074-3.066-11.266-.163-.157-.208-.281-.247-.26.095-.12.249-.26.358-.374 2.283-1.693 6.047-.147 8.319.75.589.232.876-.337.316-.67-1.95-1.153-5.948-4.196-8.188-6.193-.313-.275-.527-.607-.89-.913C9.825.555 4.072 3.057 1.355 2.569c-.102-.018-.166.103-.092.175m10.98 5.899c-.06 1.242-.603 1.8-1 2.208-.217.224-.426.436-.524.738-.236.714.008 1.51.66 2.143 1.974 1.84 2.925 5.527 2.538 9.86-.291 3.288-1.448 5.763-2.671 8.385-1.031 2.207-2.096 4.489-2.577 7.259a.853.853 0 00.056.48c1.02 2.434 1.135 6.197-.672 9.46a96.586 96.586 0 00-1.97-8.711c1.964-4.488 4.203-11.75 2.919-17.668-.325-1.497-1.304-3.276-2.387-4.207-.208-.18-.402-.237-.495-.167-.084.06-.151.238-.062.444.55 1.266.879 2.599 1.226 4.276 1.125 5.443-.956 12.49-2.835 16.782l-.116.259-.457.982c-.356-2.014-.85-3.95-1.33-5.84-1.38-5.406-2.68-10.515-.401-16.254 1.247-3.137 1.483-5.692 1.672-7.746.116-1.263.216-2.355.526-3.252.905-2.605 3.062-3.178 4.744-2.852 1.632.316 3.24 1.593 3.156 3.42zm-2.868.62a1.177 1.177 0 10.736-2.236 1.178 1.178 0 10-.736 2.237z"/></svg>

After

Width:  |  Height:  |  Size: 1.7 KiB

8763
docs/yarn.lock Normal file

File diff suppressed because it is too large Load diff