forgejo-docs/admin/actions.md

layout	title	license
~/layouts/Markdown.astro	Forgejo Actions administrator guide	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. It can be activated by adding the following to app.ini:

[actions]
ENABLED = true

Forgejo itself does not run the jobs, it relies on the Forgejo runner to do so.

Forgejo runner

Installation

Download the latest binary release and verify their signature:

$ 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.asc forgejo-runner
Good signature from "Forgejo <contact@forgejo.org>"
                aka "Forgejo Releases <release@forgejo.org>"

Docker

For jobs to run in containers, the Forgejo runner needs access to Docker.

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 is installed. The LXC helpers can be used as follows to create a suitable container:

$ 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

NOTE: Multiarch Go builds and binfmt need bookworm to produce and test binaries on a single machine for people who do not have access to dedicated hardware. If this is not needed, installing the Forgejo runner on bullseye will also work.

The Forgejo runner can then be installed and run within the myrunner container.

$ ./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 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 /org/{organization}/settings/actions/runners to gain access to all repositories within the organization.
• 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:

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.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:

{
  "WARNING": "This file is automatically generated. Do not edit.",
  "id": 6,
  "uuid": "fcd0095a-291c-420c-9de7-965e2ebaa3e8",
  "name": "runner",
  "token": "{TOKEN}",
  "address": "https://next.forgejo.org",
  "labels": ["docker:docker://node:16-bullseye", "self-hosted"]
}

Running

Once the Forgejo runner is successfully registered, it can be run from the directory in which the .runner file is found with:

$ forgejo-runner daemon
INFO[0000] Starting runner daemon

Adding the .forgejo/workflows/demo.yaml file to the test repository:

on: [push]
jobs:
  test:
    runs-on: docker
    steps:
      - run: echo All Good

Will send a job request to the Forgejo runner that will display logs such as:

...
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 a similar output in the Actions tab of the repository.

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 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:

runs-on: docker

the job will be submitted to a runner that registered with --labels docker:docker://node:16-bullseye.

Docker

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 by default.

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

Certain hosts may require specific configurations for runners to work smoothly. Anything specific to these host environments can be found below.

NixOS

The gitea-actions-runner recipe was release in NixOS 23.05. It can be configured via services.gitea-actions-runner.

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.

virtualisation.docker = {
  daemon.settings = {
    fixed-cidr-v6 = "fd00::/80";
    ipv6 = true;
  };
};