foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-24 18:09:26 -05:00
Code Issues Activity

provide details on the Docker & LXC requirements

Browse source
This commit is contained in:
Earl Warren 2023-05-29 09:57:48 +02:00 committed by Caesar Schinas
parent 014bade547
commit 8b6b61054c
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
1 changed files with 42 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
admin/actions.md
View file

@ -4,35 +4,59 @@ title: 'Forgejo Actions'
license: 'CC-BY-SA-4.0'
---
`Forgejo Actions` provides continuous integration driven from the files in the `.forgejo/workflows` directory of a repository. It is still experimental and disabled by default and can be activated by adding the following to `app.ini`:
`Forgejo Actions` provides continuous integration driven from the files in the `.forgejo/workflows` directory of a repository. It is still experimental and disabled by default. It can be activated by adding the following to `app.ini`:
```yaml
[actions]
ENABLED = true
```
Forgejo does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so.
`Forgejo` itself does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so.
# Forgejo runner
## Installation
Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) into `/usr/local/bin/forgejo-runner` and change its permissions with `chmod +x /usr/local/bin/forgejo-runner`.
The binaries are signed and should be verified to match with the following :
Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) and verify their signature:
```shell
$ wget https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64
$ wget https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64.asc
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64
$ chmod +x forgejo-runner
$ wget -O forgejo-runner.asc https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64.asc
$ gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
$ gpg --verify forgejo-runner-amd64.asc forgejo-runner-amd64
$ gpg --verify forgejo-runner.asc forgejo-runner
Good signature from "Forgejo <contact@forgejo.org>"
aka "Forgejo Releases <release@forgejo.org>"
```
### Docker
For jobs to run in containers, the `Forgejo runner` needs access to [Docker](https://docs.docker.com/engine/install/).
### LXC
For jobs to run in LXC containers, the `Forgejo runner` needs passwordless sudo access on a Debian GNU/Linux bookworm system where [LXC](https://linuxcontainers.org/lxc/) is installed. The [LXC helpers](https://code.forgejo.org/forgejo/lxc-helpers/) can be used as follows to create a suitable container:
```shell
$ git clone https://code.forgejo.org/forgejo/lxc-helpers
$ ./lxc-helpers/lxc-helpers.sh lxc_container_create myrunner
$ ./lxc-helpers/lxc-helpers.sh lxc_container_start myrunner
```
The `Forgejo runner` can then be installed and run within the `myrunner` container.
```shell
$ ./lxc-helpers/lxc-helpers.sh lxc_container_run bash
# apt-get install docker.io wget gnupg2
# wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64
...
```
**Warning:** LXC containers do not provide a level of security that makes them safe for potentially malicious users to run jobs. They provide an excellent isolation for jobs that may accidentally damage the system they run on.
## Registration
The runner is driven by a Forgejo instance and must register itself. It will be given permission to read the repositories and send back information to Forgejo such as the logs or its status. A special kind of token is needed and can be obtained from the `Create new runner` button:
The `Forgejo runner` needs to connect to a `Forgejo` instance and must register itself before doing so. It will be given permission to read the repositories and send back information to `Forgejo` such as the logs or its status. A special kind of token is needed and can be obtained from the `Create new runner` button:
- in `/admin/runners` to gain access to all repositories.
- in `/{owner}/{repository}/settings/actions/runners` to gain access to a single repository.
@ -40,7 +64,7 @@ The runner is driven by a Forgejo instance and must register itself. It will be
For instance, using a token obtained for a test repository from `next.forgejo.org`:
```shell
forgejo-runner-amd64 register --no-interactive --token {TOKEN} --name runner --instance https://next.forgejo.org --labels ubuntu-latest:docker://node:16-buster,self-hosted
forgejo-runner register --no-interactive --token {TOKEN} --name runner --instance https://next.forgejo.org --labels ubuntu-latest:docker://node:16-buster,self-hosted
INFO Registering runner, arch=amd64, os=linux, version=2.0.3.
WARN Runner in user-mode.
DEBU Successfully pinged the Forgejo instance server
@ -51,7 +75,7 @@ It will create a `.runner` file that looks like:
```json
{
"WARNING": "This file is automatically generated. Do not edit it manually unless you know what you are doing.",
"WARNING": "This file is automatically generated. Do not edit.",
"id": 6,
"uuid": "fcd0095a-291c-420c-9de7-965e2ebaa3e8",
"name": "runner",
@ -63,10 +87,10 @@ It will create a `.runner` file that looks like:
## Running
Once Forgejo runner is successfully registered, it can be run from the directory in which the `.runner` file is found with:
Once the `Forgejo runner` is successfully registered, it can be run from the directory in which the `.runner` file is found with:
```shell
$ forgejo-runner-amd64 daemon
$ forgejo-runner daemon
INFO[0000] Starting runner daemon
```
@ -81,7 +105,7 @@ jobs:
- run: echo All Good
```
Will send a job request to the runner that will show logs such as:
Will send a job request to the `Forgejo runner` that will display logs such as:
```shell
...
@ -92,13 +116,13 @@ INFO[2023-05-28T18:54:53+02:00] task 29 repo is earl-warren/test https://code.fo
[/test] ✅ Success - Main echo All Good
```
It will also show in the `Actions` tab of the repository.
It will also show a similar output in the `Actions` tab of the repository.
If no runner is available, Forgejo will wait for it and submit the job as soon as it connects.
If no `Forgejo runner` is available, `Forgejo` will wait for one to connect and submit the job as soon as it is available.
## Job environment
The jobs defined in the files found in `.forgejo/workflows` specify the environment they need with `runs-on`. Each runner declares, with the `--labels` option` which one they support so Forgejo knows to submit jobs accordingly. For instance if a job has:
The jobs defined in the files found in `.forgejo/workflows` specify the environment they need to run with `runs-on`. Each `Forgejo runner` declares, with the `--labels` option, which one they support so `Forgejo` knows to submit jobs accordingly. For instance if a job has:
```yaml
runs-on: ubuntu-latest
@ -108,7 +132,7 @@ the job will be submitted to a runner that registered with `--labels ubuntu-late
### Docker
If `runs-on` matches a label that starts with `docker://`, the rest of it is interpreted as a container image. The runner will execute all the steps, as root, within a container created from that image.
If `runs-on` is matched to a label that contains `docker://`, the rest of it is interpreted as a container image. The runner will execute all the steps, as root, within a container created from that image.
### LXC