74e8925bec
fix #148 Adds a spell checker via `cspell` and fixes some spelling issues in the docs. Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/439 Co-authored-by: pat-s <patrick.schratz@gmail.com> Co-committed-by: pat-s <patrick.schratz@gmail.com>
311 lines
9.8 KiB
Markdown
311 lines
9.8 KiB
Markdown
---
|
|
eleventyNavigation:
|
|
key: UsingForgejoActions
|
|
title: Using Forgejo 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. For more information, please read [Forgejo's Documentation](https://forgejo.org/docs/latest/user/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.
|
|
DEBUG 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](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)
|
|
- [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/)
|