Add documentation for Forgejo CI Actions runner (#369)
This should solve #318. Helped-by: Linus Groh <mail@linusgroh.de> Reviewed-by: Panagiotis "Ivory" Vasilopoulos <git@n0toose.net> Reviewed-by: Linus Groh <mail@linusgroh.de> Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/369 Co-authored-by: oatbiscuits <oatbiscuits@noreply.codeberg.org> Co-committed-by: oatbiscuits <oatbiscuits@noreply.codeberg.org>
This commit is contained in:
oatbiscuits
Panagiotis "Ivory" Vasilopoulos
parent
1925a19f11
commit
f0408b2c6a
BIN
assets/images/ci/actions/create-new-runner.png
Normal file
BIN
assets/images/ci/actions/create-new-runner.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
assets/images/ci/actions/create-new-runner.webp
Normal file
BIN
assets/images/ci/actions/create-new-runner.webp
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
BIN
assets/images/ci/actions/demo-workflow.png
Normal file
BIN
assets/images/ci/actions/demo-workflow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
BIN
assets/images/ci/actions/demo-workflow.webp
Normal file
BIN
assets/images/ci/actions/demo-workflow.webp
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
306
content/ci/actions.md
Normal file
306
content/ci/actions.md
Normal file
|
|
@ -0,0 +1,306 @@
|
|||
---
|
||||
eleventyNavigation:
|
||||
key: UsingForgejoActions
|
||||
title: Using Forgejo / Gitea Actions (Self-hosted)
|
||||
parent: CI
|
||||
---
|
||||
|
||||
Actions is a continuous integration and continuous delivery (CI/CD) feature that allows you to automate your build, test and deployment pipelines in Forgejo, the software Codeberg uses. It is compatible with GitHub Actions.
|
||||
|
||||
Due to outstanding security issues and bus factor (we need more maintainers for our CI service to get it running),
|
||||
we are currently not yet providing hosted Actions.
|
||||
If you need Codeberg to host your CI, please use Woodpecker CI instead.
|
||||
|
||||
But you can already connect your own Runner to Codeberg.
|
||||
CI jobs will run on your machine, and the result will be displayed in Codeberg.
|
||||
|
||||
This guide will walk you through setting up your own [Forgejo Actions](https://forgejo.org/2023-02-27-forgejo-actions/) Runner to use for CI jobs.
|
||||
|
||||
## Obtaining a registration token
|
||||
|
||||
{% admonition "info" "Make sure to enable actions" %}
|
||||
|
||||
Repository Actions are disabled by default and will require you to enable them in the "Advanced Settings" section of the settings page.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
Before deploying the Runner, you need to obtain a registration token from Codeberg. Registration tokens are used by the Runner and Codeberg to share secrets and configurations.
|
||||
|
||||
You can add Runners to your account, organization, or repository. Choosing where you obtain the registration token will determine where your Runner will accept workflows from.
|
||||
|
||||
1. Go to the account/organization/repository settings page.
|
||||
|
||||
2. Click on Actions.
|
||||
|
||||
3. Click on Runners.
|
||||
|
||||
4. Click on Create new Runner.
|
||||
|
||||
5. Copy the registration token.
|
||||
|
||||
<picture>
|
||||
<source srcset="/assets/images/ci/actions/create-new-runner.webp" type="image/webp">
|
||||
<img src="/assets/images/ci/actions/create-new-runner.png" alt="Create new Runner">
|
||||
</picture>
|
||||
|
||||
|
||||
## Installing Forgejo Runner
|
||||
|
||||
Forgejo Runner is released in both binary and container image (OCI) forms:
|
||||
|
||||
- Download the binary to run on your machine:
|
||||
|
||||
```bash
|
||||
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64
|
||||
$ chmod +x forgejo-runner
|
||||
```
|
||||
|
||||
Make sure to replace `amd64` with `arm64` if your host machine is on ARM.
|
||||
|
||||
- Or download the container image and run it using Docker:
|
||||
|
||||
```bash
|
||||
$ docker run --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner --version
|
||||
forgejo-runner version v3.3.0
|
||||
```
|
||||
|
||||
## Preparing configuration files
|
||||
|
||||
Before you deploy the Runner, you need to generate its configuration files and modify as suited.
|
||||
|
||||
You can generate them to your current directory by either running the binary on host or in a Docker container.
|
||||
|
||||
Make sure to replace `{TOKEN}` with the registration token you copied, and `{NAME}` with any identifier to monitor it on Codeberg.
|
||||
|
||||
### Binary
|
||||
|
||||
```bash
|
||||
$ ./forgejo-runner register --no-interactive --token {TOKEN} --name {NAME} --instance https://codeberg.org
|
||||
INFO Registering runner, arch=amd64, os=linux, version=3.3.0.
|
||||
DEBU Successfully pinged the Forgejo instance server
|
||||
INFO Runner registered successfully.
|
||||
$ ./forgejo-runner generate-config > config.yml
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner register --no-interactive --token {TOKEN} --name {NAME} --instance https://codeberg.org
|
||||
Status: Downloaded newer image for code.forgejo.org/forgejo/runner:3.3.0
|
||||
level=info msg="Registering runner, arch=arm64, os=linux, version=v3.3.0."
|
||||
level=warning msg="Runner in user-mode."
|
||||
level=debug msg="Successfully pinged the Forgejo instance server"
|
||||
level=info msg="Runner registered successfully."
|
||||
$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner generate-config > config.yml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
These commands will generate two files in your current directory:
|
||||
|
||||
- `.runner` which is the configuration file produced when registering the runner.
|
||||
|
||||
- `config.yml` which is the main configuration file with defaults in place you can modify to suit your needs and environment.
|
||||
|
||||
## Deployment Methods
|
||||
|
||||
Depending on your setup and your security needs, there is a wide variety of options for deploying the Runner.
|
||||
|
||||
### Running on Docker
|
||||
|
||||
This method uses the host Docker server by mounting the socket.
|
||||
|
||||
{% admonition "info" "Podman compatibility" %}
|
||||
|
||||
Podman can work by executing:
|
||||
|
||||
```bash
|
||||
$ podman system service -t 0 &
|
||||
|
||||
$ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon
|
||||
```
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
Since this method requires access to the Docker socket, you will need to get the GID of the Docker group (usually `docker`) in your host machine by running:
|
||||
|
||||
```bash
|
||||
$ id | grep -Po '\d+\(docker\)'
|
||||
$ 996(docker)
|
||||
```
|
||||
|
||||
Make sure to replace `996` with the Docker group GID of the host in the following command:
|
||||
|
||||
```bash
|
||||
$ docker run -d -v /var/run/docker.sock:/var/run/docker.sock --user 1000:996 -v $PWD:/data --rm code.forgejo.org/forgejo/runner:3.3.0 forgejo-runner --config config.yml daemon
|
||||
22eae46a021294a213e7f733203f7551250b67367c7507b53b5fd427f0f82d2e
|
||||
```
|
||||
|
||||
Now your CI Runner should be running in a new container.
|
||||
|
||||
#### Running on Docker in Docker
|
||||
|
||||
Using Docker Compose, we can configure the Runner container to execute workflows inside another layer of containers (Docker-in-Docker).
|
||||
|
||||
Here is an example snippet of how it can be configured:
|
||||
|
||||
```yaml
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
docker:
|
||||
image: docker:dind
|
||||
privileged: true
|
||||
volumes:
|
||||
- certs:/certs
|
||||
|
||||
runner:
|
||||
image: code.forgejo.org/forgejo/runner:3.3.0
|
||||
environment:
|
||||
DOCKER_HOST: tcp://docker:2376
|
||||
DOCKER_TLS_VERIFY: 1
|
||||
DOCKER_CERT_PATH: /certs/client
|
||||
volumes:
|
||||
- /opt/forgejo-runner:/data
|
||||
- certs:/certs
|
||||
command: "forgejo-runner --config config.yml daemon"
|
||||
volumes:
|
||||
certs:
|
||||
```
|
||||
|
||||
Make sure to replace `/opt/forgejo-runner` with the directory path of your configuration files.
|
||||
|
||||
### Running on Kubernetes
|
||||
|
||||
{% admonition "warning" "Warning" %}
|
||||
|
||||
Docker in Docker (dind) requires elevated privileges on Kubernetes.
|
||||
|
||||
The current way to achieve this is to set the pod `SecurityContext` to `privileged`.
|
||||
|
||||
Keep in mind that this is a potential security issue that can allow a malicious application to break out of the container context.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
Here is an example snippet of how it can be configured:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
stringData:
|
||||
token: your_registration_token
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: runner-secret
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
labels:
|
||||
app: forgejo-runner
|
||||
name: forgejo-runner
|
||||
spec:
|
||||
replicas: 2
|
||||
selector:
|
||||
matchLabels:
|
||||
app: forgejo-runner
|
||||
strategy: {}
|
||||
template:
|
||||
metadata:
|
||||
creationTimestamp: null
|
||||
labels:
|
||||
app: forgejo-runner
|
||||
spec:
|
||||
restartPolicy: Always
|
||||
volumes:
|
||||
- name: docker-certs
|
||||
emptyDir: {}
|
||||
- name: runner-data
|
||||
emptyDir: {}
|
||||
initContainers:
|
||||
- name: runner-config-generation
|
||||
image: code.forgejo.org/forgejo/runner:3.3.0
|
||||
command: [ "forgejo-runner create-runner-file --instance $FORGEJO_INSTANCE_URL --secret $RUNNER_SECRET --connect" ]
|
||||
env:
|
||||
- name: RUNNER_SECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: runner-secret
|
||||
key: token
|
||||
- name: FORGEJO_INSTANCE_URL
|
||||
value: https://codeberg.org
|
||||
volumeMounts:
|
||||
- name: runner-data
|
||||
mountPath: /data
|
||||
containers:
|
||||
- name: runner
|
||||
image: code.forgejo.org/forgejo/runner:3.3.0
|
||||
command: ["sh", "-c", "while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; forgejo-runner daemon"]
|
||||
env:
|
||||
- name: DOCKER_HOST
|
||||
value: tcp://localhost:2376
|
||||
- name: DOCKER_CERT_PATH
|
||||
value: /certs/client
|
||||
- name: DOCKER_TLS_VERIFY
|
||||
value: "1"
|
||||
volumeMounts:
|
||||
- name: docker-certs
|
||||
mountPath: /certs
|
||||
- name: runner-data
|
||||
mountPath: /data
|
||||
- name: daemon
|
||||
image: docker:dind
|
||||
env:
|
||||
- name: DOCKER_TLS_CERTDIR
|
||||
value: /certs
|
||||
securityContext:
|
||||
privileged: true
|
||||
volumeMounts:
|
||||
- name: docker-certs
|
||||
mountPath: /certs
|
||||
```
|
||||
|
||||
Make sure to replace the value of `token` with your registration token.
|
||||
|
||||
### Running on host machine
|
||||
|
||||
{% admonition "warning" "Warning" %}
|
||||
|
||||
There is no isolation at all and a single job can permanently destroy the host.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
```bash
|
||||
$ ./forgejo-runner --config config.yml daemon
|
||||
INFO[0000-00-00T00:00:00Z] Starting runner daemon
|
||||
```
|
||||
|
||||
Now your CI Runner should running on your host machine.
|
||||
|
||||
## Testing workflows
|
||||
|
||||
To test your CI runner setup, you can use the following demo workflow:
|
||||
|
||||
```yaml
|
||||
on: [push]
|
||||
jobs:
|
||||
test:
|
||||
runs-on: docker
|
||||
steps:
|
||||
- run: echo All Good
|
||||
```
|
||||
|
||||
The runner seeks action recipes from `.forgejo/workflows`, so make sure your file is in the required path.
|
||||
|
||||
<picture>
|
||||
<source srcset="/assets/images/ci/actions/demo-workflow.webp" type="image/webp">
|
||||
<img src="/assets/images/ci/actions/demo-workflow.png" alt="Demo workflow running successfully">
|
||||
</picture>
|
||||
|
||||
## References
|
||||
|
||||
- [Initial announcement blog post by Forgejo](https://forgejo.org/2023-02-27-forgejo-actions/)
|
||||
- [Admin docs for Forgejo 1.20](https://forgejo.org/docs/v1.20/admin/actions/)
|
||||
- [User docs for Forgejo 1.20](https://forgejo.org/docs/v1.20/user/actions/)
|
||||
- [Codeberg Issue tracking the Actions Progress](https://codeberg.org/Codeberg/Community/issues/843)
|
||||
- [Setting up a Self-Hosted Forgejo Actions Runner with Docker Compose](https://linus.dev/posts/setting-up-a-self-hosted-forgejo-actions-runner-with-docker-compose/)
|
||||
|
|
@ -31,19 +31,6 @@ refer to the [Gitea VCS integration section](https://woodpecker-ci.org/docs/admi
|
|||
|
||||
## Using Codeberg / Forgejo / Gitea Actions
|
||||
|
||||
Recently, a GitHub-Actions-compatible feature has been integrated in Forgejo,
|
||||
the software Codeberg uses.
|
||||
Forgejo, the software Codeberg is built on, offers a CI/CD feature called Actions. It offers compatibility with GitHub Actions, [with some differences](https://docs.gitea.com/usage/actions/comparison).
|
||||
|
||||
Due to outstanding security issues and bus factor (we need more maintainers for our CI service to get it running),
|
||||
we are currently not yet providing hosted Actions.
|
||||
If you need Codeberg to host your CI, please use Woodpecker CI instead.
|
||||
|
||||
But you can already connect your own runner to Codeberg.
|
||||
CI jobs will run on your machine, and the result will be displayed in Codeberg.
|
||||
|
||||
Further information is available in the
|
||||
|
||||
- [initial announcement blog post by Forgejo](https://forgejo.org/2023-02-27-forgejo-actions/)
|
||||
- [Admin docs for Forgejo](https://forgejo.org/docs/latest/admin/actions/)
|
||||
- [User docs for Forgejo](https://forgejo.org/docs/latest/user/actions/)
|
||||
- [Codeberg Issue tracking the Actions Progress](https://codeberg.org/Codeberg/Community/issues/843)
|
||||
Further information such as how to run it is available in [Using Forgejo / Gitea Actions (Self-hosted) page](./actions).
|
||||
|
|
|
|||
Loading…
Reference in a new issue