mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-12-23 08:56:29 +00:00
Docs updates and fixes (#3535)
Co-authored-by: Robert Kaussow <xoxys@rknet.org>
This commit is contained in:
qwerty287
GitHub
parent
5de15d84bd
commit
e50cf7ad1e
23 changed files with 54 additions and 29 deletions
|
|
@ -81,7 +81,7 @@ steps:
|
|||
template: config/k8s/service.yaml
|
||||
```
|
||||
|
||||
See [plugin docs](./20-usage/51-plugins/10-overview.md).
|
||||
See [plugin docs](./20-usage/51-plugins/51-overview.md).
|
||||
|
||||
## Continue reading
|
||||
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
|
|
@ -31,7 +31,7 @@
|
|||
- **YAML File**: A file format used to define and configure [workflows][Workflow].
|
||||
- **Dependency**: [Workflows][Workflow] can depend on each other, and if possible, they are executed in parallel.
|
||||
- **Status**: Status refers to the outcome of a step or [workflow][Workflow] after it has been executed, determined by the internal command exit code. At the end of a [workflow][Workflow], its status is sent to the [forge][Forge].
|
||||
- **Service extension**: Some parts of woodpecker internal services like secrets storage or config fetcher can be replaced through service extensions.
|
||||
- **Service extension**: Some parts of Woodpecker internal services like secrets storage or config fetcher can be replaced through service extensions.
|
||||
|
||||
## Pipeline events
|
||||
|
||||
|
|
@ -55,8 +55,8 @@ Sometimes there are multiple terms that can be used to describe something. This
|
|||
|
||||
[Pipeline]: ../20-workflow-syntax.md
|
||||
[Workflow]: ../25-workflows.md
|
||||
[Forge]: ../../30-administration/11-forges/10-overview.md
|
||||
[Plugin]: ../51-plugins/10-overview.md
|
||||
[Forge]: ../../30-administration/11-forges/11-overview.md
|
||||
[Plugin]: ../51-plugins/51-overview.md
|
||||
[Workspace]: ../20-workflow-syntax.md#workspace
|
||||
[Matrix]: ../30-matrix-workflows.md
|
||||
[Docker]: ../../30-administration/22-backends/10-docker.md
|
||||
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
|
@ -188,7 +188,8 @@ Some of the steps may be allowed to fail without causing the whole workflow and
|
|||
|
||||
### `when` - Conditional Execution
|
||||
|
||||
Woodpecker supports defining a list of conditions for a step by using a `when` block. If at least one of the conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped. A condition can be a check like:
|
||||
Woodpecker supports defining a list of conditions for a step by using a `when` block. If at least one of the conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped. A condition is evaluated to true if _all_ subconditions are true.
|
||||
A condition can be a check like:
|
||||
|
||||
```diff
|
||||
steps:
|
||||
|
|
@ -203,6 +204,11 @@ Woodpecker supports defining a list of conditions for a step by using a `when` b
|
|||
+ branch: main
|
||||
```
|
||||
|
||||
The `slack` step is executed if one of these conditions is met:
|
||||
|
||||
1. The pipeline is executed from a pull request in the repo `test/test`
|
||||
2. The pipeline is executed from a push to `maiǹ`
|
||||
|
||||
#### `repo`
|
||||
|
||||
Example conditional execution by repository:
|
||||
|
|
@ -652,7 +658,7 @@ Example configuration to use a custom clone plugin:
|
|||
|
||||
```diff
|
||||
clone:
|
||||
git:
|
||||
- name: git
|
||||
+ image: octocat/custom-git-plugin
|
||||
```
|
||||
|
||||
|
|
@ -702,7 +708,7 @@ skip_clone: true
|
|||
|
||||
## `when` - Global workflow conditions
|
||||
|
||||
Woodpecker gives the ability to skip whole workflows (not just steps #when---conditional-execution-1) based on certain conditions by a `when` block. If all conditions in the `when` block evaluate to true the workflow is executed, otherwise it is skipped, but treated as successful and other workflows depending on it will still continue.
|
||||
Woodpecker gives the ability to skip whole workflows ([not just steps](#when---conditional-execution)) based on certain conditions by a `when` block. If all conditions in the `when` block evaluate to true the workflow is executed, otherwise it is skipped, but treated as successful and other workflows depending on it will still continue.
|
||||
|
||||
For more information about the specific filters, take a look at the [step-specific `when` filters](#when---conditional-execution).
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpeck
|
|||
|
||||
:::warning
|
||||
Please note that files are only shared between steps of the same workflow (see [File changes are incremental](./20-workflow-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` workflow in the `deploy` workflow.
|
||||
If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/10-overview.md) (e.g. one which stores files in an Amazon S3 bucket).
|
||||
If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/51-overview.md) (e.g. one which stores files in an Amazon S3 bucket).
|
||||
:::
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ To configure cron jobs you need at least push access to the repository.
|
|||
+ cron: "name of the cron job" # if you only want to execute this step by a specific cron job
|
||||
```
|
||||
|
||||
1. Create a new cron job in the repository settings:
|
||||
2. Create a new cron job in the repository settings:
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -81,7 +81,7 @@ This is the reference list of all environment variables available to your pipeli
|
|||
| | **Current pipeline** |
|
||||
| `CI_PIPELINE_NUMBER` | pipeline number |
|
||||
| `CI_PIPELINE_PARENT` | number of parent pipeline |
|
||||
| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) |
|
||||
| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) |
|
||||
| `CI_PIPELINE_URL` | link to the web UI for the pipeline |
|
||||
| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline |
|
||||
| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events (i.e. production) |
|
||||
|
|
@ -114,7 +114,7 @@ This is the reference list of all environment variables available to your pipeli
|
|||
| | **Previous pipeline** |
|
||||
| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number |
|
||||
| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline |
|
||||
| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) |
|
||||
| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) |
|
||||
| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI |
|
||||
| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge |
|
||||
| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events (ie production) |
|
||||
|
|
|
|||
|
|
@ -48,6 +48,23 @@ Secrets should be passed as settings too. Therefore, users should use [`from_sec
|
|||
|
||||
For Go, we provide a plugin library you can use to get easy access to internal env vars and your settings. See <https://codeberg.org/woodpecker-plugins/go-plugin>.
|
||||
|
||||
## Metadata
|
||||
|
||||
In your documentation, you can use a Markdown header to define metadata for your plugin. This data is used by [our plugin index](/plugins).
|
||||
|
||||
Supported metadata:
|
||||
|
||||
- `name`: The plugin's full name
|
||||
- `icon`: URL to your plugin's icon
|
||||
- `description`: A short description of what it's doing
|
||||
- `author`: Your name
|
||||
- `tags`: List of keywords (e.g. `[git, clone]` for the clone plugin)
|
||||
- `containerImage`: name of the container image
|
||||
- `containerImageUrl`: link to the container image
|
||||
- `url`: homepage or repository of your plugin
|
||||
|
||||
If you want your plugin to be listed in the index, you should add as many fields as possible, but only `name` is required.
|
||||
|
||||
## Example plugin
|
||||
|
||||
This provides a brief tutorial for creating a Woodpecker webhook plugin, using simple shell scripting, to make HTTP requests during the build pipeline.
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ You can install Woodpecker on multiple ways:
|
|||
|
||||
Authentication is done using OAuth and is delegated to your forge which is configured using environment variables.
|
||||
|
||||
See the complete reference for all supported forges [here](../11-forges/10-overview.md).
|
||||
See the complete reference for all supported forges [here](../11-forges/11-overview.md).
|
||||
|
||||
## Database
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# NixOS
|
||||
|
||||
:::info
|
||||
Note that this module is not maintained by the woodpecker-developers.
|
||||
Note that this module is not maintained by the Woodpecker developers.
|
||||
If you experience issues please open a bug report in the [nixpkgs repo](https://github.com/NixOS/nixpkgs/issues/new/choose) where the module is maintained.
|
||||
:::
|
||||
|
||||
|
|
@ -85,4 +85,4 @@ All configuration options can be found via [NixOS Search](https://search.nixos.o
|
|||
|
||||
## Tips and tricks
|
||||
|
||||
There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline
|
||||
There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ toc_max_heading_level: 2
|
|||
|
||||
## User registration
|
||||
|
||||
Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/10-overview.md) (using OAuth2).
|
||||
Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/11-overview.md) (using OAuth2).
|
||||
|
||||
Registration is closed by default (`WOODPECKER_OPEN=false`). If registration is open (`WOODPECKER_OPEN=true`) then every user with an account at the configured forge can login to Woodpecker.
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ To handle sensitive data in docker-compose or docker-swarm configurations there
|
|||
|
||||
For docker-compose you can use a `.env` file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure.
|
||||
|
||||
Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables woodpecker allows to read sensible data from files by providing a `*_FILE` option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file.
|
||||
Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables Woodpecker allows to read sensible data from files by providing a `*_FILE` option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file.
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
version: '3'
|
||||
|
|
@ -477,7 +477,7 @@ Supported variables:
|
|||
|
||||
> Default: empty
|
||||
|
||||
List of addon files. See [addons](./75-addons/00-overview.md).
|
||||
List of addon files. See [addons](./75-addons/75-overview.md).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ WOODPECKER_GITEA_SECRET=YOUR_GITEA_CLIENT_SECRET
|
|||
## Gitea on the same host with containers
|
||||
|
||||
If you have Gitea also running on the same host within a container, make sure the agent does have access to it.
|
||||
The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the woodpecker agent to the same docker network as Gitea is in.
|
||||
The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the Woodpecker agent to the same docker network as Gitea is in.
|
||||
Otherwise, the communication should go via the `docker0` gateway (usually 172.17.0.1).
|
||||
|
||||
To configure the Docker network if the network's name is `gitea`, configure it like this:
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ WOODPECKER_BITBUCKET_SECRET=...
|
|||
|
||||
## Registration
|
||||
|
||||
You must register an OAuth application at Bitbucket in order to get a key and secret combination for woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`).
|
||||
You must register an OAuth application at Bitbucket in order to get a key and secret combination for Woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`).
|
||||
|
||||
Please set a name and set the `Callback URL` like this:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Awesome Woodpecker
|
||||
|
||||
A curated list of awesome things related to Woodpecker-CI.
|
||||
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/main/docs/docs/92-awesome.md) and add them.
|
||||
|
||||
|
|
@ -14,7 +14,7 @@ If you have some missing resources, please feel free to [open a pull-request](ht
|
|||
|
||||
## Projects using Woodpecker
|
||||
|
||||
- [Woodpecker-CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself
|
||||
- [Woodpecker CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself
|
||||
- [All official plugins](https://github.com/woodpecker-ci?q=plugin&type=all)
|
||||
- [dessalines/thumb-key](https://github.com/dessalines/thumb-key/blob/main/.woodpecker.yml) - Android Jetpack compose linting and building
|
||||
- [Vieter](https://git.rustybever.be/vieter-v/vieter) - Archlinux/Pacman repository server & automated package build system
|
||||
|
|
@ -24,12 +24,12 @@ If you have some missing resources, please feel free to [open a pull-request](ht
|
|||
## Tools
|
||||
|
||||
- [Convert Drone CI pipelines to Woodpecker CI](https://codeberg.org/lafriks/woodpecker-pipeline-transform)
|
||||
- [Ansible NAS](https://github.com/davestephens/ansible-nas/) - a homelab Ansible playbook that can set up Woodpecker-CI and Gitea
|
||||
- [Ansible NAS](https://github.com/davestephens/ansible-nas/) - a homelab Ansible playbook that can set up Woodpecker CI and Gitea
|
||||
- [picus](https://github.com/windsource/picus) - Picus connects to a Woodpecker CI server and creates an agent in the cloud when there are pending workflows.
|
||||
- [Hetzner cloud](https://www.hetzner.com/cloud) based [Woodpecker compatible autoscaler](https://git.ljoonal.xyz/ljoonal/hetzner-ci-autoscaler) - Creates and destroys VPS instances based on the count of pending & running jobs.
|
||||
- [woodpecker-lint](https://git.schmidl.dev/schtobia/woodpecker-lint) - A repository for linting a woodpecker config file via pre-commit hook
|
||||
- [Grafana Dashboard](https://github.com/Janik-Haag/woodpecker-grafana-dashboard) - A dashboard visualizing information exposed by the woodpecker prometheus endpoint.
|
||||
- [woodpecker-autoscaler](https://github.com/Lerentis/woodpecker-autoscaler) - Yet another woodpecker autoscaler currently targeting [Hetzner cloud](https://www.hetzner.com/cloud) that works in parallel to other autoscaler implementations.
|
||||
- [woodpecker-lint](https://git.schmidl.dev/schtobia/woodpecker-lint) - A repository for linting a Woodpecker config file via pre-commit hook
|
||||
- [Grafana Dashboard](https://github.com/Janik-Haag/woodpecker-grafana-dashboard) - A dashboard visualizing information exposed by the Woodpecker prometheus endpoint.
|
||||
- [woodpecker-autoscaler](https://github.com/Lerentis/woodpecker-autoscaler) - Yet another Woodpecker autoscaler currently targeting [Hetzner cloud](https://www.hetzner.com/cloud) that works in parallel to other autoscaler implementations.
|
||||
|
||||
## Configuration Services
|
||||
|
||||
|
|
@ -50,8 +50,10 @@ If you have some missing resources, please feel free to [open a pull-request](ht
|
|||
- [Locally Cached Nix CI with Woodpecker](https://blog.kotatsu.dev/posts/2023-04-21-woodpecker-nix-caching/)
|
||||
- [How to run Cypress auto-tests on Woodpecker CI and report results to Slack](https://devforth.io/blog/how-to-run-cypress-auto-tests-on-woodpecker-ci-and-report-results-to-slack/)
|
||||
- [Quest For CICD - WoodpeckerCI](https://omaramin.me/posts/woodpecker/)
|
||||
- [Getting started with Woodpecker CI](https://blog.lutra-it.eu/getting-started-with-woodpecker-ci.html)
|
||||
- [Getting started with Woodpecker CI](https://systeemkabouter.eu/getting-started-with-woodpecker-ci.html)
|
||||
- [Installing gitea and woodpecker using binary packages](https://neelex.com/2023/03/26/Installing-gitea-using-binary-packages/)
|
||||
- [Deploying mdbook to codeberg pages using woodpecker CI](https://www.markpitblado.me/blog/ci-deployment-of-mdbook)
|
||||
- [Deploy a Fly app with Woodpecker CI](https://joeroe.io/2024/01/09/deploy-fly-woodpecker-ci.html)
|
||||
|
||||
## Videos
|
||||
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ WOODPECKER_HEALTHCHECK=false
|
|||
|
||||
### Setup OAuth
|
||||
|
||||
Create an OAuth app for your forge as described 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.
|
||||
Create an OAuth app for your forge as described in the [forges documentation](../30-administration/11-forges/11-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
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
## Addons and extensions
|
||||
|
||||
If you are wondering whether your contribution will be accepted to be merged in the Woodpecker core, or whether it's better to write an
|
||||
[addon](../30-administration/75-addons/00-overview.md), [extension](../30-administration/100-external-configuration-api.md) or an
|
||||
[addon](../30-administration/75-addons/75-overview.md), [extension](../30-administration/100-external-configuration-api.md) or an
|
||||
[external custom backend](../30-administration/22-backends/50-custom-backends.md), please check these points:
|
||||
|
||||
- Is your change very specific to your setup and unlikely to be used by anyone else?
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ async function loadContent(): Promise<Content> {
|
|||
}
|
||||
|
||||
return <WoodpeckerPlugin>{
|
||||
name: docsHeader.name || i.name,
|
||||
name: docsHeader.name,
|
||||
url: docsHeader.url,
|
||||
icon: docsHeader.icon,
|
||||
description: docsHeader.description,
|
||||
|
|
|
|||
Loading…
Reference in a new issue