You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Continuous Integration (CI) tools are vital for automating the testing and deployment of modern software. One such open-source tool is Woodpecker CI, a lightweight CI/CD system. Woodpecker CI is an open-source continuous integration and delivery platform that helps developers automate building, testing, and deploying their code. It is a community-driven fork and successor of the popular Drone CI project, sharing many design principles and compatibility with Drone pipelines. Traditionally, Woodpecker pipelines are written in YAML. But with the rise of programmable pipelines, we now have the flexibility to define our CI configuration using Starlark — a Python-like configuration language.
12
+
Continuous Integration tools are essential to build and test modern software automatically and regularly. Woodpecker CI is one such open-source tool, a lightweight CI/CD system. [Woodpecker CI](https://woodpecker-ci.org/) is an open-source continuous integration and delivery system that help developers in automating deployment, builds, and testing of code. It's an open-source fork and alternative to the popular Drone CI project with numerous design similarities and Drone pipeline compatibility. Traditionally, Woodpecker pipelines are YAML, but now that programmable pipelines are in vogue, we can finally have the liberty of defining our CI configuration through Starlark — a Python-ish config language.
13
13
14
-
In this blog, I’ll walk you through setting up Woodpecker CI with Traefik as a reverse proxy and integrating it with WCCS (Woodpecker CI Config Service) to convert Starlark configurations into YAML files, enabling us to write pipelines in .woodpecker.star files. Here's a high-level view of what we'll cover:
14
+
In this article, I will walk you through setting up Woodpecker CI with Traefik as a reverse proxy and [WCCS](https://github.com/opencloud-eu/woodpecker-ci-config-service/) (Woodpecker CI Config Service) to convert Starlark configurations into YAML files so that we can write pipelines in `.star` files. Here is a high-level overview of what we are going through:
15
15
16
16
- Spinning up a Woodpecker server with Traefik
17
17
@@ -23,31 +23,59 @@ In this blog, I’ll walk you through setting up Woodpecker CI with Traefik as a
23
23
24
24
By the end, you’ll be able to write CI pipelines in Starlark and dynamically convert them to YAML during runtime.
25
25
26
-
## Prepare Woodpecker secrets via .env
27
-
```console
28
-
#Your woodpecker host
29
-
WOODPECKER_HOST=https://<your-ci-server>
30
-
31
-
32
-
# GitHub OAuth Secrets
33
-
WOODPECKER_GITHUB_CLIENT=XXXXXXXXXXXXXXXX
34
-
WOODPECKER_GITHUB_SECRET=XXXXXXXXXXXXXXXXXXXXXXXX
26
+
## Setting Up Woodpecker Server and Agent
27
+
Let's start by setting up the Woodpecker server and agent services in the `docker-compose.yml` file as show below:
35
28
29
+
```yml
30
+
services:
31
+
woodpecker-server:
32
+
image: woodpeckerci/woodpecker-server:v3
33
+
environment:
34
+
- WOODPECKER_LOG_LEVEL=debug
35
+
- WOODPECKER_OPEN=false
36
+
- WOODPECKER_HOST=http://<your-ci-server>
37
+
- WOODPECKER_GITHUB=true
38
+
- WOODPECKER_GITHUB_CLIENT=xxxxxxx # GitHub OAuth client ID
Woodpecker cannot do anything by itself, it needs a forge (the service where the repositories are hosted). Woodpecker supports [various forges](https://woodpecker-ci.org/docs/administration/configuration/forges/overview), for this blog we will focus on GitHub.
147
+
136
148
To connect GitHub with Woodpecker:
137
149
138
-
1. Register a new OAuth application in your GitHub developer settings.
150
+
1. Register a new OAuth application in your GitHub developer [settings](https://github.com/settings/applications/new).
151
+
152
+
2. In your GitHub OAuth App, set the authorization callback URL to `https://<your-ci-server>/authorize`
139
153
140
-
2. Set the callback URL to `https://<your-ci-server>/authorize`
Before enabling a repo in the Woodpecker CI server, make sure to have a GitHub repository ready. You can use an existing repo of your own or create a new empty one. We will be making a pull request to the repo to trigger CI later.
- Enable it. For this blog, I am using an existing repo called `Drum-KIT` which has already been enabled (as you can see in the last row of the image below).
- Then, add `.woodpecker.star` as pipeline config path and save it:
199
+
Now that you have your `.woodpecker.yaml` file ready, you can commit and push it to your enabled GitHub repository and then, open a Pull Request from your branch <your-branch-name> to `master/main` according to you repo. GitHub's default branch is set to `main`.
200
+
Once the PR is created, Woodpecker will automatically fetch the pipeline configuration, and start your first CI run. You can then head over to the Woodpecker UI to watch the build logs in real time.
Every request sent by Woodpecker is signed using a http-signature by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from:
176
-
```console
177
-
http(s)://your-ci-server/api/signature/public-key
178
-
```
179
-
Store that public key into `keys/public.pem` in the same directory level as your docker compose, it will be needed for signature verification.
204
+
Now that we have already set up the woodpecker server and triggered pipelines using the traditional `.yaml` configuration, let's now integrate WCCS to unlock flexibility and define our pipelines in Starlark.
180
205
181
206
## Setting Up WCCS-Woodpecker CI Config Service (Starlark Conversion Service)
182
207
The Woodpecker Config Conversion Service (WCCS) is a lightweight web service created and maintained by [Opencloud-eu](https://opencloud.eu/en). It enables Woodpecker CI to convert pipeline definitions written in Starlark into standard YAML on the fly by receiving a signed POST request from Woodpecker.
183
208
You can easily deploy WCCS using their official Docker image available on Docker Hub: [opencloudeu/wccs](https://hub.docker.com/r/opencloudeu/wccs).
209
+
Update your `docker-compose.yml` to include the WCCS service:
184
210
```yml
211
+
...
212
+
185
213
wccs:
186
214
image: opencloudeu/wccs:latest
187
215
container_name: wccs
188
216
command: server
189
217
environment:
190
218
- WCCS_LOG_LEVEL=debug
191
-
- WCCS_SERVER_PUBLIC_KEY=/keys/public.pem
219
+
- WCCS_SERVER_PUBLIC_KEY=/keys/public.pem# path to public key(generated in the section below)
192
220
volumes:
193
221
- /opt/woodpecker/keys:/keys
194
222
- /etc/ssl/certs:/etc/ssl/certs:ro
@@ -201,6 +229,8 @@ You can easily deploy WCCS using their official Docker image available on Docker
201
229
networks:
202
230
- woodpecker-net
203
231
232
+
...
233
+
204
234
volumes:
205
235
woodpecker-server-data:
206
236
woodpecker-agent-config:
@@ -210,15 +240,38 @@ networks:
210
240
driver: bridge
211
241
```
212
242
243
+
## Generating the Public Key
244
+
Before running any pipeline, woodpecker server sends a POST request to an external config service (in our case WCCS) with all current config file and build information of the current repository. The external service takes the information and sends back the pipeline configurations. In our case, this is how a starlark file is being converted into yaml configurations.
245
+
246
+
And before WCCS can accept and process those requests, it needs to verify that the requests are trusted and coming from the woodpecker server.
247
+
248
+
Every request sent by Woodpecker is signed using a http-signature by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from:
249
+
```console
250
+
https://<your-ci-server>/api/signature/public-key
251
+
```
252
+
Store that public key into `keys/public.pem` in the same directory level as your docker compose. The `public.pem` file is then mounted to the WCCS container as shown in the snippet above and used in env variable `WCCS_SERVER_PUBLIC_KEY`
253
+
213
254
## Connecting WCCS with Woodpecker
214
255
To allow Woodpecker to fetch pipeline configs from WCCS, we added this to the server env:
Woodpecker now sends a signed JSON payload to WCCS whenever a build is triggered. WCCS verifies the signature using the public key and responds with a YAML pipeline based on your .woodpecker.star file.
259
+
Woodpecker now sends a signed JSON payload to WCCS whenever a build is triggered. WCCS verifies the signature using the public key and responds with a YAML pipeline based on your `.woodpecker.star` file.
260
+
261
+
After conneting WCCS with the woodpecker server, there's one more thing that you need to do i.e. to set pipeline config path, because by default Woodpecker will take `.woodpecker.yaml` as it's pipeline configuration.
262
+
263
+
- From the settings of your Woodpecker server, go to `Repositories` and click on the enabled repo's settings icon as shown below:
Here's a simple `.woodpecker.star` example that you can add in your project's root and you're all set:
272
+
Here's a simple starlark pipeline configuration example that you can add in your project.
273
+
Create a new branch by checking out from your `master/main` branch.
274
+
Add the following configration in the `.woodpecker.star` file in your repo's root
222
275
```console
223
276
def main(ctx):
224
277
return [{
@@ -232,16 +285,16 @@ def main(ctx):
232
285
],
233
286
"when": {
234
287
"event": ["push", "pull_request"],
235
-
"branch": ["master"],
288
+
"branch": ["master"], # configure it as your repo's base branch.(in my case, it's `master`)
236
289
},
237
290
}
238
291
]
239
292
}]
240
293
```
241
294
242
-
## Triggering Your First CI Run
243
-
Now that you have your `.woodpecker.star` file ready, commit and push it to your GitHub repository and then, open a Pull Request from your branch <your-branch-name> to master.
244
-
Once the PR is created, Woodpecker will automatically send the build request to WCCS, fetch the pipeline config, and start your first CI run. You can head over to the Woodpecker UI to watch the build logs in real time.
295
+
## Triggering CI with starlark-powered pipeline
296
+
Now that you have your `.woodpecker.star` file ready, commit and push it to your GitHub repository and then, open a new Pull Request from your branch <your-branch-name> to master/main.
297
+
Once the PR is created, Woodpecker will automatically send a build request to WCCS, fetch the pipeline configuration, and start your first CI run. You can then head over to the Woodpecker UI to watch the build logs in real time.
0 commit comments