admin: actions: rework and introduce OCI images

docs/admin/actions.md

@@ -3,18 +3,26 @@ title: 'Forgejo Actions administrator guide'
 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 in beta and disabled by default. It can be activated by adding the following to `app.ini`:
+`Forgejo Actions` provides continuous integration driven from the files found in the `.forgejo/workflows` directory of a repository.
+
+## Forgejo settings
+
+### Enabling
+
+`Forgejo Actions` is still in alpha and disabled by default. It can be activated by adding the following to `app.ini`:
 
 ```yaml
 [actions]
 ENABLED = true
 ```
 
-`Forgejo` itself does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so.
+Note that `Forgejo` does not run the jobs, it relies on the [`Forgejo
+runner`](https://code.forgejo.org/forgejo/runner) to do so. It needs
+to be installed separately.
 
-## Default Actions URL
+### Default Actions URL
 
-When `uses:` does not specify an absolution URL for the `Action`, the
+In a [workflow](https://forgejo.org/docs/v1.20/user/actions/#glossary), when `uses:` does not specify an absolute URL, the
 value of `DEFAULT_ACTIONS_URL` is prepended to it.
 
 ```yaml
@@ -23,7 +31,7 @@ ENABLED = true
 DEFAULT_ACTIONS_URL = https://code.forgejo.org
 ```
 
-The actions found at https://code.forgejo.org are:
+The actions published at https://code.forgejo.org are:
 
 - known to work with Forgejo Actions
 - published under a Free Software license
@@ -41,26 +49,75 @@ even if it provides something different than what is expected.
 
 ## Forgejo runner
 
+The `Forgejo runner` is a daemon that fetch workflows to run from a
+Forgejo instance, execute them, sends back with the logs and
+ultimately reports its success or failure.
+
 ### Installation
 
+Each `Forgejo runner` releases is published for all supported architectures as:
+
+- [binaries](https://code.forgejo.org/forgejo/runner/releases)
+- [OCI images](https://code.forgejo.org/forgejo/-/packages/container/runner/versions)
+
+#### Installation of the binary
+
 Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) and verify their signature:
 
 ```shell
-$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.5.0/forgejo-runner-amd64
+$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.0.0/forgejo-runner-amd64
 $ chmod +x forgejo-runner
-$ wget -O forgejo-runner.asc https://code.forgejo.org/forgejo/runner/releases/download/v2.5.0/forgejo-runner-amd64.asc
+$ wget -O forgejo-runner.asc https://code.forgejo.org/forgejo/runner/releases/download/v3.0.0/forgejo-runner-amd64.asc
 $ gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
 $ gpg --verify forgejo-runner.asc forgejo-runner
 Good signature from "Forgejo <contact@forgejo.org>"
 		aka "Forgejo Releases <release@forgejo.org>"
 ```
 
-#### Docker
+#### Installation of the OCI image
 
-For jobs to run in containers, the `Forgejo runner` needs access to [Docker](https://docs.docker.com/engine/install/).
+The [OCI
+images](https://code.forgejo.org/forgejo/-/packages/container/runner/versions)
+are built from the Dockerfile [found in the source
+directory](https://code.forgejo.org/forgejo/runner/src/branch/main/Dockerfile). It contains the `forgejo-runner` binary.
 
-#### Podman
+```shell
+$ docker run --rm code.forgejo.org/forgejo/runner:3.0.0 forgejo-runner --version
+forgejo-runner version v3.0.0
+```
 
+It does not run as root:
+
+```shell
+$ docker run --rm code.forgejo.org/forgejo/runner:3.0.0 id
+uid=1000 gid=1000 groups=1000
+```
+
+A [docker-compose](https://docs.docker.com/compose/) example [is
+provided](https://codeberg.org/forgejo/runner/src/branch/main/examples/docker-compose)
+to demonstrate how to install that OCI image to successfully run a workflow.
+
+### Execution of the workflows
+
+The `Forgejo runner` relies application containers (Docker, Podman,
+...) or system containers (LXC) to execute a workflow in an isolated
+environment. They need to be installed and configured independently.
+
+- **Docker:**
+  See [the Docker installation](https://docs.docker.com/engine/install/) documentation for more information.
+
+  IPv6 support is not enabled by default in docker. The following snippet enables this.
+
+  ```nix
+  virtualisation.docker = {
+    daemon.settings = {
+      fixed-cidr-v6 = "fd00::/80";
+      ipv6 = true;
+    };
+  };
+  ```
+
+- **Podman:**
   While Podman is generally compatible to Docker,
   it does not run socket for managing containers by default
   (because it doesn't usually need one).
@@ -75,8 +132,7 @@ $ podman system service -t 0 &
   $ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon
   ```
 
-#### LXC
+- **LXC:**
-
   For jobs to run in LXC containers, the `Forgejo runner` needs passwordless sudo access for all `lxc-*` commands 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
@@ -94,7 +150,7 @@ The `Forgejo runner` can then be installed and run within the `myrunner` contain
   ```shell
   $ lxc-helpers.sh lxc_container_run forgejo-runners -- sudo --user debian bash
   $ sudo apt-get install docker.io wget gnupg2
-$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.3.0/forgejo-runner-amd64
+  $ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.0.0/forgejo-runner-amd64
   ...
   ```
 
@@ -104,8 +160,7 @@ $ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/downlo
 
 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.
 
-#### Online registration
+- Online registration
-
   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.
@@ -119,7 +174,7 @@ For instance, using a token obtained for a test repository from `next.forgejo.or
 
   ```shell
   forgejo-runner register --no-interactive --token {TOKEN} --name runner --instance https://next.forgejo.org --labels docker:docker://node:16-bullseye,self-hosted
-INFO Registering runner, arch=amd64, os=linux, version=2.3.0.
+  INFO Registering runner, arch=amd64, os=linux, version=3.0.0.
   INFO Runner registered successfully.
   ```
 
@@ -137,8 +192,7 @@ It will create a `.runner` file that looks like:
   }
   ```
 
-#### Offline registration
+- Offline registration
-
   When Infrastructure as Code (Ansible, kubernetes, etc.) is used to
   deploy and configure both Forgejo and the Forgejo runner, it may be
   more convenient for it to generate a secret and share it with both.
@@ -327,36 +381,18 @@ runs-on: docker
 
 it will be submitted to a runner that registered with a `docker` label (for instance with `--labels docker:docker://node:16-bullseye`).
 
-#### Docker
+- **Docker or Podman:**
-
   If `runs-on` is matched to a label that contains `docker://`, the rest of it is interpreted as the default container image to use if no other is specified. The runner will execute all the steps, as root, within a container created from that image.
-
+- **LXC:**
-#### LXC
-
   If `runs-on` is `self-hosted`, the runner will execute all the steps, as root, within a Debian GNU/Linux `bullseye` LXC container.
 
-### Host environment
+## Packaging
 
-Certain hosts may require specific configurations for runners to work smoothly. Anything specific to these host environments can be found below.
+### NixOS
 
-#### NixOS
+The [`forgejo-actions-runner`](https://github.com/NixOS/nixpkgs/blob/ac6977498b1246f21af08f3cf25ea7b602d94b99/pkgs/development/tools/continuous-integration/forgejo-actions-runner/default.nix) recipe is released in NixOS.
 
-The `gitea-actions-runner` recipe was released in NixOS 23.05. It can be configured via `services.gitea-actions-runner`.
+Please note that the `services.forgejo-actions-runner.instances.<name>.labels` key may be set to `[]` (an empty list) to use the packaged Forgejo instance list. One of `virtualisation.docker.enable` or `virtualisation.podman.enable` will need to be set. The default Forgejo image list is populated with docker images.
-
-Please note that the `services.gitea-actions-runner.instances.<name>.labels` key may be set to `[]` (an empty list) to use the packaged Forgejo instance list. One of `virtualisation.docker.enable` or `virtualisation.podman.enable` will need to be set. The default Forgejo image list is populated with docker images.
-
-##### IPv6 on docker
-
-IPv6 support is not enabled by default in docker. The following snippet enables this.
-
-```nix
-virtualisation.docker = {
-  daemon.settings = {
-    fixed-cidr-v6 = "fd00::/80";
-    ipv6 = true;
-  };
-};
-```
 
 ## Other runners