mirror of
https://codeberg.org/forgejo/docs.git
synced 2025-01-11 00:50:57 -05:00
admin: actions: rework and introduce OCI images
This commit is contained in:
Earl Warren
Earl Warren
parent
581d02f1d7
commit
d1f42e1b83
1 changed files with 151 additions and 115 deletions
|
|
@ -3,18 +3,26 @@ 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 in beta and disabled by default. It can be activated by adding the following to `app.ini`:
|
||||
`Forgejo Actions` provides continuous integration driven from the files found in the `.forgejo/workflows` directory of a repository.
|
||||
|
||||
## Forgejo settings
|
||||
|
||||
### Enabling
|
||||
|
||||
`Forgejo Actions` is still in alpha 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.
|
||||
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.
|
||||
|
||||
## Default Actions URL
|
||||
### Default Actions URL
|
||||
|
||||
When `uses:` does not specify an absolution URL for the `Action`, the
|
||||
In a [workflow](https://forgejo.org/docs/v1.20/user/actions/#glossary), when `uses:` does not specify an absolute URL, the
|
||||
value of `DEFAULT_ACTIONS_URL` is prepended to it.
|
||||
|
||||
```yaml
|
||||
|
|
@ -23,7 +31,7 @@ ENABLED = true
|
|||
DEFAULT_ACTIONS_URL = https://code.forgejo.org
|
||||
```
|
||||
|
||||
The actions found at https://code.forgejo.org are:
|
||||
The actions published at https://code.forgejo.org are:
|
||||
|
||||
- known to work with Forgejo Actions
|
||||
- published under a Free Software license
|
||||
|
|
@ -41,26 +49,75 @@ even if it provides something different than what is expected.
|
|||
|
||||
## Forgejo runner
|
||||
|
||||
The `Forgejo runner` is a daemon that fetch workflows to run from a
|
||||
Forgejo instance, execute them, sends back with the logs and
|
||||
ultimately reports its success or failure.
|
||||
|
||||
### Installation
|
||||
|
||||
Each `Forgejo runner` releases is published for all supported architectures as:
|
||||
|
||||
- [binaries](https://code.forgejo.org/forgejo/runner/releases)
|
||||
- [OCI images](https://code.forgejo.org/forgejo/-/packages/container/runner/versions)
|
||||
|
||||
#### Installation of the binary
|
||||
|
||||
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.5.0/forgejo-runner-amd64
|
||||
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.0.0/forgejo-runner-amd64
|
||||
$ chmod +x forgejo-runner
|
||||
$ wget -O forgejo-runner.asc https://code.forgejo.org/forgejo/runner/releases/download/v2.5.0/forgejo-runner-amd64.asc
|
||||
$ wget -O forgejo-runner.asc https://code.forgejo.org/forgejo/runner/releases/download/v3.0.0/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
|
||||
#### Installation of the OCI image
|
||||
|
||||
For jobs to run in containers, the `Forgejo runner` needs access to [Docker](https://docs.docker.com/engine/install/).
|
||||
The [OCI
|
||||
images](https://code.forgejo.org/forgejo/-/packages/container/runner/versions)
|
||||
are built from the Dockerfile [found in the source
|
||||
directory](https://code.forgejo.org/forgejo/runner/src/branch/main/Dockerfile). It contains the `forgejo-runner` binary.
|
||||
|
||||
#### Podman
|
||||
```shell
|
||||
$ docker run --rm code.forgejo.org/forgejo/runner:3.0.0 forgejo-runner --version
|
||||
forgejo-runner version v3.0.0
|
||||
```
|
||||
|
||||
It does not run as root:
|
||||
|
||||
```shell
|
||||
$ docker run --rm code.forgejo.org/forgejo/runner:3.0.0 id
|
||||
uid=1000 gid=1000 groups=1000
|
||||
```
|
||||
|
||||
A [docker-compose](https://docs.docker.com/compose/) example [is
|
||||
provided](https://codeberg.org/forgejo/runner/src/branch/main/examples/docker-compose)
|
||||
to demonstrate how to install that OCI image to successfully run a workflow.
|
||||
|
||||
### Execution of the workflows
|
||||
|
||||
The `Forgejo runner` relies application containers (Docker, Podman,
|
||||
...) or system containers (LXC) to execute a workflow in an isolated
|
||||
environment. They need to be installed and configured independently.
|
||||
|
||||
- **Docker:**
|
||||
See [the Docker installation](https://docs.docker.com/engine/install/) documentation for more information.
|
||||
|
||||
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;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
- **Podman:**
|
||||
While Podman is generally compatible to Docker,
|
||||
it does not run socket for managing containers by default
|
||||
(because it doesn't usually need one).
|
||||
|
|
@ -75,8 +132,7 @@ $ podman system service -t 0 &
|
|||
$ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon
|
||||
```
|
||||
|
||||
#### LXC
|
||||
|
||||
- **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
|
||||
|
|
@ -94,7 +150,7 @@ The `Forgejo runner` can then be installed and run within the `myrunner` contain
|
|||
```shell
|
||||
$ lxc-helpers.sh lxc_container_run forgejo-runners -- sudo --user debian bash
|
||||
$ sudo apt-get install docker.io wget gnupg2
|
||||
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.3.0/forgejo-runner-amd64
|
||||
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.0.0/forgejo-runner-amd64
|
||||
...
|
||||
```
|
||||
|
||||
|
|
@ -104,8 +160,7 @@ $ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/downlo
|
|||
|
||||
The `Forgejo runner` needs to connect to a `Forgejo` instance and must be registered before doing so. It will give it permission to read the repositories and send back information to `Forgejo` such as the logs or its status.
|
||||
|
||||
#### Online registration
|
||||
|
||||
- Online registration
|
||||
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.
|
||||
|
|
@ -119,7 +174,7 @@ For instance, using a token obtained for a test repository from `next.forgejo.or
|
|||
|
||||
```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.3.0.
|
||||
INFO Registering runner, arch=amd64, os=linux, version=3.0.0.
|
||||
INFO Runner registered successfully.
|
||||
```
|
||||
|
||||
|
|
@ -137,8 +192,7 @@ It will create a `.runner` file that looks like:
|
|||
}
|
||||
```
|
||||
|
||||
#### Offline registration
|
||||
|
||||
- Offline registration
|
||||
When Infrastructure as Code (Ansible, kubernetes, etc.) is used to
|
||||
deploy and configure both Forgejo and the Forgejo runner, it may be
|
||||
more convenient for it to generate a secret and share it with both.
|
||||
|
|
@ -327,36 +381,18 @@ runs-on: docker
|
|||
|
||||
it will be submitted to a runner that registered with a `docker` label (for instance with `--labels docker:docker://node:16-bullseye`).
|
||||
|
||||
#### Docker
|
||||
|
||||
- **Docker or Podman:**
|
||||
If `runs-on` is matched to a label that contains `docker://`, 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.
|
||||
|
||||
#### LXC
|
||||
|
||||
- **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
|
||||
## Packaging
|
||||
|
||||
Certain hosts may require specific configurations for runners to work smoothly. Anything specific to these host environments can be found below.
|
||||
### NixOS
|
||||
|
||||
#### NixOS
|
||||
The [`forgejo-actions-runner`](https://github.com/NixOS/nixpkgs/blob/ac6977498b1246f21af08f3cf25ea7b602d94b99/pkgs/development/tools/continuous-integration/forgejo-actions-runner/default.nix) recipe is released in 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;
|
||||
};
|
||||
};
|
||||
```
|
||||
Please note that the `services.forgejo-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.
|
||||
|
||||
## Other runners
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue