mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-12-27 19:00:35 +00:00
Code Issues Projects Releases Wiki Activity

chore: rewrite intro pipeline page

Browse source
This commit is contained in:
pat-s 2024-12-10 12:15:49 +01:00
parent fee25583b0
commit 7c031b1b73
No known key found for this signature in database
GPG key ID: 3C6318841EF78925
1 changed files with 47 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
docs/docs/20-usage/10-intro.md
View file

@ -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).