foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-21 17:36:59 -05:00
Code Issues Activity

{admin,user}: actions: runner 3.1+ support lxc + self-hosted

Browse source 
The upcoming 3.1 release of the Forgeo runner will allow to specify
which template and release must be must be used for a LXC
container. It also defines the lxc:// scheme as distinct from the
host:// scheme.

The host:// scheme is documented to be used for running jobs directly
from the host, which was not possible with the Forgejo runner versions
prior to 3.1
This commit is contained in:
Earl Warren 2023-11-09 04:29:52 +01:00
parent 7cf8b2fc95
commit 9c0d4b25e5
No known key found for this signature in database
GPG key ID: 0579CB2928A78A00
2 changed files with 46 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

27
docs/admin/actions.md
View file

@ -174,6 +174,11 @@ environment. They need to be installed and configured independently.
> **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.
- **self-hosted:**
There is no requirement for jobs that run directly on the host.
> **Warning:** there is no isolation at all and a single job can permanently destroy the host.
### Registration
The `Forgejo runner` needs to connect to a `Forgejo` instance and must be registered before doing so. It will give it permission to read the repositories and send back information to `Forgejo` such as the logs or its status.
@ -405,11 +410,14 @@ configuration file specified with `--config`. For instance:
```yaml
runner:
labels:
- 'node18:docker://node:18-bookworm'
- 'ubuntu-22.04:docker://ubuntu:22.04'
- 'docker:docker://node:20-bookworm'
- 'node20:docker://node:20-bookworm'
- 'lxc:lxc://debian:bullseye'
- 'bullseye:lxc://debian:bullseye'
- 'self-hosted:host://-self-hosted'
```
will have the `Forgejo runner` declare that it supports the `node18` and `ubuntu-22.04` labels.
will have the `Forgejo runner` declare that it supports the `node20` and `bullseye` labels.
If the list of labels is empty, it defaults to `docker:docker://node:16-bullseye` and will declare the label `docker`.
@ -425,7 +433,18 @@ If the list of labels is empty, it defaults to `docker:docker://node:16-bullseye
See the user documentation for `jobs.<job_id>.container` for more information.
- **LXC:**
If `runs-on` is `self-hosted`, the runner will execute all the steps, as root, within a Debian GNU/Linux `bullseye` LXC container.
If `runs-on` is matched to a label mapped to `lxc://`, the rest of it is interpreted as the default [template and release](https://images.linuxcontainers.org/) to use if no other is specified. The runner will execute all the steps, as root, within a [LXC container](https://linuxcontainers.org/) created from that template and release. The default template is `debian` and the default release is `bullseye`. They can be overridden by a workflow to use `debian` and `bookworm` as follows.
```yaml
runs-on: lxc
container:
image: debian:bookwork
```
See the user documentation for `jobs.<job_id>.container` for more information.
- **self-hosted:**
If `runs-on` is matched to a label mapped to `host://-self-hosted``, the runner will execute all the steps in a shell forked from the runner, directly on the host.
## Packaging

36
docs/user/actions.md
View file

@ -422,23 +422,33 @@ The list of available `labels` for a given repository can be seen in the `/{owne
By default the `docker` label will create a container from a [Node.js 16 Debian GNU/Linux bullseye image](https://hub.docker.com/_/node/tags?name=16-bullseye) and will run each `step` as root. Since an application container is used, the jobs will inherit the limitations imposed by the engine (Docker for instance). In particular they will not be able to run or install software that depends on `systemd`.
The `runs-on: self-hosted` label will run the jobs in a [LXC](https://linuxcontainers.org/lxc/) container where software that rely on `systemd` can be installed. Nested containers can also be created recursively (see [the `setup-forgejo` integration tests](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/.forgejo/workflows/integration.yml) for an example).
The `runs-on: lxc` label will run the jobs in a [LXC](https://linuxcontainers.org/lxc/) container where software that rely on `systemd` can be installed. Nested containers can also be created recursively (see [the `end-to-end` tests](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/.forgejo/workflows/integration.yml) for an example). `Services` are not supported for jobs that run on LXC.
`Services` are not supported for jobs that run on LXC.
The `runs-on: self-hosted` label will run the jobs directly on the host, in a shell spawned from the runner. It provides no isolation at all.
### `jobs.<job_id>.container`
If the default image is unsuitable, a job can specify an alternate container image with `container:`, [as shown in this example](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions/example-container/.forgejo/workflows/test.yml). For instance the following will ensure the job is run using [Alpine 3.18](https://hub.docker.com/_/alpine/tags?name=3.18).
- **Docker or Podman:**
If the default image is unsuitable, a job can specify an alternate container image with `container:`, [as shown in this example](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions/example-container/.forgejo/workflows/test.yml). For instance the following will ensure the job is run using [Alpine 3.18](https://hub.docker.com/_/alpine/tags?name=3.18).
```yaml
runs-on: docker
container:
image: alpine:3.18
## Optionally provide credentials if the registry requires authentication.
#credentials:
# username: "root"
# password: "admin1234"
```
```yaml
runs-on: docker
container:
image: alpine:3.18
## Optionally provide credentials if the registry requires authentication.
#credentials:
# username: "root"
# password: "admin1234"
```
- **LXC:**
If the default [template and release](https://images.linuxcontainers.org/) are unsuitable, a job can specify an alternate template and release as follows.
```yaml
runs-on: lxc
container:
image: debian:bookworm
```
### `jobs.<job_id>.options`
@ -581,7 +591,7 @@ Each example is part of the [setup-forgejo](https://code.forgejo.org/forgejo/end
```sh
$ git clone --depth 1 http://code.forgejo.org/forgejo/end-to-end
$ cd setup-forgejo
$ cd end-to-end
$ forgejo-runner exec --workflows actions/example-expression/.forgejo/workflows/test.yml
INFO[0000] Using the only detected workflow event: push
INFO[0000] Planning jobs for event: push