--- layout: '~/layouts/Markdown.astro' 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`: ```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 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 : ```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 $ gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710 $ gpg --verify forgejo-runner-amd64.asc forgejo-runner-amd64 Good signature from "Forgejo " aka "Forgejo Releases " ``` ## 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: - in `/admin/runners` to gain access to all repositories. - in `/{owner}/{repository}/settings/actions/runners` to gain access to a single repository. 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 INFO Registering runner, arch=amd64, os=linux, version=2.0.3. WARN Runner in user-mode. DEBU Successfully pinged the Forgejo instance server INFO Runner registered successfully. ``` 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.", "id": 6, "uuid": "fcd0095a-291c-420c-9de7-965e2ebaa3e8", "name": "runner", "token": "{TOKEN}", "address": "https://next.forgejo.org", "labels": ["ubuntu-latest:docker://node:16-buster", "self-hosted"] } ``` ## Running Once 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 INFO[0000] Starting runner daemon ``` Adding the `.forgejo/workflows/demo.yaml` file to the test repository: ``` on: [push] jobs: test: runs-on: ubuntu-latest steps: - run: echo All Good ``` Will send a job request to the runner that will show logs such as: ```shell ... INFO[2023-05-28T18:54:53+02:00] task 29 repo is earl-warren/test https://code.forgejo.org https://next.forgejo.org ... [/test] [DEBUG] Working directory '/workspace/earl-warren/test' | All Good [/test] ✅ Success - Main echo All Good ``` It will also show 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. ## 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: ```yaml runs-on: ubuntu-latest ``` the job will be submitted to a runner that registered with `--labels ubuntu-latest:docker://node:16-buster`. ### 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. ### LXC If `runs-on` is `self-hosted`, the runner will execute all the steps, as root, within a Debian GNU/Linux bullseye LXC container.