--- 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: ``` ::// ``` 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.20 ``` See the user documentation for `jobs..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.20` defines `docker` to be the `alpine:3.20` image from https://code.forgejo.org/oci/-/packages/container/alpine/3.20 ### 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..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.