forgejo-docs/docs/admin/actions.md

---
title: 'Forgejo Actions administrator guide'
license: 'CC-BY-SA-4.0'
---

`Forgejo Actions` provides continuous integration driven from the files found in the `.forgejo/workflows` directory of a repository. 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.

## Settings

### Default Actions URL

In a [workflow](../../user/actions/#glossary), when `uses:` does not specify an absolute URL, the
value of `DEFAULT_ACTIONS_URL` is prepended to it.

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

The actions published at https://code.forgejo.org are:

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

They can be found in the following organizations:

- [General purpose actions](https://code.forgejo.org/actions)
- [Docker actions](https://code.forgejo.org/docker)

When setting `DEFAULT_ACTIONS_URL` to a Forgejo instance with an open
registration, **care must be taken to avoid name conflicts**. For
instance if an action has `uses: foo/bar@main` it will clone and try
to run the action found at `DEFAULT_ACTIONS_URL/foo/bar` if it exists,
even if it provides something different than what is expected.

### Disabling

As of `Forgejo v1.21` it is enabled by default. It can be disabled by adding the following to `app.ini`:

```yaml
[actions]
ENABLED = false
```

### Storage

The logs and artifacts are stored in `Forgejo`. The cache is stored by
the runner itself and never sent to `Forgejo`.

#### `job` logs

The logs of each `job` run is stored by the `Forgejo` server and never
expires. The location where these files are stored is configured in
the `storage.actions_log` section of `app.ini` as [explained in in the
storage documentation](../storage/).

#### `artifacts` logs

The artifacts uploaded by a job are stored by the `Forgejo` server and
expire after a delay that defaults to 90 days and can be configured as
follows:

```yaml
[actions]
ARTIFACT_RETENTION_DAYS = 90
```

The location where these artifacts are stored is configured in
the `storage.artifacts` section of `app.ini` as [explained in in the
storage documentation](../storage/).

The `admin/monitor/cron` administration web interface can be used to
manually trigger the `Cleanup actions expired logs and artifacts` task
instead of waiting for the scheduled task to happen.

## Forgejo runner

The `Forgejo runner` is a daemon that fetches workflows to run from a
Forgejo instance, executes them, sends back with the logs and
ultimately reports its success or failure.

Installation and setup instructions can be found in the [Forgejo Runner installation guide](../runner-installation/).

## Choosing labels

Runner labels are used by workflows to define what type of environment they need to be executed in. Each runner declares a set of labels, and the `Forgejo` server will send it tasks accordingly. For example, a workflow with:

```yaml
runs-on: docker
```

will be run on a runner which has declared a `docker` label.

A label has the following structure:

```
<label-name>:<label-type>://<default-image>
```

The `label name` is a unique string that identifies the label. It is the part that is specified in the `runs-on` field of workflows to choose which runners the workflow can be excecuted on.

The `label type` determines what containerization system will be used to run the workflow. There are three options:

### Docker or Podman

If a label specifies `docker` as its `label type`, 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.

The default container container image can be overridden by a workflow:

```yaml
runs-on: docker
container:
  image: alpine:3.18
```

See the user documentation for `jobs.<job_id>.container` for more information.

Label examples:

- `node20:docker://node:20-bookworm` == `node20:docker://docker.io/node:20-bookworm` defines `node20` to be the `node:20-bookworm` image from hub.docker.com
- `docker:docker://code.forgejo.org/oci/alpine:3.18` defines `docker` to be the `alpine:3.18` image from https://code.forgejo.org/oci/-/packages/container/alpine/3.18

### LXC

If a label specifies `lxc` as its `label type`, the rest of it is interpreted as the default [template and release](https://images.linuxcontainers.org/) to use if no other is specified. The runner will execute all the steps, as root, within a [LXC container](https://linuxcontainers.org/) created from that template and release. The default template is `debian` and the default release is `bullseye`.

[nodejs](https://nodejs.org/en/download/) version 20 is installed.

The default template and release can be overridden by a workflow:

```yaml
runs-on: lxc
container:
  image: debian:bookworm
```

See the user documentation for `jobs.<job_id>.container` for more information.

Label example:

- `bookworm:lxc://debian:bookworm` defines `bookworm` to be an LXC container running Debian GNU/Linux bookworm.

### Host

If a label specifies `host` as its `label type`, the runner will execute all the steps in a shell forked from the runner, directly on the host.

> **Warning:** There is no isolation at all and a single job can permanently destroy the host.

Label example:

- `self-hosted:host://-self-hosted` defines `self-hosted` to be a shell

### Special labels

Runner labels can also be used to define other special features a runner has. For example, you could use `gpu:docker://node:20-bullseye` to define a runner that has a GPU installed. Workflows which need a GPU could then specify `runs-on: gpu` to be excecuted on this runner.

### Mimicking GitHub runners

To mimic the GitHub runners, the `runs-on` field can be set to `ubuntu-22.04:docker://node:20-bullseye` for instance.
With this, the Forgejo runner will respond to `runs-on: ubuntu-22.04` and will use the `node:20-bullseye` image from hub.docker.com.
This image is quite capable of running many of the workflows that are designed for the GitHub runners.
For a slightly bigger image, use `ghcr.io/catthehacker/ubuntu:act-22.04` instead of `node:20-bullseye` which should be compatible with most actions while remaining relatively small.
There exist larger images used that can go up to 20GB compressed with more software installed if needed.

## Other runners

It is possible to use [other runners](https://codeberg.org/forgejo-contrib/delightful-forgejo#user-content-forgejo-actions-runners) instead of `Forgejo runner`. As long as they can connect to a `Forgejo` instance using the [same protocol](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/routers/api/actions), they will be given tasks to run.