diff --git a/admin/actions.md b/admin/actions.md index aa9b6a5e..b778a9f0 100644 --- a/admin/actions.md +++ b/admin/actions.md @@ -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 " aka "Forgejo Releases " ``` +### 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