mirror of
https://codeberg.org/forgejo/docs.git
synced 2024-12-17 21:33:56 -05:00
9567aff03a
This PR rewrites the runner installation instructions, with the following changes: - deduplicate instructions as much as possible - explicitly instruct to create a separate user for the runner - reword the label explanations - split the instructions for administrating the actions feature from the installation guide for the Forgejo Runner - add instructions for setting up the runner as a systemd service https://forgejo.codeberg.page/@docs_pull_860/docs/next/admin/actions https://forgejo.codeberg.page/@docs_pull_860/docs/next/admin/runner-installation/ Reviewed-on: https://codeberg.org/forgejo/docs/pulls/860 Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org> Co-authored-by: Kwonunn <kwonunnx@gmail.com> Co-committed-by: Kwonunn <kwonunnx@gmail.com>
168 lines
6.6 KiB
Markdown
168 lines
6.6 KiB
Markdown
---
|
|
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.
|