---
layout: '~/layouts/Markdown.astro'
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 experimental 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.

# Default Actions URL

When `uses:` does not specify an absolution URL for the `Action`, the value of `DEFAULT_ACTIONS_URL` is prepended to it.

```yaml
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org
```

The [actions organization](https://code.forgejo.org/actions) contains a set of actions that are:

- known to work with Forgejo Actions
- published under a Free Software license

# Forgejo runner

## Installation

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.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](https://docs.docker.com/engine/install/).

### 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
$ 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](https://go.dev/) builds and [binfmt](https://github.com/tonistiigi/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.

```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 `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/{org}/settings/actions/runners` to gain access to all repositories within the organization.
- in `/user/settings/actions/runners` to gain access to all repositories of the logged in user
- 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 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:

```json
{
  "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:

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

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

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

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

```yaml
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 released 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.

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