mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-12-23 00:46:30 +00:00
Use versioned docs (#1145)
This commit is contained in:
Anbraten
GitHub
parent
18c1807f4f
commit
605a048b58
75 changed files with 3823 additions and 45 deletions
|
|
@ -84,4 +84,4 @@ pipeline:
|
|||
template: config/k8s/service.yml
|
||||
```
|
||||
|
||||
See [plugin docs](/docs/usage/plugins/plugins).
|
||||
See [plugin docs](./20-usage/51-plugins/10-plugins.md).
|
||||
|
|
|
|||
|
|
@ -213,7 +213,7 @@ Example registry hostname matching logic:
|
|||
|
||||
##### Global registry support
|
||||
|
||||
To make a private registry globally available check the [server configuration docs](/docs/administration/server-config#global-registry-setting).
|
||||
To make a private registry globally available check the [server configuration docs](../30-administration/10-server-config.md#global-registry-setting).
|
||||
|
||||
##### GCR registry support
|
||||
|
||||
|
|
@ -254,13 +254,13 @@ docker run --entrypoint=build.sh golang
|
|||
|
||||
Woodpecker provides the ability to pass environment variables to individual pipeline steps.
|
||||
|
||||
For more details check the [environment docs](/docs/usage/environment/).
|
||||
For more details check the [environment docs](./50-environment.md).
|
||||
|
||||
### `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/).
|
||||
For more details check the [secrets docs](./40-secrets.md).
|
||||
|
||||
### `when` - Conditional Execution
|
||||
|
||||
|
|
@ -380,7 +380,7 @@ when:
|
|||
cron: sync_* # name of your cron job
|
||||
```
|
||||
|
||||
[Read more about cron](/docs/usage/cron)
|
||||
[Read more about cron](./45-cron.md)
|
||||
|
||||
#### `tag`
|
||||
|
||||
|
|
@ -410,7 +410,7 @@ pipeline:
|
|||
#### `platform`
|
||||
|
||||
:::note
|
||||
This condition should be used in conjunction with a [matrix](/docs/usage/matrix-pipelines#example-matrix-pipeline-using-multiple-platforms) pipeline as a regular pipeline will only executed by a single agent which only has one arch.
|
||||
This condition should be used in conjunction with a [matrix](./30-matrix-pipelines.md#example-matrix-pipeline-using-multiple-platforms) pipeline as a regular pipeline will only executed by a single agent which only has one arch.
|
||||
:::
|
||||
|
||||
Execute a step for a specific platform:
|
||||
|
|
@ -516,19 +516,19 @@ In the above example, the `frontend` and `backend` steps are executed in paralle
|
|||
|
||||
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/).
|
||||
For more details check the [volumes docs](./70-volumes.md).
|
||||
|
||||
### `detach`
|
||||
|
||||
Woodpecker gives the ability to detach steps to run them in background until the pipeline finishes.
|
||||
|
||||
For more details check the [service docs](/docs/usage/services#detachment).
|
||||
For more details check the [service docs](./60-services.md#detachment).
|
||||
|
||||
## `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/).
|
||||
For more details check the [services docs](./60-services.md).
|
||||
|
||||
## `workspace`
|
||||
|
||||
|
|
@ -598,7 +598,7 @@ git clone https://github.com/octocat/hello-world \
|
|||
|
||||
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-pipelines/).
|
||||
For more details check the [matrix build docs](./30-matrix-pipelines.md).
|
||||
|
||||
## `platform`
|
||||
|
||||
|
|
@ -624,7 +624,7 @@ pipeline:
|
|||
|
||||
You can set labels for your pipeline to select an agent to execute the pipeline on. An agent will pick up and run a pipeline when **every** label assigned to a pipeline matches the agents labels.
|
||||
|
||||
To set additional agent labels check the [agent configuration options](/docs/administration/agent-config#woodpecker_filter_labels). Agents will have at least three default labels: `platform=agent-os/agent-arch`, `hostname=my-agent` and `repo=*`. Agents can use a `*` as a wildcard for a label. For example `repo=*` will match every repo.
|
||||
To set additional agent labels check the [agent configuration options](../30-administration/15-agent-config.md#woodpecker_filter_labels). Agents will have at least three default labels: `platform=agent-os/agent-arch`, `hostname=my-agent` and `repo=*`. Agents can use a `*` as a wildcard for a label. For example `repo=*` will match every repo.
|
||||
|
||||
Pipeline labels with an empty value will be ignored.
|
||||
By default each pipeline has at least the `repo=your-user/your-repo-name` label. If you have set the [platform attribute](#platform) for your pipeline it will have a label like `platform=your-os/your-arch` as well.
|
||||
|
|
@ -649,7 +649,7 @@ pipeline:
|
|||
|
||||
Woodpecker supports [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) in the pipeline configuration. These can be used as variables to not repeat yourself.
|
||||
|
||||
For more details and examples check the [Advanced YAML syntax docs](/docs/usage/advanced-yaml-syntax)
|
||||
For more details and examples check the [Advanced YAML syntax docs](./35-advanced-yaml-syntax.md)
|
||||
|
||||
## `clone`
|
||||
|
||||
|
|
@ -732,7 +732,7 @@ Woodpecker supports to define multiple pipelines for a repository. Those pipelin
|
|||
|
||||
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. See [project settings](/docs/usage/project-settings#trusted) to enable trusted mode.
|
||||
> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ This Feature is only available for GitHub, Gitea & GitLab repositories. Follow [
|
|||
|
||||
By default, Woodpecker looks for the pipeline definition in `.woodpecker.yml` in the project root.
|
||||
|
||||
The Multi-Pipeline feature allows the pipeline to be split into several files and placed in the `.woodpecker/` folder. Only `.yml` files will be 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).
|
||||
The Multi-Pipeline feature allows the pipeline to be split into several files and placed in the `.woodpecker/` folder. Only `.yml` files will be 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](./71-project-settings.md).
|
||||
|
||||
## Rational
|
||||
|
||||
|
|
@ -15,9 +15,10 @@ The Multi-Pipeline feature allows the pipeline to be split into several files an
|
|||
- utilizing more agents to speed up build
|
||||
|
||||
## Example multi-pipeline definition
|
||||
|
||||
:::warning
|
||||
Please note that files are only shared between steps of the same pipeline (see [File changes are incremental](/docs/usage/pipeline-syntax#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` pipeline below in the `deploy` pipeline.
|
||||
If you still need to pass artifacts between the pipelines you need use storage [plugins](/docs/usage/plugins/plugins) (e.g. one which stores files in an Amazon S3 bucket).
|
||||
Please note that files are only shared between steps of the same pipeline (see [File changes are incremental](./20-pipeline-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` pipeline below in the `deploy` pipeline.
|
||||
If you still need to pass artifacts between the pipelines you need use storage [plugins](./51-plugins/10-plugins.md) (e.g. one which stores files in an Amazon S3 bucket).
|
||||
:::
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ To configure cron jobs you need at least push access to the repository.
|
|||
|
||||
:::warning
|
||||
By default pipelines triggered by cron jobs wont execute any steps in pipelines, as they are not part of the default event filter and you explicitly need to set a `event: cron` filter.
|
||||
Read more at: [pipeline-syntax#event](/docs/usage/pipeline-syntax#event)
|
||||
Read more at: [pipeline-syntax#event](./20-pipeline-syntax.md#event)
|
||||
:::
|
||||
|
||||
## Add a new cron job
|
||||
|
|
|
|||
|
|
@ -32,4 +32,4 @@ Plugins are just pipeline steps. They share the build workspace, mounted as a vo
|
|||
|
||||
## Creating a plugin
|
||||
|
||||
See a [detailed plugin example](/docs/usage/plugins/sample-plugin).
|
||||
See a [detailed plugin example](./20-sample-plugin.md).
|
||||
|
|
|
|||
|
|
@ -3,7 +3,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.
|
||||
|
||||
:::note
|
||||
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.
|
||||
Volumes are only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
|
||||
:::
|
||||
|
||||
```diff
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ As the owner of a project in Woodpecker you can change project related settings
|
|||
|
||||
## Pipeline path
|
||||
|
||||
The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multi pipeline](/docs/usage/multi-pipeline) you have to change it to a folder path ending with a `/` like `.woodpecker/`.
|
||||
The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multi pipeline](./25-multi-pipeline.md) you have to change it to a folder path ending with a `/` like `.woodpecker/`.
|
||||
|
||||
## Repository hooks
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
# Setup
|
||||
|
||||
A Woodpecker deployment consists of two parts:
|
||||
|
||||
- A server which is the heart of Woodpecker and ships the webinterface.
|
||||
- Next to one server you can deploy any number of agents which will run the pipelines.
|
||||
|
||||
|
|
@ -13,9 +14,10 @@ A Woodpecker deployment consists of two parts:
|
|||
## Installation
|
||||
|
||||
You can install Woodpecker on multiple ways:
|
||||
- Using [docker-compose](/docs/administration/setup#docker-compose) with the official [container images](/docs/downloads#docker-images)
|
||||
- By deploying to a [Kubernetes](/docs/administration/kubernetes) with manifests or Woodpeckers official Helm charts
|
||||
- Using [binaries](/docs/downloads)
|
||||
|
||||
- Using [docker-compose](#docker-compose) with the official [container images](../80-downloads.md#docker-images)
|
||||
- By deploying to a [Kubernetes](./80-kubernetes.md) with manifests or Woodpeckers official Helm charts
|
||||
- Using [binaries](../80-downloads.md)
|
||||
|
||||
### docker-compose
|
||||
|
||||
|
|
@ -122,20 +124,20 @@ services:
|
|||
|
||||
Authentication is done using OAuth and is delegated to your forge which is configured by using environment variables. The example above demonstrates basic GitHub integration.
|
||||
|
||||
See the complete reference for all supported forges [here](/docs/administration/forges/overview).
|
||||
See the complete reference for all supported forges [here](./11-forges/10-overview.md).
|
||||
|
||||
## Database
|
||||
|
||||
By default Woodpecker uses a sqlite database which requires zero installation or configuration. See the [database settings](/docs/administration/database) page to further configure it or use MySQL or Postgres.
|
||||
By default Woodpecker uses a sqlite database which requires zero installation or configuration. See the [database settings](./30-database.md) page to further configure it or use MySQL or Postgres.
|
||||
|
||||
## SSL
|
||||
|
||||
Woodpecker supports ssl configuration by using Let's encrypt or by using own certificates. See the [SSL guide](/docs/administration/ssl).
|
||||
Woodpecker supports ssl configuration by using Let's encrypt or by using own certificates. See the [SSL guide](./60-ssl.md).
|
||||
|
||||
## Metrics
|
||||
|
||||
A [Prometheus endpoint](/docs/administration/prometheus) is exposed.
|
||||
A [Prometheus endpoint](./90-prometheus.md) 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.
|
||||
See the [proxy guide](./70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Registration is closed by default. While disabled an administrator needs to add new users manually (exp. `woodpecker-cli user add`).
|
||||
|
||||
If registration is open every user with an account at the configured [forges](/docs/administration/forges/overview) can login to Woodpecker.
|
||||
If registration is open every user with an account at the configured [forges](./11-forges/10-overview.md) can login to Woodpecker.
|
||||
This example enables open registration for users that are members of approved organizations:
|
||||
|
||||
```diff
|
||||
|
|
@ -354,7 +354,7 @@ Example: `WOODPECKER_LIMIT_CPU_SET=1,2`
|
|||
### `WOODPECKER_CONFIG_SERVICE_ENDPOINT`
|
||||
> Default: ``
|
||||
|
||||
Specify a configuration service endpoint, see [Configuration Extension](/docs/administration/external-configuration-api)
|
||||
Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
| Event: Pull-Request | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: |
|
||||
| Event: Deploy | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | :x: |
|
||||
| OAuth | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
|
||||
| [Multi pipeline](/docs/usage/multi-pipeline) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | :x: |
|
||||
| [when.path filter](/docs/usage/pipeline-syntax#path) | :white_check_mark: | :white_check_mark:¹ | :white_check_mark: | :x: | :x: | :x: | :x: |
|
||||
| [Multi pipeline](../../20-usage/25-multi-pipeline.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | :x: |
|
||||
| [when.path filter](../../20-usage/20-pipeline-syntax.md#path) | :white_check_mark: | :white_check_mark:¹ | :white_check_mark: | :x: | :x: | :x: | :x: |
|
||||
|
||||
¹) [except for pull requests](https://github.com/woodpecker-ci/woodpecker/issues/754)
|
||||
|
|
|
|||
|
|
@ -88,7 +88,7 @@ Configures the number of parallel builds.
|
|||
### `WOODPECKER_FILTER_LABELS`
|
||||
> Default: empty
|
||||
|
||||
Configures labels to filter pipeline pick up. Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard. By default agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed. To learn how labels work check out the [pipeline syntax page](/docs/usage/pipeline-syntax#labels).
|
||||
Configures labels to filter pipeline pick up. Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard. By default agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed. To learn how labels work check out the [pipeline syntax page](../20-usage/20-pipeline-syntax.md#labels).
|
||||
|
||||
### `WOODPECKER_HEALTHCHECK`
|
||||
> Default: `true`
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Enable IPv6 for the networks used by pipeline containers (steps). Make sure you
|
|||
|
||||
## Docker credentials
|
||||
|
||||
Woodpecker supports [Docker credentials](https://github.com/docker/docker-credential-helpers) to securely store registry credentials. Install your corresponding credential helper and configure it in your Docker config file passed via [`WOODPECKER_DOCKER_CONFIG`](/docs/administration/server-config#woodpecker_docker_config).
|
||||
Woodpecker supports [Docker credentials](https://github.com/docker/docker-credential-helpers) to securely store registry credentials. Install your corresponding credential helper and configure it in your Docker config file passed via [`WOODPECKER_DOCKER_CONFIG`](../10-server-config.md#woodpecker_docker_config).
|
||||
|
||||
To add your credential helper to the Woodpecker server container you could use the following code to build a custom image:
|
||||
|
||||
|
|
|
|||
|
|
@ -95,8 +95,8 @@ pipeline:
|
|||
### Using labels to filter tasks
|
||||
|
||||
You can use the [agent configuration
|
||||
options](/docs/administration/agent-config#woodpecker_filter_labels) and the
|
||||
[pipeline syntax](/docs/usage/pipeline-syntax#labels) to only run certain
|
||||
options](../15-agent-config.md#woodpecker_filter_labels) and the
|
||||
[pipeline syntax](../../20-usage/20-pipeline-syntax.md#labels) to only run certain
|
||||
pipelines on certain agents. Example:
|
||||
|
||||
Define a `label` `type` with value `exec` for a particular agent:
|
||||
|
|
|
|||
|
|
@ -93,7 +93,7 @@ woodpeckeragent.example.com {
|
|||
```
|
||||
|
||||
:::note
|
||||
Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [WOODPECKER_GRPC_SECURE](/docs/administration/agent-config#woodpecker_grpc_secure).
|
||||
Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [WOODPECKER_GRPC_SECURE](./15-agent-config.md#woodpecker_grpc_secure).
|
||||
:::
|
||||
|
||||
## Ngrok
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ Some versions need some changes to the server configuration or the pipeline conf
|
|||
|
||||
## 1.0.0
|
||||
|
||||
- The signature used to verify extensions calls (like those used for the [config-extension](/docs/administration/external-configuration-api)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](/docs/administration/external-configuration-api) documentation.
|
||||
- Refactored support of old agent filter labels and expression. Learn how to use the new [filter](/docs/usage/pipeline-syntax#labels).
|
||||
- The signature used to verify extensions calls (like those used for the [config-extension](./30-administration/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/100-external-configuration-api.md) documentation.
|
||||
- Refactored support of old agent filter labels and expression. Learn how to use the new [filter](./20-usage/20-pipeline-syntax.md#labels)
|
||||
- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable.
|
||||
|
||||
## 0.15.0
|
||||
|
|
@ -16,7 +16,7 @@ Some versions need some changes to the server configuration or the pipeline conf
|
|||
|
||||
Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases.
|
||||
|
||||
Read more about it at the [Project Settings](/docs/usage/project-settings#pipeline-path)
|
||||
Read more about it at the [Project Settings](./20-usage/71-project-settings.md#pipeline-path)
|
||||
|
||||
- From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`.
|
||||
If you used `latest` before to try pre-release features you should switch to `next` after this release.
|
||||
|
|
@ -49,7 +49,7 @@ Some versions need some changes to the server configuration or the pipeline conf
|
|||
- CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH
|
||||
- CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH
|
||||
|
||||
For all available variables and their descriptions have a look at [built-in-environment-variables](/docs/usage/environment#built-in-environment-variables).
|
||||
For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables).
|
||||
|
||||
- Prometheus metrics have been changed from `drone_*` to `woodpecker_*`
|
||||
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ WOODPECKER_HEALTHCHECK=false
|
|||
|
||||
### Setup O-Auth
|
||||
|
||||
Create an O-Auth app for your forge as describe in the [forges documentation](/docs/administration/forges/overview). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for Github you would use `http://localhost:8000/authorize` as authorization callback URL.
|
||||
Create an O-Auth app for your forge as describe in the [forges documentation](../30-administration/11-forges/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for Github you would use `http://localhost:8000/authorize` as authorization callback URL.
|
||||
|
||||
## Developing with VS-Code
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# UI Development
|
||||
|
||||
To develop the UI you need to install [Node.js and Yarn](/docs/development/getting-started#nodejs--yarn). In addition it is recommended to use VS-Code with the recommended plugin selection to get features like auto-formatting, linting and typechecking. The UI is written with [Vue 3](https://v3.vuejs.org/) as Single-Page-Application accessing the Woodpecker REST api.
|
||||
To develop the UI you need to install [Node.js and Yarn](./01-getting-started.md#nodejs--yarn). In addition it is recommended to use VS-Code with the recommended plugin selection to get features like auto-formatting, linting and typechecking. The UI is written with [Vue 3](https://v3.vuejs.org/) as Single-Page-Application accessing the Woodpecker REST api.
|
||||
|
||||
## Setup
|
||||
The UI code is placed in `web/`. Change to that folder in your terminal with `cd web/` and install all dependencies by running `yarn install`. For production builds the generated UI code is integrated into the Woodpecker server by using [go-embed](https://pkg.go.dev/embed).
|
||||
|
|
@ -10,7 +10,7 @@ Testing UI changes would require us to rebuild the UI after each adjustment to t
|
|||
|
||||
|
||||
Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `yarn start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file.
|
||||
After starting the Woodpecker server as explained in the [debugging](/docs/development/getting-started#debugging) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000).
|
||||
After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000).
|
||||
|
||||
## Tools and frameworks
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
The documentation is using docusaurus as framework. You can learn more about it from its [official documentation](https://docusaurus.io/docs/).
|
||||
|
||||
If you only want to change some text it probably is enough if you just search for the corresponding [Markdown](https://www.markdownguide.org/basic-syntax/) file inside the `docs/docs/` folder and adjust it. If you want to change larger parts and test the rendered documentation you can run docusaurus locally. Similarly to the UI you need to install [Node.js and Yarn](/docs/development/getting-started#nodejs--yarn). After that you can run and build docusaurus locally by using the following commands:
|
||||
If you only want to change some text it probably is enough if you just search for the corresponding [Markdown](https://www.markdownguide.org/basic-syntax/) file inside the `docs/docs/` folder and adjust it. If you want to change larger parts and test the rendered documentation you can run docusaurus locally. Similarly to the UI you need to install [Node.js and Yarn](./01-getting-started.md#nodejs--yarn). After that you can run and build docusaurus locally by using the following commands:
|
||||
|
||||
```bash
|
||||
cd docs/
|
||||
|
|
|
|||
|
|
@ -50,6 +50,10 @@ module.exports = {
|
|||
position: 'left',
|
||||
label: 'Awesome',
|
||||
},
|
||||
{
|
||||
type: 'docsVersionDropdown',
|
||||
position: 'right',
|
||||
},
|
||||
{
|
||||
href: 'https://github.com/woodpecker-ci/woodpecker',
|
||||
position: 'right',
|
||||
|
|
@ -174,6 +178,18 @@ module.exports = {
|
|||
docs: {
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/master/docs/',
|
||||
includeCurrentVersion: true,
|
||||
lastVersion: '0.15',
|
||||
versions: {
|
||||
current: {
|
||||
label: 'Next',
|
||||
banner: 'unreleased',
|
||||
},
|
||||
'0.15': {
|
||||
label: '0.15.x',
|
||||
banner: 'none',
|
||||
},
|
||||
},
|
||||
},
|
||||
theme: {
|
||||
customCss: require.resolve('./src/css/custom.css'),
|
||||
|
|
|
|||
87
docs/versioned_docs/version-0.15/10-intro.md
Normal file
87
docs/versioned_docs/version-0.15/10-intro.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# Welcome to Woodpecker
|
||||
|
||||
Woodpecker is a simple CI engine with great extensibility. It runs your pipelines inside [Docker](https://www.docker.com/) containers, so if you are already using them in your daily workflow, you'll love Woodpecker for sure.
|
||||
|
||||
|
||||
|
||||
## .woodpecker.yml
|
||||
|
||||
- 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
|
||||
# .woodpecker.yml
|
||||
pipeline:
|
||||
build:
|
||||
image: debian
|
||||
commands:
|
||||
- echo "This is the build step"
|
||||
a-test-step:
|
||||
image: debian
|
||||
commands:
|
||||
- echo "Testing.."
|
||||
```
|
||||
|
||||
### Build steps are containers
|
||||
|
||||
- Define any Docker image as context
|
||||
- either use your own and install the needed tools in custom Docker images, or
|
||||
- search [Docker Hub](https://hub.docker.com/search?type=image) for images that are already tailored for your needs)
|
||||
- List the commands that should be executed in your container, in order to build or test your application
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
- image: debian
|
||||
+ image: mycompany/image-with-awscli
|
||||
commands:
|
||||
- aws help
|
||||
```
|
||||
|
||||
### File changes are incremental
|
||||
|
||||
- Woodpecker clones the source code in the beginning pipeline
|
||||
- Changes to files are persisted through steps as the same volume is mounted to all steps
|
||||
|
||||
```yaml
|
||||
# .woodpecker.yml
|
||||
pipeline:
|
||||
build:
|
||||
image: debian
|
||||
commands:
|
||||
- touch myfile
|
||||
a-test-step:
|
||||
image: debian
|
||||
commands:
|
||||
- cat myfile
|
||||
```
|
||||
|
||||
## Plugins are straightforward
|
||||
|
||||
- If you copy the same shell script from project to project
|
||||
- Pack it into a plugin instead
|
||||
- And make the yaml declarative
|
||||
- Plugins are Docker images with your script as an entrypoint
|
||||
|
||||
```Dockerfile
|
||||
# Dockerfile
|
||||
FROM laszlocloud/kubectl
|
||||
COPY deploy /usr/local/deploy
|
||||
ENTRYPOINT ["/usr/local/deploy"]
|
||||
```
|
||||
|
||||
```bash
|
||||
# deploy
|
||||
kubectl apply -f $PLUGIN_TEMPLATE
|
||||
```
|
||||
|
||||
```yaml
|
||||
# .woodpecker.yml
|
||||
pipeline:
|
||||
deploy-to-k8s:
|
||||
image: laszlocloud/my-k8s-plugin
|
||||
template: config/k8s/service.yml
|
||||
```
|
||||
|
||||
See [plugin docs](./20-usage/51-plugins/10-plugins.md).
|
||||
76
docs/versioned_docs/version-0.15/20-usage/10-intro.md
Normal file
76
docs/versioned_docs/version-0.15/20-usage/10-intro.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# Getting started
|
||||
|
||||
## Repository Activation
|
||||
|
||||
To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your version control system (e.g. GitHub).
|
||||
|
||||
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
|
||||
|
||||
|
||||
|
||||
> Required Permissions
|
||||
>
|
||||
>The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook.
|
||||
>
|
||||
> Note that manually creating webhooks yourself is not possible. This is because webhooks are signed using a per-repository secret key which is not exposed to end users.
|
||||
|
||||
# Webhooks
|
||||
|
||||
When you activate your repository Woodpecker automatically add webhooks to your version control system (e.g. GitHub). There is no manual configuration required.
|
||||
|
||||
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
|
||||
|
||||
## Configuration
|
||||
|
||||
To configure your 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.
|
||||
|
||||
:::info
|
||||
|
||||
Currently, only YAML 1.1 syntax is supported for pipeline configuration files. YAML 1.2 support is [planned for the future](https://github.com/woodpecker-ci/woodpecker/issues/517)!
|
||||
|
||||
:::
|
||||
|
||||
Example pipeline configuration:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go get
|
||||
- go build
|
||||
- go test
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:9.4.5
|
||||
environment:
|
||||
- POSTGRES_USER=myapp
|
||||
```
|
||||
|
||||
Example pipeline configuration with multiple, serial steps:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
backend:
|
||||
image: golang
|
||||
commands:
|
||||
- go get
|
||||
- go build
|
||||
- go test
|
||||
|
||||
frontend:
|
||||
image: node:6
|
||||
commands:
|
||||
- npm install
|
||||
- npm test
|
||||
|
||||
notify:
|
||||
image: plugins/slack
|
||||
channel: developers
|
||||
username: woodpecker
|
||||
```
|
||||
|
||||
## Execution
|
||||
|
||||
To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your version control system and execute your pipeline.
|
||||
498
docs/versioned_docs/version-0.15/20-usage/20-pipeline-syntax.md
Normal file
498
docs/versioned_docs/version-0.15/20-usage/20-pipeline-syntax.md
Normal file
|
|
@ -0,0 +1,498 @@
|
|||
# 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.
|
||||
|
||||
Example pipeline:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
backend:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
frontend:
|
||||
image: node
|
||||
commands:
|
||||
- npm install
|
||||
- npm run test
|
||||
- npm run build
|
||||
```
|
||||
|
||||
In the above example we define two pipeline steps, `frontend` and `backend`. The names of these steps are completely arbitrary.
|
||||
|
||||
|
||||
## Global Pipeline Conditionals
|
||||
|
||||
Woodpecker gives the ability to skip whole pipelines (not just steps) based on certain conditions.
|
||||
|
||||
### `branches`
|
||||
Woodpecker can 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:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
+branches: master
|
||||
```
|
||||
|
||||
Example matching multiple target branches:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
+branches: [ master, develop ]
|
||||
```
|
||||
|
||||
Example uses glob matching:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
+branches: [ master, feature/* ]
|
||||
```
|
||||
|
||||
Example includes branches:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
+branches:
|
||||
+ include: [ master, feature/* ]
|
||||
```
|
||||
|
||||
Example excludes branches:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
+branches:
|
||||
+ exclude: [ develop, feature/* ]
|
||||
```
|
||||
|
||||
### `platform`
|
||||
|
||||
To configure your pipeline to only be executed on an agent with a specific platform, you can use the `platform` key.
|
||||
Have a look at the official [go docs](https://go.dev/doc/install/source) for the available platforms. The syntax of the platform is `GOOS/GOARCH` like `linux/arm64` or `linux/amd64`.
|
||||
|
||||
Example:
|
||||
|
||||
Assuming we have two agents, one `arm` and one `amd64`. Previously this pipeline would have executed on **either agent**, as Woodpecker is not fussy about where it runs the pipelines. By setting the following option it will only be executed on an agent with the platform `linux/arm64`.
|
||||
|
||||
```diff
|
||||
+platform: linux/arm64
|
||||
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
```
|
||||
|
||||
### 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]"
|
||||
```
|
||||
|
||||
## `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](./60-services.md).
|
||||
|
||||
## Steps
|
||||
|
||||
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:
|
||||
backend:
|
||||
image: golang
|
||||
commands:
|
||||
+ - go build
|
||||
+ - go test
|
||||
```
|
||||
|
||||
### File changes are incremental
|
||||
|
||||
- Woodpecker clones the source code in the beginning pipeline
|
||||
- Changes to files are persisted through steps as the same volume is mounted to all steps
|
||||
|
||||
```yaml
|
||||
# .woodpecker.yml
|
||||
pipeline:
|
||||
build:
|
||||
image: debian
|
||||
commands:
|
||||
- echo "test content" > myfile
|
||||
a-test-step:
|
||||
image: debian
|
||||
commands:
|
||||
- cat myfile
|
||||
```
|
||||
|
||||
### `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:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
+ image: golang:1.6
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
publish:
|
||||
+ image: plugins/docker
|
||||
repo: foo/bar
|
||||
|
||||
services:
|
||||
database:
|
||||
+ image: mysql
|
||||
```
|
||||
|
||||
Woodpecker supports any valid Docker image from any Docker registry:
|
||||
|
||||
```text
|
||||
image: golang
|
||||
image: golang:1.7
|
||||
image: library/golang:1.7
|
||||
image: index.docker.io/library/golang
|
||||
image: index.docker.io/library/golang:1.7
|
||||
```
|
||||
|
||||
Woodpecker does not automatically upgrade docker images. Example configuration to always pull the latest image when updates are available:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang:latest
|
||||
+ pull: true
|
||||
```
|
||||
|
||||
#### Images from private registries
|
||||
|
||||
You must provide registry credentials on the UI in order to pull private pipeline images defined in your Yaml configuration file.
|
||||
|
||||
These credentials are never exposed to your pipeline, which means they cannot be used to push, and are safe to use with pull requests, for example. Pushing to a registry still require setting credentials for the appropriate plugin.
|
||||
|
||||
Example configuration using a private image:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
+ image: gcr.io/custom/golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
```
|
||||
|
||||
Woodpecker matches the registry hostname to each image in your yaml. If the hostnames match, the registry credentials are used to authenticate to your registry and pull the image. Note that registry credentials are used by the Woodpecker agent and are never exposed to your build containers.
|
||||
|
||||
Example registry hostnames:
|
||||
|
||||
- Image `gcr.io/foo/bar` has hostname `gcr.io`
|
||||
- Image `foo/bar` has hostname `docker.io`
|
||||
- Image `qux.com:8000/foo/bar` has hostname `qux.com:8000`
|
||||
|
||||
Example registry hostname matching logic:
|
||||
|
||||
- Hostname `gcr.io` matches image `gcr.io/foo/bar`
|
||||
- Hostname `docker.io` matches `golang`
|
||||
- Hostname `docker.io` matches `library/golang`
|
||||
- Hostname `docker.io` matches `bradyrydzewski/golang`
|
||||
- Hostname `docker.io` matches `bradyrydzewski/golang:latest`
|
||||
|
||||
#### Global registry support
|
||||
|
||||
To make a private registry globally available check the [server configuration docs](../30-administration/10-server-config.md#global-registry-setting).
|
||||
|
||||
#### 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).
|
||||
|
||||
### `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.
|
||||
|
||||
### `environment`
|
||||
|
||||
Woodpecker provides the ability to pass environment variables to individual pipeline steps.
|
||||
|
||||
For more details check the [environment docs](./50-environment.md).
|
||||
|
||||
### `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](./40-secrets.md).
|
||||
|
||||
### `when` - Conditional Execution
|
||||
|
||||
Woodpecker supports defining conditional pipeline steps in the `when` block.
|
||||
|
||||
For more details check the [Conditional Step Execution](./22-conditional-execution.md).
|
||||
|
||||
### `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.
|
||||
|
||||
Example parallel configuration:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
backend:
|
||||
+ group: build
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
frontend:
|
||||
+ group: build
|
||||
image: node
|
||||
commands:
|
||||
- npm install
|
||||
- npm run test
|
||||
- npm run build
|
||||
publish:
|
||||
image: plugins/docker
|
||||
repo: octocat/hello-world
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### `volumes`
|
||||
|
||||
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](./70-volumes.md).
|
||||
|
||||
### `detach`
|
||||
|
||||
Woodpecker gives the ability to detach steps to run them in background until the pipeline finishes.
|
||||
|
||||
For more details check the [service docs](./60-services.md#detachment).
|
||||
|
||||
## Advanced Configurations
|
||||
|
||||
### `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.
|
||||
|
||||
```
|
||||
/drone/src/github.com/octocat/hello-world
|
||||
```
|
||||
|
||||
The workspace can be customized using the workspace block in the Yaml file:
|
||||
|
||||
```diff
|
||||
+workspace:
|
||||
+ base: /go
|
||||
+ path: src/github.com/octocat/hello-world
|
||||
|
||||
pipeline:
|
||||
build:
|
||||
image: golang:latest
|
||||
commands:
|
||||
- go get
|
||||
- go test
|
||||
```
|
||||
|
||||
The base attribute defines a shared base volume available to all pipeline steps. This ensures your source code, dependencies and compiled binaries are persisted and shared between steps.
|
||||
|
||||
```diff
|
||||
workspace:
|
||||
+ base: /go
|
||||
path: src/github.com/octocat/hello-world
|
||||
|
||||
pipeline:
|
||||
deps:
|
||||
image: golang:latest
|
||||
commands:
|
||||
- go get
|
||||
- go test
|
||||
build:
|
||||
image: node:latest
|
||||
commands:
|
||||
- go build
|
||||
```
|
||||
|
||||
This would be equivalent to the following docker commands:
|
||||
|
||||
```
|
||||
docker volume create my-named-volume
|
||||
|
||||
docker run --volume=my-named-volume:/go golang:latest
|
||||
docker run --volume=my-named-volume:/go node:latest
|
||||
```
|
||||
|
||||
The path attribute defines the working directory of your build. This is where your code is cloned and will be the default working directory of every step in your build process. The path must be relative and is combined with your base path.
|
||||
|
||||
```diff
|
||||
workspace:
|
||||
base: /go
|
||||
+ path: src/github.com/octocat/hello-world
|
||||
```
|
||||
|
||||
```text
|
||||
git clone https://github.com/octocat/hello-world \
|
||||
/go/src/github.com/octocat/hello-world
|
||||
```
|
||||
|
||||
### `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](./30-matrix-builds.md).
|
||||
|
||||
### `clone`
|
||||
|
||||
Woodpecker automatically configures a default clone step if not explicitly defined. You can manually configure the clone step in your pipeline for customization:
|
||||
|
||||
```diff
|
||||
+clone:
|
||||
+ git:
|
||||
+ image: woodpeckerci/plugin-git
|
||||
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
```
|
||||
|
||||
Example configuration to override depth:
|
||||
|
||||
```diff
|
||||
clone:
|
||||
git:
|
||||
image: woodpeckerci/plugin-git
|
||||
+ settings:
|
||||
+ depth: 50
|
||||
```
|
||||
|
||||
Example configuration to use a custom clone plugin:
|
||||
|
||||
```diff
|
||||
clone:
|
||||
git:
|
||||
+ image: octocat/custom-git-plugin
|
||||
```
|
||||
|
||||
Example configuration to clone Mercurial repository:
|
||||
|
||||
```diff
|
||||
clone:
|
||||
hg:
|
||||
+ image: plugins/hg
|
||||
+ settings:
|
||||
+ path: bitbucket.org/foo/bar
|
||||
```
|
||||
|
||||
#### Git Submodules
|
||||
|
||||
To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`:
|
||||
|
||||
```diff
|
||||
[submodule "my-module"]
|
||||
path = my-module
|
||||
-url = git@github.com:octocat/my-module.git
|
||||
+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 Woodpecker, add `submodule_override`:
|
||||
|
||||
```diff
|
||||
clone:
|
||||
git:
|
||||
image: woodpeckerci/plugin-git
|
||||
settings:
|
||||
recursive: true
|
||||
+ submodule_override:
|
||||
+ my-module: https://github.com/octocat/my-module.git
|
||||
|
||||
pipeline:
|
||||
...
|
||||
```
|
||||
|
||||
### 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. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: docker
|
||||
environment:
|
||||
- DOCKER_HOST=tcp://docker:2375
|
||||
commands:
|
||||
- docker --tls=false ps
|
||||
|
||||
services:
|
||||
docker:
|
||||
image: docker:dind
|
||||
command: [ "--storage-driver=vfs", "--tls=false" ]
|
||||
+ privileged: true
|
||||
```
|
||||
|
|
@ -0,0 +1,183 @@
|
|||
# Conditional Step Execution
|
||||
|
||||
Woodpecker supports defining conditions for pipeline step by a `when` block. If all conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped.
|
||||
|
||||
## `repo`
|
||||
|
||||
Example conditional execution by repository:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
slack:
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
+ when:
|
||||
+ repo: test/test
|
||||
```
|
||||
|
||||
## `branch`
|
||||
|
||||
Example conditional execution by branch:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
slack:
|
||||
image: plugins/slack
|
||||
settings:
|
||||
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`
|
||||
|
||||
There are use cases for executing pipeline steps on failure, such as sending notifications for failed pipelines. Use the status constraint to execute steps even when the pipeline fails:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
slack:
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
+ when:
|
||||
+ status: [ success, failure ]
|
||||
```
|
||||
|
||||
## `platform`
|
||||
|
||||
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`
|
||||
|
||||
:::info
|
||||
This feature is currently only available for GitHub, GitLab and Gitea.
|
||||
Pull requests aren't supported by gitea at the moment ([go-gitea/gitea#18228](https://github.com/go-gitea/gitea/pull/18228)).
|
||||
Path conditions are ignored for tag events.
|
||||
:::
|
||||
|
||||
Execute a step only on a pipeline with certain files being changed:
|
||||
|
||||
```diff
|
||||
when:
|
||||
path: "src/*"
|
||||
```
|
||||
|
||||
You can use [glob patterns](https://github.com/bmatcuk/doublestar#patterns) to match the changed files and specify if the step should run if a file matching that pattern has been changed `include` or if some files have **not** been changed `exclude`.
|
||||
|
||||
```diff
|
||||
when:
|
||||
path:
|
||||
include: [ '.woodpecker/*.yml', '*.ini' ]
|
||||
exclude: [ '*.md', 'docs/**' ]
|
||||
ignore_message: "[ALL]"
|
||||
```
|
||||
|
||||
** Hint: ** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions.
|
||||
137
docs/versioned_docs/version-0.15/20-usage/25-multi-pipeline.md
Normal file
137
docs/versioned_docs/version-0.15/20-usage/25-multi-pipeline.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
# Multi pipelines
|
||||
|
||||
:::info
|
||||
This Feature is only available for GitHub, Gitea & GitLab 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.
|
||||
|
||||
The Multi-Pipeline feature allows the pipeline to be split into several files and placed in the `.woodpecker/` folder. Only `.yml` files will be 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](./71-project-settings.md).
|
||||
|
||||
## Rational
|
||||
|
||||
- faster lint/test feedback, the pipeline doesn't have to run fully to have a lint status pushed to the remote
|
||||
- better organization of the pipeline along various concerns: testing, linting, feature apps
|
||||
- utilizing more agents to speed up build
|
||||
|
||||
## Example multi-pipeline definition
|
||||
:::warning
|
||||
Please note that files are only shared between steps of the same pipeline (see [File changes are incremental](./20-pipeline-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` pipeline below in the `deploy` pipeline.
|
||||
If you still need to pass artifacts between the pipelines you need use storage [plugins](docs/usage/plugins/plugins) (e.g. one which stores files in an Amazon S3 bucket).
|
||||
:::
|
||||
|
||||
```bash
|
||||
.woodpecker/
|
||||
├── .build.yml
|
||||
├── .deploy.yml
|
||||
├── .lint.yml
|
||||
└── .test.yml
|
||||
```
|
||||
|
||||
.woodpecker/.build.yml
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
build:
|
||||
image: debian:stable-slim
|
||||
commands:
|
||||
- echo building
|
||||
- sleep 5
|
||||
```
|
||||
|
||||
.woodpecker/.deploy.yml
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
deploy:
|
||||
image: debian:stable-slim
|
||||
commands:
|
||||
- echo deploying
|
||||
|
||||
depends_on:
|
||||
- lint
|
||||
- build
|
||||
- test
|
||||
```
|
||||
|
||||
.woodpecker/.test.yml
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
test:
|
||||
image: debian:stable-slim
|
||||
commands:
|
||||
- echo testing
|
||||
- sleep 5
|
||||
|
||||
depends_on:
|
||||
- build
|
||||
```
|
||||
|
||||
.woodpecker/.lint.yml
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
lint:
|
||||
image: debian:stable-slim
|
||||
commands:
|
||||
- echo linting
|
||||
- sleep 5
|
||||
```
|
||||
|
||||
## Status lines
|
||||
|
||||
Each pipeline has its own status line on GitHub.
|
||||
|
||||
## Flow control
|
||||
|
||||
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 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:
|
||||
deploy:
|
||||
image: debian:stable-slim
|
||||
commands:
|
||||
- echo deploying
|
||||
|
||||
+depends_on:
|
||||
+ - lint
|
||||
+ - build
|
||||
+ - test
|
||||
```
|
||||
|
||||
Pipelines that need to run even on failures should set the `runs_on` tag.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
notify:
|
||||
image: debian:stable-slim
|
||||
commands:
|
||||
- echo notifying
|
||||
|
||||
depends_on:
|
||||
- deploy
|
||||
|
||||
+runs_on: [ success, failure ]
|
||||
```
|
||||
|
||||
Some pipelines don't need the source code, set the `skip_clone` tag to skip cloning:
|
||||
|
||||
```diff
|
||||
|
||||
pipeline:
|
||||
notify:
|
||||
image: debian:stable-slim
|
||||
commands:
|
||||
- echo notifying
|
||||
|
||||
depends_on:
|
||||
- deploy
|
||||
|
||||
runs_on: [ success, failure ]
|
||||
+skip_clone: true
|
||||
```
|
||||
113
docs/versioned_docs/version-0.15/20-usage/30-matrix-builds.md
Normal file
113
docs/versioned_docs/version-0.15/20-usage/30-matrix-builds.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
# Matrix builds
|
||||
|
||||
Woodpecker has integrated support for matrix builds. Woodpecker executes a separate build task for each combination in the matrix, allowing you to build and test a single commit against multiple configurations.
|
||||
|
||||
Example matrix definition:
|
||||
|
||||
```yaml
|
||||
matrix:
|
||||
GO_VERSION:
|
||||
- 1.4
|
||||
- 1.3
|
||||
REDIS_VERSION:
|
||||
- 2.6
|
||||
- 2.8
|
||||
- 3.0
|
||||
```
|
||||
|
||||
Example matrix definition containing only specific combinations:
|
||||
|
||||
```yaml
|
||||
matrix:
|
||||
include:
|
||||
- GO_VERSION: 1.4
|
||||
REDIS_VERSION: 2.8
|
||||
- GO_VERSION: 1.5
|
||||
REDIS_VERSION: 2.8
|
||||
- GO_VERSION: 1.6
|
||||
REDIS_VERSION: 3.0
|
||||
```
|
||||
|
||||
## Interpolation
|
||||
|
||||
Matrix variables are interpolated in the yaml using the `${VARIABLE}` syntax, before the yaml is parsed. This is an example yaml file before interpolating matrix parameters:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
build:
|
||||
image: golang:${GO_VERSION}
|
||||
commands:
|
||||
- go get
|
||||
- go build
|
||||
- go test
|
||||
|
||||
services:
|
||||
database:
|
||||
image: ${DATABASE}
|
||||
|
||||
matrix:
|
||||
GO_VERSION:
|
||||
- 1.4
|
||||
- 1.3
|
||||
DATABASE:
|
||||
- mysql:5.5
|
||||
- mysql:6.5
|
||||
- mariadb:10.1
|
||||
```
|
||||
|
||||
Example Yaml file after injecting the matrix parameters:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
- image: golang:${GO_VERSION}
|
||||
+ image: golang:1.4
|
||||
commands:
|
||||
- go get
|
||||
- go build
|
||||
- go test
|
||||
+ environment:
|
||||
+ - GO_VERSION=1.4
|
||||
+ - DATABASE=mysql:5.5
|
||||
|
||||
services:
|
||||
database:
|
||||
- image: ${DATABASE}
|
||||
+ image: mysql:5.5
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Example matrix build based on Docker image tag:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
build:
|
||||
image: golang:${TAG}
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
matrix:
|
||||
TAG:
|
||||
- 1.7
|
||||
- 1.8
|
||||
- latest
|
||||
```
|
||||
|
||||
Example matrix build based on Docker image:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
build:
|
||||
image: ${IMAGE}
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
matrix:
|
||||
IMAGE:
|
||||
- golang:1.7
|
||||
- golang:1.8
|
||||
- golang:latest
|
||||
```
|
||||
134
docs/versioned_docs/version-0.15/20-usage/40-secrets.md
Normal file
134
docs/versioned_docs/version-0.15/20-usage/40-secrets.md
Normal file
|
|
@ -0,0 +1,134 @@
|
|||
# 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.
|
||||
|
||||
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.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: docker
|
||||
commands:
|
||||
+ - echo $DOCKER_USERNAME
|
||||
+ - echo $DOCKER_PASSWORD
|
||||
+ secrets: [ docker_username, docker_password ]
|
||||
```
|
||||
|
||||
Alternatively, you can get a `setting` from secrets using the `from_secret` syntax.
|
||||
In this example, the secret named `secret_token` would be passed to the pipeline as `PLUGIN_TOKEN`.
|
||||
|
||||
**NOTE:** the `from_secret` syntax only works with the newer `settings` block.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: my-plugin
|
||||
settings:
|
||||
+ token:
|
||||
+ from_secret: secret_token
|
||||
```
|
||||
|
||||
|
||||
Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: docker
|
||||
commands:
|
||||
- - echo ${DOCKER_USERNAME}
|
||||
- - echo ${DOCKER_PASSWORD}
|
||||
+ - echo $${DOCKER_USERNAME}
|
||||
+ - echo $${DOCKER_PASSWORD}
|
||||
secrets: [ docker_username, docker_password ]
|
||||
```
|
||||
|
||||
## Adding Secrets
|
||||
|
||||
Secrets are added to the Woodpecker secret store on the UI or with the CLI.
|
||||
|
||||
## Alternate Names
|
||||
|
||||
There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: plugins/docker
|
||||
repo: octocat/hello-world
|
||||
tags: latest
|
||||
+ secrets:
|
||||
+ - source: docker_prod_password
|
||||
+ target: docker_password
|
||||
```
|
||||
|
||||
## Pull Requests
|
||||
|
||||
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
|
||||
woodpecker-cli secret add \
|
||||
-repository octocat/hello-world \
|
||||
-image plugins/docker \
|
||||
+ -event pull_request \
|
||||
+ -event push \
|
||||
+ -event tag \
|
||||
-name docker_username \
|
||||
-value <value>
|
||||
```
|
||||
|
||||
Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
|
||||
|
||||
## Examples
|
||||
|
||||
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
|
||||
woodpecker-cli secret add \
|
||||
-repository octocat/hello-world \
|
||||
-name aws_access_key_id \
|
||||
-value <value>
|
||||
```
|
||||
|
||||
Create the secret and limit to a single image:
|
||||
|
||||
```diff
|
||||
woodpecker-cli secret add \
|
||||
-repository octocat/hello-world \
|
||||
+ -image plugins/s3 \
|
||||
-name aws_access_key_id \
|
||||
-value <value>
|
||||
```
|
||||
|
||||
Create the secrets and limit to a set of images:
|
||||
|
||||
```diff
|
||||
woodpecker-cli secret add \
|
||||
-repository octocat/hello-world \
|
||||
+ -image plugins/s3 \
|
||||
+ -image peloton/woodpecker-ecs \
|
||||
-name aws_access_key_id \
|
||||
-value <value>
|
||||
```
|
||||
|
||||
Create the secret and enable for multiple hook events:
|
||||
|
||||
```diff
|
||||
woodpecker-cli secret add \
|
||||
-repository octocat/hello-world \
|
||||
-image plugins/s3 \
|
||||
+ -event pull_request \
|
||||
+ -event push \
|
||||
+ -event tag \
|
||||
-name aws_access_key_id \
|
||||
-value <value>
|
||||
```
|
||||
|
||||
Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines:
|
||||
|
||||
```diff
|
||||
woodpecker-cli secret add \
|
||||
-repository octocat/hello-world \
|
||||
-name ssh_key \
|
||||
+ -value @/root/ssh/id_rsa
|
||||
```
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Registries
|
||||
|
||||
Woodpecker provides the ability to add container registries in the settings of your repository. Adding a registry allows you to authenticate and pull private images from a container registry when using these images as a step inside your pipeline.
|
||||
199
docs/versioned_docs/version-0.15/20-usage/50-environment.md
Normal file
199
docs/versioned_docs/version-0.15/20-usage/50-environment.md
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
# Environment variables
|
||||
|
||||
Woodpecker provides the ability to pass environment variables to individual pipeline steps. Example pipeline step with custom environment variables:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
+ environment:
|
||||
+ - CGO=0
|
||||
+ - GOOS=linux
|
||||
+ - GOARCH=amd64
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
```
|
||||
|
||||
Please note that the environment section is not able to expand environment variables. If you need to expand variables they should be exported in the commands section.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
- environment:
|
||||
- - PATH=$PATH:/go
|
||||
commands:
|
||||
+ - export PATH=$PATH:/go
|
||||
- go build
|
||||
- go test
|
||||
```
|
||||
|
||||
> Please be warned that `${variable}` expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- - export PATH=${PATH}:/go
|
||||
+ - export PATH=$${PATH}:/go
|
||||
- go build
|
||||
- go test
|
||||
```
|
||||
|
||||
## Built-in environment variables
|
||||
|
||||
This is the reference list of all environment variables available to your pipeline containers. These are injected into your pipeline step and plugins containers, at runtime.
|
||||
|
||||
| NAME | Description |
|
||||
|--------------------------------|----------------------------------------------------------------------------------------------|
|
||||
| `CI=woodpecker` | environment is woodpecker |
|
||||
| | **Repository** |
|
||||
| `CI_REPO` | repository full name `<owner>/<name>` |
|
||||
| `CI_REPO_OWNER` | repository owner |
|
||||
| `CI_REPO_NAME` | repository name |
|
||||
| `CI_REPO_SCM` | repository scm (git) |
|
||||
| `CI_REPO_LINK` | repository link |
|
||||
| `CI_REPO_REMOTE` | repository clone url |
|
||||
| `CI_REPO_DEFAULT_BRANCH` | repository default branch (master) |
|
||||
| `CI_REPO_PRIVATE` | repository is private |
|
||||
| `CI_REPO_TRUSTED` | repository is trusted |
|
||||
| | **Current Commit** |
|
||||
| `CI_COMMIT_SHA` | commit sha |
|
||||
| `CI_COMMIT_REF` | commit ref |
|
||||
| `CI_COMMIT_REFSPEC` | commit ref spec |
|
||||
| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) |
|
||||
| `CI_COMMIT_SOURCE_BRANCH` | commit source branch |
|
||||
| `CI_COMMIT_TARGET_BRANCH` | commit target branch |
|
||||
| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) |
|
||||
| `CI_COMMIT_PULL_REQUEST` | commit pull request number (empty if event is not `pull_request`) |
|
||||
| `CI_COMMIT_LINK` | commit link in remote |
|
||||
| `CI_COMMIT_MESSAGE` | commit message |
|
||||
| `CI_COMMIT_AUTHOR` | commit author username |
|
||||
| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address |
|
||||
| `CI_COMMIT_AUTHOR_AVATAR` | commit author avatar |
|
||||
| | **Current build** |
|
||||
| `CI_BUILD_NUMBER` | build number |
|
||||
| `CI_BUILD_PARENT` | build number of parent build |
|
||||
| `CI_BUILD_EVENT` | build event (push, pull_request, tag, deployment) |
|
||||
| `CI_BUILD_LINK` | build link in ci |
|
||||
| `CI_BUILD_DEPLOY_TARGET` | build deploy target for `deployment` events (ie production) |
|
||||
| `CI_BUILD_STATUS` | build status (success, failure) |
|
||||
| `CI_BUILD_CREATED` | build created unix timestamp |
|
||||
| `CI_BUILD_STARTED` | build started unix timestamp |
|
||||
| `CI_BUILD_FINISHED` | build finished unix timestamp |
|
||||
| | **Current job** |
|
||||
| `CI_JOB_NUMBER` | job number |
|
||||
| `CI_JOB_STATUS` | job status (success, failure) |
|
||||
| `CI_JOB_STARTED` | job started unix timestamp |
|
||||
| `CI_JOB_FINISHED` | job finished unix timestamp |
|
||||
| | **Previous commit** |
|
||||
| `CI_PREV_COMMIT_SHA` | previous commit sha |
|
||||
| `CI_PREV_COMMIT_REF` | previous commit ref |
|
||||
| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec |
|
||||
| `CI_PREV_COMMIT_BRANCH` | previous commit branch |
|
||||
| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch |
|
||||
| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch |
|
||||
| `CI_PREV_COMMIT_LINK` | previous commit link in remote |
|
||||
| `CI_PREV_COMMIT_MESSAGE` | previous commit message |
|
||||
| `CI_PREV_COMMIT_AUTHOR` | previous commit author username |
|
||||
| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address |
|
||||
| `CI_PREV_COMMIT_AUTHOR_AVATAR` | previous commit author avatar |
|
||||
| | **Previous build** |
|
||||
| `CI_PREV_BUILD_NUMBER` | previous build number |
|
||||
| `CI_PREV_BUILD_PARENT` | previous build number of parent build |
|
||||
| `CI_PREV_BUILD_EVENT` | previous build event (push, pull_request, tag, deployment) |
|
||||
| `CI_PREV_BUILD_LINK` | previous build link in ci |
|
||||
| `CI_PREV_BUILD_DEPLOY_TARGET` | previous build deploy target for `deployment` events (ie production) |
|
||||
| `CI_PREV_BUILD_STATUS` | previous build status (success, failure) |
|
||||
| `CI_PREV_BUILD_CREATED` | previous build created unix timestamp |
|
||||
| `CI_PREV_BUILD_STARTED` | previous build started unix timestamp |
|
||||
| `CI_PREV_BUILD_FINISHED` | previous build finished unix timestamp |
|
||||
| |   |
|
||||
| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to |
|
||||
| | **System** |
|
||||
| `CI_SYSTEM_NAME` | name of the ci system: `woodpecker` |
|
||||
| `CI_SYSTEM_LINK` | link to ci system |
|
||||
| `CI_SYSTEM_HOST` | hostname of ci server |
|
||||
| `CI_SYSTEM_VERSION` | version of the server |
|
||||
| | **Internal** - Please don't use! |
|
||||
| `CI_SCRIPT` | Internal script path. Used to call pipeline step commands. |
|
||||
| `CI_NETRC_USERNAME` | Credentials for private repos to be able to clone data. (Only available for specific images) |
|
||||
| `CI_NETRC_PASSWORD` | Credentials for private repos to be able to clone data. (Only available for specific images) |
|
||||
| `CI_NETRC_MACHINE` | Credentials for private repos to be able to clone data. (Only available for specific images) |
|
||||
|
||||
## Global environment variables
|
||||
|
||||
If you want specific environment variables to be available in all of your builds use the `WOODPECKER_ENVIRONMENT` setting on the Woodpecker server.
|
||||
|
||||
```.diff
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
|
||||
```
|
||||
|
||||
## String Substitution
|
||||
|
||||
Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic build or commit details in our pipeline configuration.
|
||||
|
||||
Example commit substitution:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: plugins/docker
|
||||
settings:
|
||||
+ tags: ${CI_COMMIT_SHA}
|
||||
```
|
||||
|
||||
Example tag substitution:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: plugins/docker
|
||||
settings:
|
||||
+ tags: ${CI_COMMIT_TAG}
|
||||
```
|
||||
|
||||
## String Operations
|
||||
|
||||
Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values.
|
||||
|
||||
| OPERATION | DESC |
|
||||
| ------------------ | ------------------------------------------------ |
|
||||
| `${param}` | parameter substitution |
|
||||
| `${param,}` | parameter substitution with lowercase first char |
|
||||
| `${param,,}` | parameter substitution with lowercase |
|
||||
| `${param^}` | parameter substitution with uppercase first char |
|
||||
| `${param^^}` | parameter substitution with uppercase |
|
||||
| `${param:pos}` | parameter substitution with substring |
|
||||
| `${param:pos:len}` | parameter substitution with substring and length |
|
||||
| `${param=default}` | parameter substitution with default |
|
||||
| `${param##prefix}` | parameter substitution with prefix removal |
|
||||
| `${param%%suffix}` | parameter substitution with suffix removal |
|
||||
| `${param/old/new}` | parameter substitution with find and replace |
|
||||
|
||||
Example variable substitution with substring:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: plugins/docker
|
||||
settings:
|
||||
+ tags: ${CI_COMMIT_SHA:0:8}
|
||||
```
|
||||
|
||||
Example variable substitution strips `v` prefix from `v.1.0.0`:
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
docker:
|
||||
image: plugins/docker
|
||||
settings:
|
||||
+ tags: ${CI_COMMIT_TAG##v}
|
||||
```
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
# Plugins
|
||||
|
||||
Plugins are pipeline steps that perform pre-defined tasks and are configured as steps in your pipeline. Plugins can be used to deploy code, publish artifacts, send notification, and more.
|
||||
|
||||
They are automatically pulled from [plugins.drone.io](http://plugins.drone.io).
|
||||
|
||||
Example pipeline using the Docker and Slack plugins:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
publish:
|
||||
image: plugins/docker
|
||||
settings:
|
||||
repo: foo/bar
|
||||
tags: latest
|
||||
|
||||
notify:
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
```
|
||||
|
||||
## Plugin Isolation
|
||||
|
||||
Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree.
|
||||
|
||||
## Creating a plugin
|
||||
|
||||
See a [detailed plugin example](./20-sample-plugin.md).
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
# 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.
|
||||
|
||||
## What end users will see
|
||||
|
||||
The below example demonstrates how we might configure a webhook plugin in the Yaml file:
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
webhook:
|
||||
image: foo/webhook
|
||||
settings:
|
||||
url: http://foo.com
|
||||
method: post
|
||||
body: |
|
||||
hello world
|
||||
```
|
||||
|
||||
## Write the logic
|
||||
|
||||
Create a simple shell script that invokes curl using the Yaml configuration parameters, which are passed to the script as environment variables in uppercase and prefixed with `PLUGIN_`.
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
curl \
|
||||
-X ${PLUGIN_METHOD} \
|
||||
-d ${PLUGIN_BODY} \
|
||||
${PLUGIN_URL}
|
||||
```
|
||||
|
||||
## Package it
|
||||
|
||||
Create a Dockerfile that adds your shell script to the image, and configures the image to execute your shell script as the main entrypoint.
|
||||
|
||||
```dockerfile
|
||||
FROM alpine
|
||||
ADD script.sh /bin/
|
||||
RUN chmod +x /bin/script.sh
|
||||
RUN apk -Uuv add curl ca-certificates
|
||||
ENTRYPOINT /bin/script.sh
|
||||
```
|
||||
|
||||
Build and publish your plugin to the Docker registry. Once published your plugin can be shared with the broader Woodpecker community.
|
||||
|
||||
```nohighlight
|
||||
docker build -t foo/webhook .
|
||||
docker push foo/webhook
|
||||
```
|
||||
|
||||
Execute your plugin locally from the command line to verify it is working:
|
||||
|
||||
```nohighlight
|
||||
docker run --rm \
|
||||
-e PLUGIN_METHOD=post \
|
||||
-e PLUGIN_URL=http://foo.com \
|
||||
-e PLUGIN_BODY="hello world" \
|
||||
foo/webhook
|
||||
```
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
label: 'Plugins'
|
||||
# position: 2
|
||||
collapsible: true
|
||||
collapsed: true
|
||||
79
docs/versioned_docs/version-0.15/20-usage/60-services.md
Normal file
79
docs/versioned_docs/version-0.15/20-usage/60-services.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# Services
|
||||
|
||||
Woodpecker provides a services section in the Yaml file used for defining service containers. The below configuration composes database and cache containers.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
services:
|
||||
database:
|
||||
image: mysql
|
||||
|
||||
cache:
|
||||
image: redis
|
||||
```
|
||||
|
||||
Services are accessed using custom hostnames. In the above example the mysql service is assigned the hostname `database` and is available at `database:3306`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Service containers generally expose environment variables to customize service startup such as default usernames, passwords and ports. Please see the official image documentation to learn more.
|
||||
|
||||
```diff
|
||||
services:
|
||||
database:
|
||||
image: mysql
|
||||
+ environment:
|
||||
+ - MYSQL_DATABASE=test
|
||||
+ - MYSQL_ALLOW_EMPTY_PASSWORD=yes
|
||||
|
||||
cache:
|
||||
image: redis
|
||||
```
|
||||
|
||||
## Detachment
|
||||
|
||||
Service and long running containers can also be included in the pipeline section of the configuration using the detach parameter without blocking other steps. This should be used when explicit control over startup order is required.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
database:
|
||||
image: redis
|
||||
+ detach: true
|
||||
|
||||
test:
|
||||
image: golang
|
||||
commands:
|
||||
- go test
|
||||
```
|
||||
|
||||
Containers from detached steps will terminate when the pipeline ends.
|
||||
|
||||
## Initialization
|
||||
|
||||
Service containers require time to initialize and begin to accept connections. If you are unable to connect to a service you may need to wait a few seconds or implement a backoff.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
test:
|
||||
image: golang
|
||||
commands:
|
||||
+ - sleep 15
|
||||
- go get
|
||||
- go test
|
||||
|
||||
services:
|
||||
database:
|
||||
image: mysql
|
||||
```
|
||||
25
docs/versioned_docs/version-0.15/20-usage/70-volumes.md
Normal file
25
docs/versioned_docs/version-0.15/20-usage/70-volumes.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Volumes
|
||||
|
||||
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. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
|
||||
|
||||
```diff
|
||||
pipeline:
|
||||
build:
|
||||
image: docker
|
||||
commands:
|
||||
- docker build --rm -t octocat/hello-world .
|
||||
- docker run --rm octocat/hello-world --test
|
||||
- docker push octocat/hello-world
|
||||
- docker rmi octocat/hello-world
|
||||
volumes:
|
||||
+ - /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Please note that Woodpecker mounts volumes on the host machine. This means you must use absolute paths when you configure volumes. Attempting to use relative paths will result in an error.
|
||||
|
||||
```diff
|
||||
- volumes: [ ./certs:/etc/ssl/certs ]
|
||||
+ volumes: [ /etc/ssl/certs:/etc/ssl/certs ]
|
||||
```
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# Project settings
|
||||
|
||||
As the owner of a project in Woodpecker you can change project related settings via the web interface.
|
||||
|
||||
|
||||
|
||||
## Pipeline path
|
||||
|
||||
The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multi pipeline](./25-multi-pipeline.md) you have to change it to a folder path ending with a `/` like `.woodpecker/`.
|
||||
|
||||
## Repository hooks
|
||||
|
||||
Your Version-Control-System will notify Woodpecker about events via webhooks. If you want your pipeline to only run on specific webhooks, you can check them with 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.
|
||||
|
||||
18
docs/versioned_docs/version-0.15/20-usage/80-badges.md
Normal file
18
docs/versioned_docs/version-0.15/20-usage/80-badges.md
Normal 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.
|
||||
4
docs/versioned_docs/version-0.15/20-usage/_category_.yml
Normal file
4
docs/versioned_docs/version-0.15/20-usage/_category_.yml
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
label: 'Usage'
|
||||
# position: 2
|
||||
collapsible: true
|
||||
collapsed: false
|
||||
BIN
docs/versioned_docs/version-0.15/20-usage/project-settings.png
Normal file
BIN
docs/versioned_docs/version-0.15/20-usage/project-settings.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
BIN
docs/versioned_docs/version-0.15/20-usage/repo-list.png
Normal file
BIN
docs/versioned_docs/version-0.15/20-usage/repo-list.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
141
docs/versioned_docs/version-0.15/30-administration/00-setup.md
Normal file
141
docs/versioned_docs/version-0.15/30-administration/00-setup.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
# Setup
|
||||
|
||||
A Woodpecker deployment consists of two parts:
|
||||
- A server which is the heart of Woodpecker and ships the webinterface.
|
||||
- Next to one server you can deploy any number of agents which will run the pipelines.
|
||||
|
||||
> Each agent is able to process one pipeline step 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.
|
||||
|
||||
## Installation
|
||||
|
||||
You can install Woodpecker on multiple ways:
|
||||
- Using [docker-compose](#docker-compose) with the official [docker images](../80-downloads.md#docker-images)
|
||||
- By deploying to a [Kubernetes](./80-kubernetes.md) with manifests or Woodpeckers official Helm charts
|
||||
- Using [binaries](../80-downloads.md)
|
||||
|
||||
### docker-compose
|
||||
|
||||
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server 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/woodpecker/
|
||||
environment:
|
||||
- WOODPECKER_OPEN=true
|
||||
- WOODPECKER_HOST=${WOODPECKER_HOST}
|
||||
- WOODPECKER_GITHUB=true
|
||||
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
|
||||
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
|
||||
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_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_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
||||
|
||||
volumes:
|
||||
woodpecker-server-data:
|
||||
```
|
||||
|
||||
Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
|
||||
```
|
||||
|
||||
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
[...]
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
+ volumes:
|
||||
+ - /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Agents require the server address for agent-to-server communication:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
+ - WOODPECKER_SERVER=woodpecker-server:9000
|
||||
```
|
||||
|
||||
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
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_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 all supported version control systems [here](./11-vcs/10-overview.md).
|
||||
|
||||
## Database
|
||||
|
||||
By default Woodpecker uses a sqlite database which requires zero installation or configuration. See the [database settings](./30-database.md) page to further configure it or use MySQL or Postgres.
|
||||
|
||||
## SSL
|
||||
|
||||
Woodpecker supports ssl configuration by using Let's encrypt or by using own certificates. See the [SSL guide](./60-ssl.md).
|
||||
|
||||
## Metrics
|
||||
|
||||
A [Prometheus endpoint](./90-prometheus.md) is exposed.
|
||||
|
||||
## Behind a proxy
|
||||
|
||||
See the [proxy guide](./70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
|
||||
|
|
@ -0,0 +1,317 @@
|
|||
# Server configuration
|
||||
|
||||
## User registration
|
||||
|
||||
Registration is closed by default. While disabled an administrator needs to add new users manually (exp. `woodpecker-cli user add`).
|
||||
|
||||
If registration is open every user with an account at the configured [SCM](docs/administration/vcs/overview) can login to Woodpecker.
|
||||
This example enables open registration for users that are members of approved organizations:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_OPEN=true
|
||||
+ - WOODPECKER_ORGS=dolores,dogpatch
|
||||
|
||||
```
|
||||
|
||||
## Administrators
|
||||
|
||||
Administrators should also be enumerated in your configuration.
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_ADMIN=johnsmith,janedoe
|
||||
```
|
||||
|
||||
## 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
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
|
||||
```
|
||||
|
||||
## 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:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json
|
||||
```
|
||||
|
||||
## All server configuration options
|
||||
|
||||
The following list describes all available server configuration options.
|
||||
|
||||
### `WOODPECKER_LOG_LEVEL`
|
||||
> Default: empty
|
||||
|
||||
Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty.
|
||||
|
||||
### `WOODPECKER_DEBUG_PRETTY`
|
||||
> Default: `false`
|
||||
|
||||
Enable pretty-printed debug output.
|
||||
|
||||
### `WOODPECKER_DEBUG_NOCOLOR`
|
||||
> Default: `true`
|
||||
|
||||
Disable colored debug output.
|
||||
|
||||
### `WOODPECKER_HOST`
|
||||
> Default: empty
|
||||
|
||||
Server fully qualified url of the user-facing hostname.
|
||||
|
||||
Example: `WOODPECKER_HOST=http://woodpecker.example.org`
|
||||
|
||||
### `WOODPECKER_SERVER_ADDR`
|
||||
> Default: `:8000`
|
||||
|
||||
Configures the HTTP listener port.
|
||||
|
||||
### `WOODPECKER_SERVER_CERT`
|
||||
> Default: empty
|
||||
|
||||
Path to an SSL certificate used by the server to accept HTTPS requests.
|
||||
|
||||
Example: `WOODPECKER_SERVER_CERT=/path/to/cert.pem`
|
||||
|
||||
### `WOODPECKER_SERVER_KEY`
|
||||
> Default: empty
|
||||
|
||||
Path to an SSL certificate key used by the server to accept HTTPS requests.
|
||||
|
||||
Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem`
|
||||
|
||||
### `WOODPECKER_LETS_ENCRYPT`
|
||||
> Default: `false`
|
||||
|
||||
Automatically generates an SSL certificate using Let's Encrypt, and configures the server to accept HTTPS requests.
|
||||
|
||||
### `WOODPECKER_GRPC_ADDR`
|
||||
> Default: `:9000`
|
||||
|
||||
Configures the gRPC listener port.
|
||||
|
||||
|
||||
### `WOODPECKER_ADMIN`
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list of admin accounts.
|
||||
|
||||
Example: `WOODPECKER_ADMIN=user1,user2`
|
||||
|
||||
### `WOODPECKER_ORGS`
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list of approved organizations.
|
||||
|
||||
Example: `org1,org2`
|
||||
|
||||
### `WOODPECKER_REPO_OWNERS`
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list of syncable repo owners. ???
|
||||
|
||||
Example: `user1,user2`
|
||||
|
||||
### `WOODPECKER_OPEN`
|
||||
> Default: `false`
|
||||
|
||||
Enable to allow user registration.
|
||||
|
||||
### `WOODPECKER_DOCS`
|
||||
> Default: `https://woodpecker-ci.org/`
|
||||
|
||||
Link to documentation in the UI.
|
||||
|
||||
### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS`
|
||||
> Default: `false`
|
||||
|
||||
Always use authentication to clone repositories even if they are public. Needed if the SCM requires to always authenticate as used by many companies.
|
||||
|
||||
### `WOODPECKER_DEFAULT_CLONE_IMAGE`
|
||||
> Default: `woodpeckerci/plugin-git:latest`
|
||||
|
||||
The default docker image to be used when cloning the repo
|
||||
|
||||
### `WOODPECKER_SESSION_EXPIRES`
|
||||
> Default: `72h`
|
||||
|
||||
Configures the session expiration time.
|
||||
|
||||
### `WOODPECKER_ESCALATE`
|
||||
> Default: `plugins/docker,plugins/gcr,plugins/ecr,woodpeckerci/plugin-docker,woodpeckerci/plugin-docker-buildx`
|
||||
|
||||
Docker images to run in privileged mode. Only change if you are sure what you do!
|
||||
|
||||
<!--
|
||||
### `WOODPECKER_VOLUME`
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list of Docker volumes that are mounted into every pipeline step.
|
||||
|
||||
Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`|
|
||||
-->
|
||||
|
||||
### `WOODPECKER_DOCKER_CONFIG`
|
||||
> Default: empty
|
||||
|
||||
Configures a specific private registry config for all pipelines.
|
||||
|
||||
Example: `WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json`
|
||||
|
||||
<!--
|
||||
### `WOODPECKER_ENVIRONMENT`
|
||||
> Default: empty
|
||||
|
||||
TODO
|
||||
|
||||
### `WOODPECKER_NETWORK`
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list of Docker networks that are attached to every pipeline step.
|
||||
|
||||
Example: `WOODPECKER_NETWORK=network1,network2`
|
||||
-->
|
||||
|
||||
### `WOODPECKER_AGENT_SECRET`
|
||||
> Default: empty
|
||||
|
||||
A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`.
|
||||
|
||||
### `WOODPECKER_KEEPALIVE_MIN_TIME`
|
||||
> Default: empty
|
||||
|
||||
Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping.
|
||||
|
||||
Example: `WOODPECKER_KEEPALIVE_MIN_TIME=10s`
|
||||
|
||||
### `WOODPECKER_DATABASE_DRIVER`
|
||||
> Default: `sqlite3`
|
||||
|
||||
The database driver name. Possible values are `sqlite3`, `mysql` or `postgres`.
|
||||
|
||||
### `WOODPECKER_DATABASE_DATASOURCE`
|
||||
> Default: `woodpecker.sqlite`
|
||||
|
||||
The database connection string. The default value is the path of the embedded sqlite database file.
|
||||
|
||||
Example:
|
||||
```bash
|
||||
# MySQL
|
||||
# https://github.com/go-sql-driver/mysql#dsn-data-source-name
|
||||
WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
|
||||
|
||||
# PostgreSQL
|
||||
# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
|
||||
WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable
|
||||
```
|
||||
|
||||
### `WOODPECKER_PROMETHEUS_AUTH_TOKEN`
|
||||
> Default: empty
|
||||
|
||||
Token to secure the Prometheus metrics endpoint.
|
||||
|
||||
### `WOODPECKER_STATUS_CONTEXT`
|
||||
> Default: `ci/woodpecker`
|
||||
|
||||
Context prefix Woodpecker will use to publish status messages to SCM. You probably will only need to change it if you run multiple Woodpecker instances for a single repository.
|
||||
|
||||
---
|
||||
|
||||
### `WOODPECKER_LIMIT_MEM_SWAP`
|
||||
> Default: `0`
|
||||
|
||||
The maximum amount of memory a single pipeline container is allowed to swap to disk, configured in bytes. There is no limit if `0`.
|
||||
|
||||
### `WOODPECKER_LIMIT_MEM`
|
||||
> Default: `0`
|
||||
|
||||
The maximum amount of memory a single pipeline container can use, configured in bytes. There is no limit if `0`.
|
||||
|
||||
### `WOODPECKER_LIMIT_SHM_SIZE`
|
||||
> Default: `0`
|
||||
|
||||
The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`.
|
||||
|
||||
### `WOODPECKER_LIMIT_CPU_QUOTA`
|
||||
> Default: `0`
|
||||
|
||||
The number of microseconds per CPU period that the container is limited to before throttled. There is no limit if `0`.
|
||||
|
||||
### `WOODPECKER_LIMIT_CPU_SHARES`
|
||||
> Default: `0`
|
||||
|
||||
The relative weight vs. other containers.
|
||||
|
||||
### `WOODPECKER_LIMIT_CPU_SET`
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list to limit the specific CPUs or cores a pipeline container can use.
|
||||
|
||||
Example: `WOODPECKER_LIMIT_CPU_SET=1,2`
|
||||
|
||||
---
|
||||
|
||||
### `WOODPECKER_GITHUB_...`
|
||||
|
||||
See [Github configuration](vcs/github/#configuration)
|
||||
|
||||
### `WOODPECKER_GOGS_...`
|
||||
|
||||
See [Gogs configuration](vcs/gogs/#configuration)
|
||||
|
||||
### `WOODPECKER_GITEA_...`
|
||||
|
||||
See [Gitea configuration](vcs/gitea/#configuration)
|
||||
|
||||
### `WOODPECKER_BITBUCKET_...`
|
||||
|
||||
See [Bitbucket configuration](vcs/bitbucket/#configuration)
|
||||
|
||||
### `WOODPECKER_STASH_...`
|
||||
|
||||
See [Bitbucket server configuration](vcs/bitbucket_server/#configuration)
|
||||
|
||||
### `WOODPECKER_GITLAB_...`
|
||||
|
||||
See [Gitlab configuration](vcs/gitlab/#configuration)
|
||||
|
||||
### `WOODPECKER_CODING_...`
|
||||
|
||||
See [Coding configuration](vcs/coding/#configuration)
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
# Overview
|
||||
|
||||
## Supported features
|
||||
|
||||
| Feature | [GitHub](github/) | [Gitea](gitea/) | [Gitlab](gitlab/) | [Bitbucket](bitbucket/) | [Bitbucket Server](bitbucket_server/) | [Gogs](gogs/) | [Coding](coding/) |
|
||||
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| Event: Push | :white_check_mark: | :white_check_mark: | :white_check_mark: |
|
||||
| Event: Tag | :white_check_mark: | :white_check_mark: | :white_check_mark: |
|
||||
| Event: Pull-Request | :white_check_mark: | :white_check_mark: | :white_check_mark: |
|
||||
| Event: Deploy | :white_check_mark: | :x: | :x: |
|
||||
| OAuth | :white_check_mark: | :white_check_mark: | :white_check_mark: |
|
||||
| [Multi pipeline](../../20-usage/25-multi-pipeline.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | :x: |
|
||||
| [when.path filter](../../20-usage/22-conditional-execution.md#path) | :white_check_mark: | :white_check_mark:¹ | :white_check_mark: | :x: | :x: | :x: | :x: |
|
||||
|
||||
¹) [except for pull requests](https://github.com/woodpecker-ci/woodpecker/issues/754)
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
# GitHub
|
||||
|
||||
Woodpecker comes with built-in support for GitHub and GitHub Enterprise. To enable GitHub you should configure the Woodpecker server using the following environment variables:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_GITHUB=true
|
||||
+ - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
|
||||
+ - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
|
||||
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
```
|
||||
|
||||
## Registration
|
||||
|
||||
Register your application with GitHub to create your client id and secret. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `<scheme>://<host>/authorize` as the path.
|
||||
|
||||
Please use this screenshot for reference:
|
||||
|
||||
|
||||
|
||||
## 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_GITHUB`
|
||||
> Default: `false`
|
||||
|
||||
Enables the GitHub driver.
|
||||
|
||||
### `WOODPECKER_GITHUB_URL`
|
||||
> Default: `https://github.com`
|
||||
|
||||
Configures the GitHub server address.
|
||||
|
||||
### `WOODPECKER_GITHUB_CLIENT`
|
||||
> Default: empty
|
||||
|
||||
Configures the GitHub OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITHUB_SECRET`
|
||||
> Default: empty
|
||||
|
||||
Configures the GitHub OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITHUB_MERGE_REF`
|
||||
> Default: `true`
|
||||
|
||||
TODO
|
||||
|
||||
### `WOODPECKER_GITHUB_SKIP_VERIFY`
|
||||
> Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
|
@ -0,0 +1,65 @@
|
|||
# Gitea
|
||||
|
||||
Woodpecker comes with built-in support for Gitea. To enable Gitea you should configure the Woodpecker container using the following environment variables:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_GITEA=true
|
||||
+ - WOODPECKER_GITEA_URL=${WOODPECKER_GITEA_URL}
|
||||
+ - WOODPECKER_GITEA_CLIENT=${WOODPECKER_GITEA_CLIENT}
|
||||
+ - WOODPECKER_GITEA_SECRET=${WOODPECKER_GITEA_SECRET}
|
||||
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
```
|
||||
|
||||
## Registration
|
||||
|
||||
Register your application with Gitea to create your client id and secret. You can find the OAuth applications settings of Gitea at `https://gitea.<host>/user/settings/`. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
|
||||
|
||||
If you run the Woodpecker CI server on the same host as the Gitea instance, you might also need to allow local connections in Gitea, since version `v1.16`. Otherwise webhooks will fail. Add the following lines to your Gitea configuration (usually at `/etc/gitea/conf/app.ini`).
|
||||
```ini
|
||||
...
|
||||
[webhook]
|
||||
ALLOWED_HOST_LIST=external,loopback
|
||||
```
|
||||
For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#webhook-webhook).
|
||||
|
||||
|
||||
|
||||
|
||||
## 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`
|
||||
> Default: `false`
|
||||
|
||||
Enables the Gitea driver.
|
||||
|
||||
### `WOODPECKER_GITEA_URL`
|
||||
> Default: `https://try.gitea.io`
|
||||
|
||||
Configures the Gitea server address.
|
||||
|
||||
### `WOODPECKER_GITEA_CLIENT`
|
||||
> Default: empty
|
||||
|
||||
Configures the Gitea OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITEA_SECRET`
|
||||
> Default: empty
|
||||
|
||||
Configures the Gitea OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITEA_SKIP_VERIFY`
|
||||
> Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
# GitLab
|
||||
|
||||
Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
+ - WOODPECKER_GITLAB=true
|
||||
+ - WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com
|
||||
+ - WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82
|
||||
+ - WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075
|
||||
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
```
|
||||
|
||||
## Registration
|
||||
|
||||
You must register your application with GitLab in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click New Application.
|
||||
|
||||
Please use `http://woodpecker.mycompany.com/authorize` as the Authorization callback URL. Grant `api` scope to the application.
|
||||
|
||||
If you run the Woodpecker CI server on the same host as the GitLab instance, you might also need to allow local connections in GitLab, otherwise API requests will fail. In GitLab, navigate to the Admin dashboard, then go to `Settings > Network > Outbound requests` and enable `Allow requests to the local network from web hooks and services`.
|
||||
|
||||
## 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_GITLAB`
|
||||
> Default: `false`
|
||||
|
||||
Enables the GitLab driver.
|
||||
|
||||
### `WOODPECKER_GITLAB_URL`
|
||||
> Default: `https://gitlab.com`
|
||||
|
||||
Configures the GitLab server address.
|
||||
|
||||
### `WOODPECKER_GITLAB_CLIENT`
|
||||
> Default: empty
|
||||
|
||||
Configures the GitLab OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITLAB_SECRET`
|
||||
> Default: empty
|
||||
|
||||
Configures the GitLab OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITLAB_SKIP_VERIFY`
|
||||
> Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
# Bitbucket
|
||||
|
||||
Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_BITBUCKET=true
|
||||
+ - WOODPECKER_BITBUCKET_CLIENT=95c0282573633eb25e82
|
||||
+ - WOODPECKER_BITBUCKET_SECRET=30f5064039e6b359e075
|
||||
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
```
|
||||
|
||||
## Registration
|
||||
|
||||
You must register your application with Bitbucket in order to generate a client and secret. Navigate to your account settings and choose OAuth from the menu, and click Add Consumer.
|
||||
|
||||
Please use the Authorization callback URL:
|
||||
|
||||
```nohighlight
|
||||
http://woodpecker.mycompany.com/authorize
|
||||
```
|
||||
|
||||
Please also be sure to check the following permissions:
|
||||
|
||||
```nohighlight
|
||||
Account:Email
|
||||
Account:Read
|
||||
Team Membership:Read
|
||||
Repositories:Read
|
||||
Webhooks:Read and Write
|
||||
```
|
||||
|
||||
## 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_BITBUCKET`
|
||||
> Default: `false`
|
||||
|
||||
Enables the Bitbucket driver.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_CLIENT`
|
||||
> Default: empty
|
||||
|
||||
Configures the Bitbucket OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_SECRET`
|
||||
> Default: empty
|
||||
|
||||
Configures the Bitbucket OAuth client secret. This is used to authorize access.
|
||||
|
||||
## 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** via [Discord](https://discord.gg/fcMQqSMXJy) or [Matrix](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de).
|
||||
|
|
@ -0,0 +1,141 @@
|
|||
# Bitbucket Server
|
||||
|
||||
Woodpecker comes with experimental support for Bitbucket Server, formerly known as Atlassian Stash. To enable Bitbucket Server you should configure the Woodpecker container using the following environment variables:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - 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
|
||||
volumes:
|
||||
+ - /path/to/key.pem:/path/to/key.pem
|
||||
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
```
|
||||
|
||||
## Private Key File
|
||||
|
||||
The OAuth process in Bitbucket server requires a private and a public RSA certificate. This is how you create the private RSA certificate.
|
||||
|
||||
```nohighlight
|
||||
openssl genrsa -out /etc/bitbucket/key.pem 1024
|
||||
```
|
||||
|
||||
This stores the private RSA certificate in `key.pem`. The next command generates the public RSA certificate and stores it in `key.pub`.
|
||||
|
||||
```nohighlight
|
||||
openssl rsa -in /etc/bitbucket/key.pem -pubout >> /etc/bitbucket/key.pub
|
||||
```
|
||||
|
||||
Please note that the private key file can be mounted into your Woodpecker container at runtime or as an environment variable
|
||||
|
||||
Private key file mounted into your Woodpecker container at runtime as a volume.
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
- 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
|
||||
+ volumes:
|
||||
+ - /etc/bitbucket/key.pem:/etc/bitbucket/key.pem
|
||||
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
```
|
||||
|
||||
Private key as environment variable
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
- 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-agent:
|
||||
[...]
|
||||
```
|
||||
|
||||
## Service Account
|
||||
|
||||
Woodpecker uses `git+https` to clone repositories, however, Bitbucket Server does not currently support cloning repositories with oauth token. To work around this limitation, you must create a service account and provide the username and password to Woodpecker. This service account will be used to authenticate and clone private repositories.
|
||||
|
||||
## Registration
|
||||
|
||||
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://woodpecker.mycompany.com/authorize as the Authorization callback URL.
|
||||
|
||||
## 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_STASH`
|
||||
> Default: `false`
|
||||
|
||||
Enables the Bitbucket Server driver.
|
||||
|
||||
### `WOODPECKER_STASH_URL`
|
||||
> Default: empty
|
||||
|
||||
Configures the Bitbucket Server address.
|
||||
|
||||
### `WOODPECKER_STASH_CONSUMER_KEY`
|
||||
> Default: empty
|
||||
|
||||
Configures your Bitbucket Server consumer key.
|
||||
|
||||
### `WOODPECKER_STASH_CONSUMER_RSA`
|
||||
> Default: empty
|
||||
|
||||
Configures the path to your Bitbucket Server private key file.
|
||||
|
||||
### `WOODPECKER_STASH_CONSUMER_RSA_STRING`
|
||||
> Default: empty
|
||||
|
||||
Configures your Bitbucket Server private key.
|
||||
|
||||
### `WOODPECKER_STASH_GIT_USERNAME`
|
||||
> Default: empty
|
||||
|
||||
This username is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_STASH_GIT_PASSWORD`
|
||||
> Default: empty
|
||||
|
||||
The password is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_STASH_SKIP_VERIFY`
|
||||
> Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
# Gogs
|
||||
|
||||
## 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_GOGS`
|
||||
> Default: `false`
|
||||
|
||||
Enables the Gogs driver.
|
||||
|
||||
### `WOODPECKER_GOGS_URL`
|
||||
> Default: `https://github.com`
|
||||
|
||||
Configures the Gogs server address.
|
||||
|
||||
### `WOODPECKER_GOGS_GIT_USERNAME`
|
||||
> Default: empty
|
||||
|
||||
This username is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_GOGS_GIT_PASSWORD`
|
||||
> Default: empty
|
||||
|
||||
The password is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_GOGS_PRIVATE_MODE`
|
||||
> Default: `false`
|
||||
|
||||
TODO
|
||||
|
||||
### `WOODPECKER_GOGS_SKIP_VERIFY`
|
||||
> Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
# Coding
|
||||
|
||||
## 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_CODING`
|
||||
> Default: `false`
|
||||
|
||||
Enables the Coding driver.
|
||||
|
||||
### `WOODPECKER_CODING_URL`
|
||||
> Default: `https://coding.net`
|
||||
|
||||
Configures the Coding server address.
|
||||
|
||||
### `WOODPECKER_CODING_CLIENT`
|
||||
> Default: empty
|
||||
|
||||
Configures the Coding OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_CODING_SECRET`
|
||||
> Default: empty
|
||||
|
||||
Configures the Coding OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_CODING_SCOPE`
|
||||
> Default: `user, project, project:depot`
|
||||
|
||||
Comma-separated list of OAuth scopes.
|
||||
|
||||
### `WOODPECKER_CODING_GIT_MACHINE`
|
||||
> Default: `git.coding.net`
|
||||
|
||||
TODO
|
||||
|
||||
### `WOODPECKER_CODING_GIT_USERNAME`
|
||||
> Default: empty
|
||||
|
||||
This username is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_CODING_GIT_PASSWORD`
|
||||
> Default: empty
|
||||
|
||||
The password is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_CODING_SKIP_VERIFY`
|
||||
> Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
label: 'Version control systems'
|
||||
collapsible: true
|
||||
collapsed: true
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 129 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
|
|
@ -0,0 +1,151 @@
|
|||
# Agent configuration
|
||||
|
||||
Agents are configured by the command line or environement variables. At the minimum you need the following information:
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
+ - WOODPECKER_SERVER=localhost:9000
|
||||
+ - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
|
||||
|
||||
```
|
||||
|
||||
The following are automatically set and can be overridden:
|
||||
|
||||
- WOODPECKER_HOSTNAME if not set, becomes the OS' hostname
|
||||
- WOODPECKER_MAX_PROCS if not set, defaults to 1
|
||||
|
||||
## Processes per agent
|
||||
|
||||
By default the maximum processes that are run per agent is 1. If required you can add `WOODPECKER_MAX_PROCS` to increase your parellel processing on a per-agent basis.
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
- WOODPECKER_SERVER=localhost:9000
|
||||
- WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
|
||||
+ - WOODPECKER_MAX_PROCS=4
|
||||
```
|
||||
|
||||
## Filtering agents
|
||||
|
||||
When building your pipelines as long as you have set the platform or filter, builds can be made to only run code on certain agents.
|
||||
|
||||
```
|
||||
- WOODPECKER_HOSTNAME=mycompany-ci-01.example.com
|
||||
- WOODPECKER_FILTER=
|
||||
```
|
||||
|
||||
### Filter on Platform
|
||||
|
||||
Only want certain pipelines or steps to run on certain agents with specific platforms? Such as arm vs amd64?
|
||||
|
||||
```yaml
|
||||
# .woodpecker.yml
|
||||
pipeline:
|
||||
build:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
when:
|
||||
platform: linux/amd64
|
||||
|
||||
|
||||
testing:
|
||||
image: golang
|
||||
commands:
|
||||
- go build
|
||||
- go test
|
||||
when:
|
||||
platform: linux/arm*
|
||||
|
||||
|
||||
```
|
||||
|
||||
See [Conditionals Pipeline](../20-usage/20-pipeline-syntax.md#step-when---conditional-execution) syntax for more
|
||||
|
||||
|
||||
## All agent configuration options
|
||||
|
||||
Here is the full list of configuration options and their default variables.
|
||||
|
||||
### `WOODPECKER_SERVER`
|
||||
> Default: `localhost:9000`
|
||||
|
||||
Configures gRPC address of the server.
|
||||
|
||||
### `WOODPECKER_USERNAME`
|
||||
> Default: `x-oauth-basic`
|
||||
|
||||
The gRPC username.
|
||||
|
||||
### `WOODPECKER_AGENT_SECRET`
|
||||
> Default: empty
|
||||
|
||||
A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`.
|
||||
|
||||
### `WOODPECKER_LOG_LEVEL`
|
||||
> Default: empty
|
||||
|
||||
Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty.
|
||||
|
||||
### `WOODPECKER_DEBUG_PRETTY`
|
||||
> Default: `false`
|
||||
|
||||
Enable pretty-printed debug output.
|
||||
|
||||
### `WOODPECKER_DEBUG_NOCOLOR`
|
||||
> Default: `true`
|
||||
|
||||
Disable colored debug output.
|
||||
|
||||
### `WOODPECKER_HOSTNAME`
|
||||
> Default: empty
|
||||
|
||||
Configures the agent hostname.
|
||||
|
||||
### `WOODPECKER_MAX_PROCS`
|
||||
> Default: `1`
|
||||
|
||||
Configures the number of parallel builds.
|
||||
|
||||
### `WOODPECKER_HEALTHCHECK`
|
||||
> Default: `true`
|
||||
|
||||
Enable healthcheck endpoint.
|
||||
|
||||
### `WOODPECKER_KEEPALIVE_TIME`
|
||||
> Default: empty
|
||||
|
||||
After a duration of this time of no activity, the agent pings the server to check if the transport is still alive.
|
||||
|
||||
### `WOODPECKER_KEEPALIVE_TIMEOUT`
|
||||
> Default: `20s`
|
||||
|
||||
After pinging for a keepalive check, the agent waits for a duration of this time before closing the connection if no activity.
|
||||
|
||||
### `WOODPECKER_GRPC_SECURE`
|
||||
> Default: `false`
|
||||
|
||||
Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport.
|
||||
|
||||
### `WOODPECKER_GRPC_VERIFY`
|
||||
> Default: `true`
|
||||
|
||||
Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true`.
|
||||
|
||||
### `WOODPECKER_BACKEND`
|
||||
> Default: `auto-detect`
|
||||
|
||||
Configures the backend engine to run pipelines on. Possible values are `auto-detect` or `docker`.
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
# Databases
|
||||
|
||||
The default database engine of Woodpecker is an embedded SQLite database which requires zero installation or configuration. But you can replace it with a MySQL or Postgres database.
|
||||
|
||||
## Configure sqlite
|
||||
|
||||
By default Woodpecker uses a sqlite database stored under `/var/lib/woodpecker/`. You can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the sqlite database.
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
+ volumes:
|
||||
+ - woodpecker-server-data:/var/lib/woodpecker/
|
||||
```
|
||||
|
||||
## Configure MySQL
|
||||
|
||||
The below example demonstrates mysql database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples.
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
+ WOODPECKER_DATABASE_DRIVER: mysql
|
||||
+ WOODPECKER_DATABASE_DATASOURCE: root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
|
||||
```
|
||||
|
||||
## Configure Postgres
|
||||
|
||||
The below example demonstrates postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples.
|
||||
Please use postgres versions equal or higher than **11**.
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
+ WOODPECKER_DATABASE_DRIVER: postgres
|
||||
+ WOODPECKER_DATABASE_DATASOURCE: postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
|
||||
```
|
||||
|
||||
## Database Creation
|
||||
|
||||
Woodpecker does not create your database automatically. If you are using the mysql or postgres driver you will need to manually create your database using `CREATE DATABASE`
|
||||
|
||||
## Database Migration
|
||||
|
||||
Woodpecker automatically handles database migration, including the initial creation of tables and indexes. New versions of Woodpecker will automatically upgrade the database unless otherwise specified in the release notes.
|
||||
|
||||
## Database Backups
|
||||
|
||||
Woodpecker does not perform database backups. This should be handled by separate third party tools provided by your database vendor of choice.
|
||||
|
||||
## Database Archiving
|
||||
|
||||
Woodpecker does not perform data archival; it considered out-of-scope for the project. Woodpecker is rather conservative with the amount of data it stores, however, you should expect the database logs to grow the size of your database considerably.
|
||||
131
docs/versioned_docs/version-0.15/30-administration/60-ssl.md
Normal file
131
docs/versioned_docs/version-0.15/30-administration/60-ssl.md
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
# SSL
|
||||
|
||||
Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with
|
||||
renewal or provide your own SSL certificates.
|
||||
|
||||
|
||||
## Let's Encrypt
|
||||
|
||||
Woodpecker supports automated SSL configuration and updates using Let's Encrypt.
|
||||
|
||||
You can enable Let's Encrypt by making the following modifications to your server configuration:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
ports:
|
||||
+ - 80:80
|
||||
+ - 443:443
|
||||
- 9000:9000
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_LETS_ENCRYPT=true
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
### Certificate Cache
|
||||
|
||||
Woodpecker writes the certificates to the below directory:
|
||||
|
||||
```
|
||||
/var/lib/woodpecker/golang-autocert
|
||||
```
|
||||
|
||||
### Certificate Updates
|
||||
|
||||
Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required.
|
||||
|
||||
## SSL with own certificates
|
||||
|
||||
Woodpecker supports ssl configuration by mounting certificates into your container.
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
ports:
|
||||
+ - 80:80
|
||||
+ - 443:443
|
||||
- 9000:9000
|
||||
volumes:
|
||||
+ - /etc/certs/woodpecker.foo.com/server.crt:/etc/certs/woodpecker.foo.com/server.crt
|
||||
+ - /etc/certs/woodpecker.foo.com/server.key:/etc/certs/woodpecker.foo.com/server.key
|
||||
environment:
|
||||
- [...]
|
||||
+ - 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:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
ports:
|
||||
+ - 80:80
|
||||
+ - 443:443
|
||||
- 9000:9000
|
||||
```
|
||||
|
||||
Update your configuration to mount your certificate and key:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
ports:
|
||||
- 80:80
|
||||
- 443:443
|
||||
- 9000:9000
|
||||
volumes:
|
||||
+ - /etc/certs/woodpecker.foo.com/server.crt:/etc/certs/woodpecker.foo.com/server.crt
|
||||
+ - /etc/certs/woodpecker.foo.com/server.key:/etc/certs/woodpecker.foo.com/server.key
|
||||
```
|
||||
|
||||
Update your configuration to provide the paths of your certificate and key:
|
||||
|
||||
```diff
|
||||
# docker-compose.yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
ports:
|
||||
- 80:80
|
||||
- 443:443
|
||||
- 9000:9000
|
||||
volumes:
|
||||
- /etc/certs/woodpecker.foo.com/server.crt:/etc/certs/woodpecker.foo.com/server.crt
|
||||
- /etc/certs/woodpecker.foo.com/server.key:/etc/certs/woodpecker.foo.com/server.key
|
||||
environment:
|
||||
+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.foo.com/server.crt
|
||||
+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.foo.com/server.key
|
||||
```
|
||||
|
||||
### Certificate Chain
|
||||
|
||||
The most common problem encountered is providing a certificate file without the intermediate chain.
|
||||
|
||||
> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain.
|
||||
|
||||
### Certificate Errors
|
||||
|
||||
SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely.
|
||||
|
|
@ -0,0 +1,97 @@
|
|||
# Proxy
|
||||
|
||||
## Apache
|
||||
This guide provides a brief overview for installing Woodpecker server behind the Apache2 webserver. This is an example configuration:
|
||||
|
||||
```nohighlight
|
||||
ProxyPreserveHost On
|
||||
|
||||
RequestHeader set X-Forwarded-Proto "https"
|
||||
|
||||
ProxyPass / http://127.0.0.1:8000/
|
||||
ProxyPassReverse / http://127.0.0.1:8000/
|
||||
```
|
||||
|
||||
You must have the below Apache modules installed.
|
||||
|
||||
```nohighlight
|
||||
a2enmod proxy
|
||||
a2enmod proxy_http
|
||||
```
|
||||
|
||||
You must configure Apache to set `X-Forwarded-Proto` when using https.
|
||||
|
||||
```diff
|
||||
ProxyPreserveHost On
|
||||
|
||||
+RequestHeader set X-Forwarded-Proto "https"
|
||||
|
||||
ProxyPass / http://127.0.0.1:8000/
|
||||
ProxyPassReverse / http://127.0.0.1:8000/
|
||||
```
|
||||
|
||||
## Nginx
|
||||
|
||||
This guide provides a basic overview for installing Woodpecker server behind the nginx webserver. For more advanced configuration options please consult the official nginx [documentation](https://www.nginx.com/resources/admin-guide/).
|
||||
|
||||
Example configuration:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name woodpecker.example.com;
|
||||
|
||||
location / {
|
||||
proxy_set_header X-Forwarded-For $remote_addr;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header Host $http_host;
|
||||
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_redirect off;
|
||||
proxy_http_version 1.1;
|
||||
proxy_buffering off;
|
||||
|
||||
chunked_transfer_encoding off;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You must configure the proxy to set `X-Forwarded` proxy headers:
|
||||
|
||||
```diff
|
||||
server {
|
||||
listen 80;
|
||||
server_name woodpecker.example.com;
|
||||
|
||||
location / {
|
||||
+ proxy_set_header X-Forwarded-For $remote_addr;
|
||||
+ proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_redirect off;
|
||||
proxy_http_version 1.1;
|
||||
proxy_buffering off;
|
||||
|
||||
chunked_transfer_encoding off;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Caddy
|
||||
|
||||
This guide provides a brief overview for installing Woodpecker server behind the [Caddy webserver](https://caddyserver.com/). This is an example caddyfile proxy configuration:
|
||||
|
||||
```nohighlight
|
||||
woodpecker.example.com {
|
||||
reverse_proxy woodpecker-server:8000
|
||||
}
|
||||
```
|
||||
|
||||
## Ngrok
|
||||
After installing [ngrok](https://ngrok.com/), open a new console and run:
|
||||
|
||||
```
|
||||
ngrok http 8000
|
||||
```
|
||||
|
||||
Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the ngrok url (usually xxx.ngrok.io) and start the server.
|
||||
|
|
@ -0,0 +1,213 @@
|
|||
# Kubernetes
|
||||
|
||||
Woodpecker does not support Kubernetes natively, but being a container first CI engine, it can be deployed to Kubernetes.
|
||||
|
||||
## Deploy with HELM
|
||||
|
||||
### Preparation
|
||||
|
||||
```shell
|
||||
# create secrets
|
||||
kubectl create secret generic woodpecker-secret \
|
||||
--namespace <namespace> \
|
||||
--from-literal=WOODPECKER_AGENT_SECRET=$(openssl rand -hex 32)
|
||||
|
||||
kubectl create secret generic woodpecker-github-client \
|
||||
--namespace <namespace> \
|
||||
--from-literal=WOODPECKER_GITHUB_CLIENT=xxxxxxxx
|
||||
|
||||
kubectl create secret generic woodpecker-github-secret \
|
||||
--namespace <namespace> \
|
||||
--from-literal=WOODPECKER_GITHUB_SECRET=xxxxxxxx
|
||||
|
||||
# add helm repo
|
||||
helm repo add woodpecker https://woodpecker-ci.org/
|
||||
```
|
||||
|
||||
### Woodpecker server
|
||||
|
||||
```shell
|
||||
# Install
|
||||
helm upgrade --install woodpecker-server --namespace <namespace> woodpecker/woodpecker-server
|
||||
|
||||
# Uninstall
|
||||
helm delete woodpecker-server
|
||||
```
|
||||
|
||||
### Woodpecker agent
|
||||
|
||||
```shell
|
||||
# Install
|
||||
helm upgrade --install woodpecker-agent --namespace <namespace> woodpecker/woodpecker-agent
|
||||
|
||||
# Uninstall
|
||||
helm delete woodpecker-agent
|
||||
```
|
||||
|
||||
## 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_AGENT_SECRET"
|
||||
value: "xxx"
|
||||
volumeMounts:
|
||||
- name: sqlite-volume
|
||||
mountPath: /var/lib/woodpecker
|
||||
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_AGENT_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: {}
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
# Prometheus
|
||||
|
||||
Woodpecker is compatible with Prometheus and exposes a `/metrics` endpoint. Please note that access to the metrics endpoint is restricted and requires an authorization token with administrative privileges.
|
||||
|
||||
```yaml
|
||||
global:
|
||||
scrape_interval: 60s
|
||||
|
||||
scrape_configs:
|
||||
- job_name: 'woodpecker'
|
||||
bearer_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
static_configs:
|
||||
- targets: ['woodpecker.domain.com']
|
||||
```
|
||||
|
||||
## Authorization
|
||||
|
||||
An administrator will need to generate a user api token and configure in the prometheus configuration file as a bearer token. Please see the following example:
|
||||
|
||||
```diff
|
||||
global:
|
||||
scrape_interval: 60s
|
||||
|
||||
scrape_configs:
|
||||
- job_name: 'woodpecker'
|
||||
+ bearer_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
static_configs:
|
||||
- targets: ['woodpecker.domain.com']
|
||||
```
|
||||
|
||||
## Metric Reference
|
||||
|
||||
List of prometheus metrics specific to Woodpecker:
|
||||
|
||||
```
|
||||
# HELP woodpecker_build_count Build count.
|
||||
# TYPE woodpecker_build_count counter
|
||||
woodpecker_build_count{branch="master",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
|
||||
woodpecker_build_count{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
|
||||
# HELP woodpecker_build_time Build time.
|
||||
# TYPE woodpecker_build_time gauge
|
||||
woodpecker_build_time{branch="master",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116
|
||||
woodpecker_build_time{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155
|
||||
# HELP woodpecker_build_total_count Total number of builds.
|
||||
# TYPE woodpecker_build_total_count gauge
|
||||
woodpecker_build_total_count 1025
|
||||
# HELP woodpecker_pending_jobs Total number of pending build processes.
|
||||
# TYPE woodpecker_pending_jobs gauge
|
||||
woodpecker_pending_jobs 0
|
||||
# HELP woodpecker_repo_count Total number of repos.
|
||||
# TYPE woodpecker_repo_count gauge
|
||||
woodpecker_repo_count 9
|
||||
# HELP woodpecker_running_jobs Total number of running build processes.
|
||||
# TYPE woodpecker_running_jobs gauge
|
||||
woodpecker_running_jobs 0
|
||||
# HELP woodpecker_user_count Total number of users.
|
||||
# TYPE woodpecker_user_count gauge
|
||||
woodpecker_user_count 1
|
||||
# HELP woodpecker_waiting_jobs Total number of builds waiting on deps.
|
||||
# TYPE woodpecker_waiting_jobs gauge
|
||||
woodpecker_waiting_jobs 0
|
||||
# HELP woodpecker_worker_count Total number of workers.
|
||||
# TYPE woodpecker_worker_count gauge
|
||||
woodpecker_worker_count 4
|
||||
```
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
label: 'Administration'
|
||||
# position: 3
|
||||
collapsible: true
|
||||
collapsed: true
|
||||
3
docs/versioned_docs/version-0.15/40-cli.md
Normal file
3
docs/versioned_docs/version-0.15/40-cli.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# CLI
|
||||
|
||||
TODO
|
||||
27
docs/versioned_docs/version-0.15/80-downloads.md
Normal file
27
docs/versioned_docs/version-0.15/80-downloads.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# Downloads
|
||||
|
||||
## Binaries & DEB, RPM
|
||||
|
||||
[Latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
|
||||
|
||||
## Docker images
|
||||
|
||||
Image variants:
|
||||
* The `latest` image is the latest stable release
|
||||
* The `vX.X.X` images are stable releases
|
||||
* The `vX.X` images are based on the latest patch version of a specific minor release (see [Semver](https://semver.org/lang/))
|
||||
* The `next` images are based on the current master branch and should not be used for production environments
|
||||
|
||||
``` bash
|
||||
# server
|
||||
docker pull woodpeckerci/woodpecker-server:latest
|
||||
docker pull woodpeckerci/woodpecker-server:latest-alpine
|
||||
|
||||
# agent
|
||||
docker pull woodpeckerci/woodpecker-agent:latest
|
||||
docker pull woodpeckerci/woodpecker-agent:latest-alpine
|
||||
|
||||
# cli
|
||||
docker pull woodpeckerci/woodpecker-cli:latest
|
||||
docker pull woodpeckerci/woodpecker-cli:latest-alpine
|
||||
```
|
||||
78
docs/versioned_docs/version-0.15/91-migrations.md
Normal file
78
docs/versioned_docs/version-0.15/91-migrations.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# Migrations
|
||||
|
||||
Some versions need some changes to the server configuration or the pipeline configuration files.
|
||||
|
||||
## 0.15.0
|
||||
|
||||
- Default value for custom pipeline path is now empty / un-set which results in following resolution:
|
||||
|
||||
`.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml`
|
||||
|
||||
Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases.
|
||||
|
||||
Read more about it at the [Project Settings](./20-usage/71-project-settings.md#pipeline-path)
|
||||
|
||||
- From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`.
|
||||
If you used `latest` before to try pre-release features you should switch to `next` after this release.
|
||||
|
||||
- Dropped support for `DRONE_*` environment variables. The according `WOODPECKER_*` variables must be used instead.
|
||||
Additionally some alternative namings have been removed to simplify maintenance:
|
||||
- `WOODPECKER_AGENT_SECRET` replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD` and `DRONE_AGENT_SECRET`.
|
||||
- `WOODPECKER_HOST` replaces `DRONE_HOST` and `DRONE_SERVER_HOST`.
|
||||
- `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`.
|
||||
- `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`.
|
||||
|
||||
- Dropped support for `DRONE_*` environment variables in pipeline steps. Pipeline meta-data can be accessed with `CI_*` variables.
|
||||
- `CI_*` prefix replaces `DRONE_*`
|
||||
- `CI` value is now `woodpecker`
|
||||
- `DRONE=true` has been removed
|
||||
- Some variables got deprecated and will be removed in future versions. Please migrate to the new names. Same applies for `DRONE_` of them.
|
||||
- CI_ARCH => use CI_SYSTEM_ARCH
|
||||
- CI_COMMIT => CI_COMMIT_SHA
|
||||
- CI_TAG => CI_COMMIT_TAG
|
||||
- CI_PULL_REQUEST => CI_COMMIT_PULL_REQUEST
|
||||
- CI_REMOTE_URL => use CI_REPO_REMOTE
|
||||
- CI_REPO_BRANCH => use CI_REPO_DEFAULT_BRANCH
|
||||
- CI_PARENT_BUILD_NUMBER => use CI_BUILD_PARENT
|
||||
- CI_BUILD_TARGET => use CI_BUILD_DEPLOY_TARGET
|
||||
- CI_DEPLOY_TO => use CI_BUILD_DEPLOY_TARGET
|
||||
- CI_COMMIT_AUTHOR_NAME => use CI_COMMIT_AUTHOR
|
||||
- CI_PREV_COMMIT_AUTHOR_NAME => use CI_PREV_COMMIT_AUTHOR
|
||||
- CI_SYSTEM => use CI_SYSTEM_NAME
|
||||
- CI_BRANCH => use CI_COMMIT_BRANCH
|
||||
- CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH
|
||||
- CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH
|
||||
|
||||
For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables).
|
||||
|
||||
- Prometheus metrics have been changed from `drone_*` to `woodpecker_*`
|
||||
|
||||
- Base path has moved from `/var/lib/drone` to `/var/lib/woodpecker`
|
||||
|
||||
- Default SQLite database location has changed:
|
||||
- `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite`
|
||||
- `drone.sqlite` -> `woodpecker.sqlite`
|
||||
|
||||
- Plugin Settings moved into `settings` section:
|
||||
```diff
|
||||
pipline:
|
||||
something:
|
||||
image: my/plugin
|
||||
- setting1: foo
|
||||
- setting2: bar
|
||||
+ settings:
|
||||
+ setting1: foo
|
||||
+ setting2: bar
|
||||
```
|
||||
|
||||
- `WOODPECKER_DEBUG` option for server and agent got removed in favor of `WOODPECKER_LOG_LEVEL=debug`
|
||||
|
||||
- Remove unused server flags which can safely be removed from your server config: `WOODPECKER_QUIC`, `WOODPECKER_GITHUB_SCOPE`, `WOODPECKER_GITHUB_GIT_USERNAME`, `WOODPECKER_GITHUB_GIT_PASSWORD`, `WOODPECKER_GITHUB_PRIVATE_MODE`, `WOODPECKER_GITEA_GIT_USERNAME`, `WOODPECKER_GITEA_GIT_PASSWORD`, `WOODPECKER_GITEA_PRIVATE_MODE`, `WOODPECKER_GITLAB_GIT_USERNAME`, `WOODPECKER_GITLAB_GIT_PASSWORD`, `WOODPECKER_GITLAB_PRIVATE_MODE`
|
||||
|
||||
- Dropped support for manually setting the agents platform with `WOODPECKER_PLATFORM`. The platform is now automatically detected.
|
||||
|
||||
- Use `WOODPECKER_STATUS_CONTEXT` instead of the deprecated options `WOODPECKER_GITHUB_CONTEXT` and `WOODPECKER_GITEA_CONTEXT`.
|
||||
|
||||
## 0.14.0
|
||||
|
||||
No breaking changes
|
||||
27
docs/versioned_docs/version-0.15/92-awesome.md
Normal file
27
docs/versioned_docs/version-0.15/92-awesome.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# Awesome Woodpecker
|
||||
|
||||
A curated list of awesome things related to Woodpecker-CI.
|
||||
|
||||
If you have some missing resources, please feel free to [open a pull-request](https://github.com/woodpecker-ci/woodpecker/edit/master/docs/docs/92-awesome.md) and add them.
|
||||
|
||||
## Official Resources
|
||||
|
||||
- [Woodpecker CI pipeline configs](https://github.com/woodpecker-ci/woodpecker/tree/master/.woodpecker) - Complex setup containing different kind of pipelines
|
||||
- [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/master/.woodpecker/test.yml)
|
||||
- [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/master/.woodpecker/web.yml)
|
||||
- [Docusaurus & publishing to Github Pages](https://github.com/woodpecker-ci/woodpecker/blob/master/.woodpecker/docs.yml)
|
||||
- [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/master/.woodpecker/docker.yml)
|
||||
- [Helm chart linting & releasing](https://github.com/woodpecker-ci/woodpecker/blob/master/.woodpecker/helm.yml)
|
||||
|
||||
## Projects using Woodpecker
|
||||
|
||||
- [Woodpecker-CI](https://github.com/woodpecker-ci/woodpecker/tree/master/.woodpecker) itself
|
||||
- [All official plugins](https://github.com/woodpecker-ci?q=plugin&type=all)
|
||||
|
||||
## Templates
|
||||
|
||||
## Blogs, guides, videos
|
||||
|
||||
## Plugins
|
||||
|
||||
We have a separate [index](/plugins) for plugins.
|
||||
|
|
@ -0,0 +1,127 @@
|
|||
# Getting started
|
||||
|
||||
## Preparation
|
||||
|
||||
### Install Go
|
||||
|
||||
Install Golang (>=1.16) as described by [this guide](https://go.dev/doc/install).
|
||||
|
||||
### Install make
|
||||
|
||||
> GNU Make is a tool which controls the generation of executables and other non-source files of a program from the program's source files. (https://www.gnu.org/software/make/)
|
||||
|
||||
Install make on:
|
||||
- Ubuntu: `apt install make` - [Docs](https://wiki.ubuntuusers.de/Makefile/)
|
||||
- [Windows](https://stackoverflow.com/a/32127632/8461267)
|
||||
- Mac OS: `brew install make`
|
||||
|
||||
### Install Node.js & Yarn
|
||||
|
||||
Install [Node.js (>=14)](https://nodejs.org/en/download/) if you want to build Woodpeckers UI or documentation.
|
||||
|
||||
For dependencies installation (node_modules) for the UI and documentation of Woodpecker the package-manager Yarn is used. The installation of Yarn is described by [this guide](https://yarnpkg.com/getting-started/install).
|
||||
|
||||
### Create a `.env` file with your development configuration
|
||||
|
||||
Similar to the environment variables you can set for your production setup of Woodpecker, you can create a `.env` in the root of the Woodpecker project and add any need config to it.
|
||||
|
||||
A common config for debugging would look like this:
|
||||
|
||||
```ini
|
||||
WOODPECKER_OPEN=true
|
||||
WOODPECKER_ADMIN=your-username
|
||||
|
||||
# if you want to test webhooks with an online SCM like Github this address needs to be accessible from public server
|
||||
WOODPECKER_HOST=http://your-dev-address.com/
|
||||
|
||||
# github (sample for a SCM config - see /docs/administration/vcs/overview for other SCMs)
|
||||
WOODPECKER_GITHUB=true
|
||||
WOODPECKER_GITHUB_CLIENT=<redacted>
|
||||
WOODPECKER_GITHUB_SECRET=<redacted>
|
||||
|
||||
# agent
|
||||
WOODPECKER_SERVER=localhost:9000
|
||||
WOODPECKER_SECRET=a-long-and-secure-password-used-for-the-local-development-system
|
||||
WOODPECKER_MAX_PROCS=1
|
||||
|
||||
# enable if you want to develop the UI
|
||||
# WOODPECKER_DEV_WWW_PROXY=http://localhost:3000
|
||||
|
||||
# used so you can login without using a public address
|
||||
WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000
|
||||
|
||||
# disable health-checks while debugging (normally not needed while developing)
|
||||
WOODPECKER_HEALTHCHECK=false
|
||||
|
||||
# WOODPECKER_LOG_LEVEL=debug
|
||||
# WOODPECKER_LOG_LEVEL=trace
|
||||
```
|
||||
|
||||
### Setup O-Auth
|
||||
|
||||
Create an O-Auth app for your SCM as describe in the [SCM documentation](../30-administration/11-vcs/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific SCM to login without the need for a public address. For example for Github you would use `http://localhost:8000/authorize` as authorization callback URL.
|
||||
|
||||
## Developing with VS-Code
|
||||
|
||||
You can use different methods for debugging the Woodpecker applications. One of the currently recommend ways to debug and test the Woodpecker application is using [VS-Code](https://code.visualstudio.com/) or [VS-Codium](https://vscodium.com/) (Open-Source binaries of VS-Code) as most maintainers are using it and Woodpecker already includes the needed debug configurations for it.
|
||||
|
||||
As a starting guide for programming Go with VS-Code you can use this video guide:
|
||||
[](https://www.youtube.com/watch?v=1MXIGYrMk80)
|
||||
|
||||
### Debugging Woodpecker
|
||||
|
||||
The Woodpecker source code already includes launch configurations for the Woodpecker server and agent. To start debugging you can click on the debug icon in the navigation bar of VS-Code (ctrl-shift-d). On that page you will see the existing launch jobs at the top. Simply select the agent or server and click on the play button. You can set breakpoints in the source files to stop at specific points.
|
||||
|
||||
|
||||
|
||||
## Testing & linting code
|
||||
|
||||
To test or lint parts of Woodpecker you can run one of the following commands:
|
||||
|
||||
```bash
|
||||
# test server code
|
||||
make test-server
|
||||
|
||||
# test agent code
|
||||
make test-agent
|
||||
|
||||
# test cli code
|
||||
make test-cli
|
||||
|
||||
# test datastore / database related code like migrations of the server
|
||||
make test-server-datastore
|
||||
|
||||
# lint go code
|
||||
make lint
|
||||
|
||||
# lint UI code
|
||||
make lint-frontend
|
||||
|
||||
# test UI code
|
||||
make test-frontend
|
||||
```
|
||||
|
||||
If you want to test a specific go file you can also use:
|
||||
|
||||
```bash
|
||||
go test -race -timeout 30s github.com/woodpecker-ci/woodpecker/<path-to-the-package-or-file-to-test>
|
||||
```
|
||||
|
||||
Or you can open the test-file inside [VS-Code](#developing-with-vs-code) and run or debug the test by clicking on the inline commands:
|
||||
|
||||
|
||||
|
||||
## Run applications from terminal
|
||||
|
||||
If you want to run a Woodpecker applications from your terminal you can use one of the following commands from the base of the Woodpecker project. They will execute Woodpecker in a similar way as described in [debugging Woodpecker](#debugging-woodpecker) without the ability to really debug it in your editor.
|
||||
|
||||
```bash
|
||||
# start server
|
||||
$ go run ./cmd/server
|
||||
|
||||
# start agent
|
||||
$ go run ./cmd/agent
|
||||
|
||||
# execute cli command
|
||||
$ go run ./cmd/cli [command]
|
||||
```
|
||||
31
docs/versioned_docs/version-0.15/92-development/03-ui.md
Normal file
31
docs/versioned_docs/version-0.15/92-development/03-ui.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# UI Development
|
||||
|
||||
To develop the UI you need to install [Node.js and Yarn](./01-getting-started.md#nodejs--yarn). In addition it is recommended to use VS-Code with the recommended plugin selection to get features like auto-formatting, linting and typechecking. The UI is written with [Vue 3](https://v3.vuejs.org/) as Single-Page-Application accessing the Woodpecker REST api.
|
||||
|
||||
## Setup
|
||||
The UI code is placed in `web/`. Change to that folder in your terminal with `cd web/` and install all dependencies by running `yarn install`. For production builds the generated UI code is integrated into the Woodpecker server by using [go-embed](https://pkg.go.dev/embed).
|
||||
|
||||
Testing UI changes would require us to rebuild the UI after each adjustment to the code by running `yarn build` and restarting the Woodpecker server. To avoid this you can make use of the dev-proxy integrated into the Woodpecker server. This integrated dev-proxy will forward all none api request to a separate http-server which will only serve the UI files.
|
||||
|
||||
|
||||
|
||||
Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `yarn start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file.
|
||||
After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000).
|
||||
|
||||
## Tools and frameworks
|
||||
|
||||
The following list contains some tools and frameworks used by the Woodpecker UI. For some points we added some guidelines / hints to help you developing.
|
||||
|
||||
- [Vue 3](https://v3.vuejs.org/)
|
||||
- use `setup` and composition api
|
||||
- place (re-usable) components in `web/src/components/`
|
||||
- views should have a route in `web/src/router.ts` and are located in `web/src/views/`
|
||||
- [Windicss](https://windicss.org/) (similar to Tailwind)
|
||||
- use Windicss classes where possible
|
||||
- if needed extend the Windicss config to use new classes
|
||||
- [Vite](https://vitejs.dev/) (similar to Webpack)
|
||||
- [Typescript](https://www.typescriptlang.org/)
|
||||
- avoid using `any` and `unknown` (the linter will prevent you from doing so anyways :wink:)
|
||||
- [eslint](https://eslint.org/)
|
||||
- [Volar & vue-tsc](https://github.com/johnsoncodehk/volar/) for type-checking in .vue file
|
||||
- use the take-over mode of Volar as described by [this guide](https://github.com/johnsoncodehk/volar/discussions/471)
|
||||
20
docs/versioned_docs/version-0.15/92-development/04-docs.md
Normal file
20
docs/versioned_docs/version-0.15/92-development/04-docs.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# Documentation
|
||||
|
||||
The documentation is using docusaurus as framework. You can learn more about it from its [official documentation](https://docusaurus.io/docs/).
|
||||
|
||||
If you only want to change some text it probably is enough if you just search for the corresponding [Markdown](https://www.markdownguide.org/basic-syntax/) file inside the `docs/docs/` folder and adjust it. If you want to change larger parts and test the rendered documentation you can run docusaurus locally. Similarly to the UI you need to install [Node.js and Yarn](./01-getting-started.md#nodejs--yarn). After that you can run and build docusaurus locally by using the following commands:
|
||||
|
||||
```bash
|
||||
cd docs/
|
||||
|
||||
yarn install
|
||||
|
||||
# build plugins used by the docs
|
||||
yarn build:woodpecker-plugins
|
||||
|
||||
# start docs with hot-reloading, so you can change the docs and directly see the changes in the browser without reloading it manually
|
||||
yarn start
|
||||
|
||||
# or build the docs to deploy it to some static page hosting
|
||||
yarn build
|
||||
```
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
# Architecture
|
||||
|
||||
## Package architecture
|
||||
|
||||
|
||||
|
||||
## System architecture
|
||||
|
||||
TODO
|
||||
35
docs/versioned_docs/version-0.15/92-development/06-guides.md
Normal file
35
docs/versioned_docs/version-0.15/92-development/06-guides.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# Guides
|
||||
|
||||
## ORM
|
||||
|
||||
Woodpecker uses [Xorm](https://xorm.io/) as ORM for the database connection.
|
||||
You can find its documentation at [gobook.io/read/gitea.com/xorm](https://gobook.io/read/gitea.com/xorm/manual-en-US/).
|
||||
|
||||
## Add a new migration
|
||||
|
||||
Woodpecker uses migrations to change the database schema if a database model has been changed. If for example a developer removes a property `Counter` from the model `Repo` in `server/model/` they would need to add a new migration task like the following example to a file like `server/store/datastore/migration/004_repos_drop_repo_counter.go`:
|
||||
|
||||
```go
|
||||
package migration
|
||||
|
||||
import (
|
||||
"xorm.io/xorm"
|
||||
)
|
||||
|
||||
var alterTableReposDropCounter = task{
|
||||
name: "alter-table-drop-counter",
|
||||
fn: func(sess *xorm.Session) error {
|
||||
return dropTableColumns(sess, "repos", "repo_counter")
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
:::info
|
||||
Adding new properties to models will be handled automatically by the underlying [ORM](#orm) based on the [struct field tags](https://stackoverflow.com/questions/10858787/what-are-the-uses-for-tags-in-go) of the model. If you add a completely new model, you have to add it to the `allBeans` variable at `server/store/datastore/migration/migration.go` to get a new table created.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
You should not use `sess.Begin()`, `sess.Commit()` or `sess.Close()` inside a migration. Session / transaction handling will be done by the underlying migration manager.
|
||||
:::
|
||||
|
||||
To automatically execute the migration after the start of the server, the new migration needs to be added to the end of `migrationTasks` in `server/store/datastore/migration/migration.go`. After a successful execution of that transaction the server will automatically add the migration to a list, so it wont be executed again on the next start.
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
label: 'Development'
|
||||
# position: 3
|
||||
collapsible: true
|
||||
collapsed: true
|
||||
16
docs/versioned_docs/version-0.15/92-development/ui-proxy.svg
Normal file
16
docs/versioned_docs/version-0.15/92-development/ui-proxy.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 7.5 KiB |
BIN
docs/versioned_docs/version-0.15/92-development/vscode-debug.png
Normal file
BIN
docs/versioned_docs/version-0.15/92-development/vscode-debug.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
BIN
docs/versioned_docs/version-0.15/woodpecker.png
Normal file
BIN
docs/versioned_docs/version-0.15/woodpecker.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
8
docs/versioned_sidebars/version-0.15-sidebars.json
Normal file
8
docs/versioned_sidebars/version-0.15-sidebars.json
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
{
|
||||
"tutorialSidebar": [
|
||||
{
|
||||
"type": "autogenerated",
|
||||
"dirName": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
3
docs/versions.json
Normal file
3
docs/versions.json
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
[
|
||||
"0.15"
|
||||
]
|
||||
Loading…
Reference in a new issue