docs: Rewrite entry and "first pipeline" page #4550
Draft
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Deployment of preview was successful: https://woodpecker-ci-woodpecker-pr-4550.surge.sh |
zc-devs
reviewed
Dec 10, 2024
| @@ -1,26 +1,33 @@ | |||
| # Welcome to Woodpecker | |||
|
|
|||
| Woodpecker is a CI/CD tool. It is designed to be lightweight, simple to use and fast. Before we dive into the details, let's have a look at some of the basics. | |||
| Woodpecker is a CI/CD tool. It is designed to be lightweight (< 200 MB memory consumption), simple to use and fast and can be used with many different Git providers and backends (docker, kubernetes, local). | |||
There was a problem hiding this comment.
(< 200 MB memory consumption)
(docker, kubernetes, local)
Not sure if such details should be in the welcome message.
Also it is a generalized duplication of hardware requirements from a dedicated page. Moreover, there it is a lower boundary and here it's an upper boundary like.
|
|
||
| Don't worry if you haven't. We'll guide you through the basics. CI/CD stands for Continuous Integration and Continuous Deployment. It's basically like a conveyor belt that moves your code from development to production doing all kinds of | ||
| checks, tests and routines along the way. A typical pipeline might include the following steps: | ||
| CI/CD stands for "Continuous Integration” and “Continuous Deployment.” |
There was a problem hiding this comment.
Suggested change
| CI/CD stands for "Continuous Integration” and “Continuous Deployment.” | |
| CI/CD stands for "Continuous Integration” and “Continuous Delivery (Deployment)”. |
| ## Getting started | ||
|
|
||
| Woodpecker is [pretty lightweight](../30-administration/00-getting-started.md#hardware-requirements) and can even run on a Raspberry Pi without much impact. | ||
| To set up your own Woodpecker instance, follow the [deployment guide](../30-administration/00-getting-started.md). |
There was a problem hiding this comment.
Missed Already have access to a Woodpecker instance? link.
Missed (which was here before) learning path for those, who do not need to deploy an instance.
| @@ -1,19 +1,20 @@ | |||
| # Your first pipeline | |||
| # "Hello world" | |||
There was a problem hiding this comment.
Suggested change
| # "Hello world" | |
| # Your first pipeline AKA "Hello world" |
| 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.  |
There was a problem hiding this comment.
Suggested change
| 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.  | |
| 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. |
| 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`. |
There was a problem hiding this comment.
Suggested change
| This step is required to initially clone your repository into a directory named `workspace`. | |
| This step is required to initially clone your repository into a directory called `workspace`. |
https://woodpecker-ci.org/docs/2.7/usage/workflow-syntax#workspace
| 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 was a problem hiding this comment.
Suggested change
| As this is always required to get started, Woodpecker adds this step implicitly. | |
| As this is often required to get started, Woodpecker adds this step implicitly. |
|
|
||
| ## 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. |
There was a problem hiding this comment.
modification functionality
Do not understand this. Do they run with readOnlyRootFilesystem?
Do not understand, how envs are related to the "modification functionality".
|
|
||
| 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: |
There was a problem hiding this comment.
Should it be in the intro page? I think it better suits in dedicated Plugins page with details.
| bucket: my-bucket-name | ||
| access_key: my-access-key | ||
| secret_key: | ||
| from_secret: secret_key |
There was a problem hiding this comment.
There were some explanation like and links to other chapters.
Open
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Yes, many subjective changes.
To keep the review somehow manageable, it would be great to focus on high-level comments and explicit wrong statements and try to refrain from comments like "XY is missing, please add" etc. (-> these can be added in new PRs).
Quite some information was wrong or outdated in these pages. This should now all be fixed.