From 7c031b1b736c26764acc5aab5445a5c48532c563 Mon Sep 17 00:00:00 2001 From: pat-s Date: Tue, 10 Dec 2024 12:15:49 +0100 Subject: [PATCH] chore: rewrite intro pipeline page --- docs/docs/20-usage/10-intro.md | 96 +++++++++++++++++----------------- 1 file changed, 47 insertions(+), 49 deletions(-) diff --git a/docs/docs/20-usage/10-intro.md b/docs/docs/20-usage/10-intro.md index 1c4baec1f..8b036f3c8 100644 --- a/docs/docs/20-usage/10-intro.md +++ b/docs/docs/20-usage/10-intro.md @@ -1,19 +1,20 @@ -# Your first pipeline +# "Hello world" pipeline -Let's get started and create your first pipeline. +Let's get started and create a simple pipeline to demonstrate the pipeline syntax and overall behavior. ## 1. Repository Activation -To activate your repository in Woodpecker navigate to the repository list and `New repository`. You will see a list of repositories from your forge (GitHub, Gitlab, ...) which can be activated with a simple click. +To enable your repository in Woodpecker, navigate to the repository list and select **New Repository**. +You’ll be presented with a list of repositories from your forge (e.g., GitHub, GitLab) that can be activated with a simple click. +Ensure you have administrative rights on the repository in your forge, as Woodpecker needs to add a webhook to detect events like pushes, pull requests, and tags.  ![new repository list](repo-new.png) -To enable a repository in Woodpecker you must have `Admin` rights on that repository, so that Woodpecker can add something -that is called a webhook (Woodpecker needs it to know about actions like pushes, pull requests, tags, etc.). +## 2. The first workflow -## 2. Define first workflow - -After enabling a repository Woodpecker will listen for changes in your repository. When a change is detected, Woodpecker will check for a pipeline configuration. So let's create a file at `.woodpecker/my-first-workflow.yaml` inside your repository: +Once your repository is enabled, Woodpecker starts monitoring it for changes. +When a change is detected, it looks for a pipeline configuration file. +To set up your first workflow, create a file named `.woodpecker/my-first-workflow.yaml` (feel free to change the file name to your liking) in your repository: ```yaml title=".woodpecker/my-first-workflow.yaml" when: @@ -22,12 +23,12 @@ when: steps: - name: build - image: debian + image: debian:latest commands: - echo "This is the build step" - echo "binary-data-123" > executable - - name: a-test-step - image: golang:1.16 + - name: test + image: golang:latest commands: - echo "Testing ..." - ./executable @@ -35,8 +36,7 @@ steps: **So what did we do here?** -1. We defined your first workflow file `my-first-workflow.yaml`. -2. This workflow will be executed when a push event happens on the `main` branch, +1. This workflow will be executed when a `push` event happens on the `main` branch, because we added a filter using the `when` section: ```diff @@ -47,64 +47,62 @@ steps: ... ``` -3. We defined two steps: `build` and `a-test-step` +1. We defined two steps: `build` and `test` -The steps are executed in the order they are defined, so `build` will be executed first and then `a-test-step`. +The steps in your workflow are executed sequentially in the order they are defined. +For instance, the `build` step will run first, followed by the `test` step. -In the `build` step we use the `debian` image and build a "binary file" called `executable`. +- In the `build` step, the workflow uses the debian image to create a binary file named executable. +- In the `test` step, the workflow uses the `golang:latest` image to run the executable file for testing. -In the `a-test-step` we use the `golang:1.16` image and run the `executable` file to test it. - -You can use any image from registries like the [Docker Hub](https://hub.docker.com/search?type=image) you have access to: +You can use any image any registry you have access to. +The most common one is [Docker Hub](https://hub.docker.com/search?type=image). +By default, `docker.io` (=Dockerhub) is used implicitly as the default registry. +If you want to use a different one, you need to prefix the registry explicitly: ```diff steps: - name: build - image: debian -+ image: my-company/image-with-aws_cli - commands: - - aws help ++ image: my-registry/my-company/my-image:latest ``` -## 3. Push the file and trigger first pipeline +## 3. Push the file and trigger the first pipeline -If you push this file to your repository now, Woodpecker will already execute your first pipeline. +If you commit and push this file to your repository, Woodpecker will execute the pipeline. You can check the pipeline execution in the Woodpecker UI by navigating to the `Pipelines` section of your repository. ![pipeline view](./pipeline.png) -As you probably noticed, there is another step in called `clone` which is executed before your steps. This step clones your repository into a folder called `workspace` which is available throughout all steps. - -This for example allows the first step to build your application using your source code and as the second step will receive -the same workspace it can use the previously built binary and test it. +As you probably noticed, there is another step called `clone` which is executed before your steps. +This step is required to initially clone your repository into a directory named `workspace`. +This directory will be available throughout all steps and provide the pipeline access to the files. +As this is always required to get started, Woodpecker adds this step implicitly. +There are ways to [alter/omit this step](./20-workflow-syntax.md#clone) for specific use cases, but this is out-of-scope for getting started. ## 4. Use a plugin for reusable tasks -Sometimes you have some tasks that you need to do in every project. For example, deploying to Kubernetes or sending a Slack message. Therefore you can use one of the [official and community plugins](/plugins) or simply [create your own](./51-plugins/20-creating-plugins.md). +Woodpecker plugins are steps that aim to simplify the execution of frequently used tasks. +They also come with restricted modification functionality, which reduces the potential attack surface, for example by disallowing the use of arbitrary environment variables. +The Woodpecker team maintains a set of official plugins. +In addition, there are many community plugins available from various contributors. +Most can be found in the [Plugin registry](https://woodpecker-ci.org/plugins), but you will surely also find additional ones out in the wild. -If you want to get a Slack notification after your pipeline has finished, you can add a Slack plugin to your pipeline: +If you want to create your own plugin, take a look at our [plugin guide](./51-plugins/20-creating-plugins.md). + +The key differences between plugins and regular steps in Woodpecker are: + +- No `environment:` section: Plugins do not support the use of the `environment:` section for defining environment variables. +- Dedicated `settings:` section: Plugins utilize a specific `settings:` section to configure their options and behavior. ```yaml steps: - # ... - - name: notify me on Slack - image: plugins/slack + - name: Upload to S3 + image: woodpeckerci/plugin-s3:latest settings: - channel: developers - username: woodpecker - password: - from_secret: slack_token - when: - status: [success, failure] # This will execute the step on success and failure + bucket: my-bucket-name + access_key: my-access-key + secret_key: + from_secret: secret_key ``` - -To configure a plugin you can use the `settings` section. - -Sometime you need to provide secrets to the plugin. You can do this by using the `from_secret` key. The secret must be defined in the Woodpecker UI. You can find more information about secrets [here](./40-secrets.md). - -Similar to the `when` section at the top of the file which is for the complete workflow, you can use the `when` section for each step to define when a step should be executed. - -Learn more about [plugins](./51-plugins/51-overview.md). - -As you now have a basic understanding of how to create a pipeline, you can dive deeper into the [workflow syntax](./20-workflow-syntax.md) and [plugins](./51-plugins/51-overview.md).