diff --git a/docs/admin/actions.md b/docs/admin/actions.md index a81bfb98..7d44cb3c 100644 --- a/docs/admin/actions.md +++ b/docs/admin/actions.md @@ -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..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..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 diff --git a/docs/user/actions.md b/docs/user/actions.md index d94c1333..0bfeb8f6 100644 --- a/docs/user/actions.md +++ b/docs/user/actions.md @@ -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..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..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