From 99d169bd3ffc90c721f456b88379cee6bf31258e Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Fri, 30 Aug 2024 17:00:57 +0200 Subject: [PATCH] Move event type descriptions from Terminology to Workflow Syntax (#4062) --- docs/docs/20-usage/15-terminology/index.md | 25 +++++++--------------- docs/docs/20-usage/20-workflow-syntax.md | 11 +++++++++- docs/docs/20-usage/50-environment.md | 4 ++-- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/docs/20-usage/15-terminology/index.md b/docs/docs/20-usage/15-terminology/index.md index f05f18207..0b5eafd8a 100644 --- a/docs/docs/20-usage/15-terminology/index.md +++ b/docs/docs/20-usage/15-terminology/index.md @@ -7,18 +7,18 @@ - **Server**: The component of Woodpecker that handles webhooks from forges, orchestrates agents, and sends status back. It also serves the API and web UI for administration and configuration. - **Agent**: A component of Woodpecker that executes [pipelines][Pipeline] (specifically one or more [workflows][Workflow]) with a specific backend (e.g. [Docker][], Kubernetes, [local][Local]). It connects to the server via GRPC. - **CLI**: The Woodpecker command-line interface (CLI) is a terminal tool used to administer the server, to execute pipelines locally for debugging / testing purposes, and to perform tasks like linting pipelines. -- **Pipeline**: A sequence of [workflows][Workflow] that are executed on the code. [Pipelines][Pipeline] are triggered by events. -- **Workflow**: A sequence of steps and services that are executed as part of a [pipeline][Pipeline]. Workflows are represented by YAML files. Each [workflow][Workflow] has its own isolated [workspace][Workspace], and often additional resources like a shared network (docker). +- **[Pipeline][Pipeline]**: A sequence of [workflows][Workflow] that are executed on the code. Pipelines are triggered by events. +- **[Workflow][Workflow]**: A sequence of steps and services that are executed as part of a [pipeline][Pipeline]. Workflows are represented by YAML files. Each workflow has its own isolated [workspace][Workspace], and often additional resources like a shared network (docker). - **Steps**: Individual commands, actions or tasks within a [workflow][Workflow]. - **Code**: Refers to the files tracked by the version control system used by the [forge][Forge]. - **Repos**: Short for repositories, these are storage locations where code is stored. -- **Forge**: The hosting platform or service where the repositories are hosted. -- **Workspace**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps. -- **Event**: Triggers the execution of a [pipeline][Pipeline], such as a [forge][Forge] event like `push`, or `manual` triggered manually from the UI. +- **[Forge][Forge]**: The hosting platform or service where the repositories are hosted. +- **[Workspace][workspace]**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps. +- **[Event][Event]**: Triggers the execution of a [pipeline][Pipeline], such as a [forge][Forge] event like `push`, or `manual` triggered manually from the UI. - **Commit**: A defined state of the code, usually associated with a version control system like Git. -- **Matrix**: A configuration option that allows the execution of [workflows][Workflow] for each value in the [matrix][Matrix]. +- **[Matrix][Matrix]**: A configuration option that allows the execution of [workflows][Workflow] for each value in the matrix. - **Service**: A service is a step that is executed from the start of a [workflow][Workflow] until its end. It can be accessed by name via the network from other steps within the same [workflow][Workflow]. -- **Plugins**: [Plugins][Plugin] are extensions that provide pre-defined actions or commands for a step in a [workflow][Workflow]. They can be configured via settings. +- **[Plugins][Plugin]**: Plugins are extensions that provide pre-defined actions or commands for a step in a [workflow][Workflow]. They can be configured via settings. - **Container**: A lightweight and isolated environment where commands are executed. - **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. @@ -33,16 +33,6 @@ ![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg) -## Pipeline events - -- `push`: A push event is triggered when a commit is pushed to a branch. -- `pull_request`: A pull request event is triggered when a pull request is opened or a new commit is pushed to it. -- `pull_request_closed`: A pull request closed event is triggered when a pull request is closed or merged. -- `tag`: A tag event is triggered when a tag is pushed. -- `release`: A release event is triggered when a release, pre-release or draft is created. (You can apply further filters using [evaluate](../20-workflow-syntax.md#evaluate) with [environment variables](../50-environment.md#built-in-environment-variables).) -- `manual`: A manual event is triggered when a user manually triggers a pipeline. -- `cron`: A cron event is triggered when a cron job is executed. - ## Conventions Sometimes there are multiple terms that can be used to describe something. This section lists the preferred terms to use in Woodpecker: @@ -54,6 +44,7 @@ Sometimes there are multiple terms that can be used to describe something. This +[Event]: ../20-workflow-syntax.md#event [Pipeline]: ../20-workflow-syntax.md [Workflow]: ../25-workflows.md [Forge]: ../../30-administration/11-forges/11-overview.md diff --git a/docs/docs/20-usage/20-workflow-syntax.md b/docs/docs/20-usage/20-workflow-syntax.md index d50345e6a..204980c2a 100644 --- a/docs/docs/20-usage/20-workflow-syntax.md +++ b/docs/docs/20-usage/20-workflow-syntax.md @@ -288,7 +288,16 @@ when: #### `event` -Available events: `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `deployment`, `cron`, `manual` +The available events are: + +- `push`: triggered when a commit is pushed to a branch. +- `pull_request`: triggered when a pull request is opened or a new commit is pushed to it. +- `pull_request_closed`: triggered when a pull request is closed or merged. +- `tag`: triggered when a tag is pushed. +- `release`: triggered when a release, pre-release or draft is created. (You can apply further filters using [evaluate](#evaluate) with [environment variables](./50-environment.md#built-in-environment-variables).) +- `deployment` (only available for GitHub): triggered when a deployment is created in the repository. +- `cron`: triggered when a cron job is executed. +- `manual`: triggered when a user manually triggers a pipeline. Execute a step if the build event is a `tag`: diff --git a/docs/docs/20-usage/50-environment.md b/docs/docs/20-usage/50-environment.md index f334c09d0..5766faac7 100644 --- a/docs/docs/20-usage/50-environment.md +++ b/docs/docs/20-usage/50-environment.md @@ -81,7 +81,7 @@ This is the reference list of all environment variables available to your pipeli | | **Current pipeline** | | | `CI_PIPELINE_NUMBER` | pipeline number | `8` | | `CI_PIPELINE_PARENT` | number of parent pipeline | `0` | -| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` | +| `CI_PIPELINE_EVENT` | pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` | | `CI_PIPELINE_URL` | link to the web UI for the pipeline | `https://ci.example.com/repos/7/pipeline/8` | | `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline | `https://git.example.com/john-doe/my-repo/commit/eba09b46064473a1d345da7abf28b477468e8dbd` | | `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events | `production` | @@ -115,7 +115,7 @@ This is the reference list of all environment variables available to your pipeli | | **Previous pipeline** | | | `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | `7` | | `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | `0` | -| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` | +| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` | | `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | `https://ci.example.com/repos/7/pipeline/7` | | `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` | | `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events | `production` |