Merge pull request 'docs: actions administration documentation' (#235) from earl-warren/website:wip-actions into main

Reviewed-on: https://codeberg.org/forgejo/website/pulls/235
Reviewed-by: Loïc Dachary <dachary@noreply.codeberg.org>

admin/actions.md

@@ -0,0 +1,139 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'Forgejo Actions'
+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.
+
+# 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 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
+```
+
+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 `/{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 ubuntu-latest:docker://node:16-buster,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": ["ubuntu-latest:docker://node:16-buster", "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:
+
+```
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    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: ubuntu-latest
+```
+
+the job will be submitted to a runner that registered with `--labels ubuntu-latest:docker://node:16-buster`.
+
+### 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.
+
+### LXC
+
+If `runs-on` is `self-hosted`, the runner will execute all the steps, as root, within a Debian GNU/Linux bullseye LXC container.

admin/config-cheat-sheet.md

@@ -1330,38 +1330,8 @@ PROXY_HOSTS = *.github.com
 
 ## Actions (`actions`)
 
-- `ENABLED`: **false**: Enable/Disable actions capabilities
+- `ENABLED`: **false**: Enable/Disable actions
-- `DEFAULT_ACTIONS_URL`: **https://codeberg.org**: Default address to get action plugins, e.g. the default value means downloading from "https://codeberg.org/actions/checkout" for "uses: actions/checkout@v3"
+- `DEFAULT_ACTIONS_URL`: **https://code.forgejo.org**: Default address to get action plugins, e.g. the default value means downloading from "https://code.forgejo.org/actions/checkout" for "uses: actions/checkout@v3"
-
-`DEFAULT_ACTIONS_URL` indicates where should we find the relative path action plugin. i.e. when use an action in a workflow file like
-
-```yaml
-name: versions
-on:
-  push:
-    branches:
-      - main
-      - releases/*
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-```
-
-Now we need to know how to get actions/checkout, this configuration is the default git server to get it. That means we will get the repository via git clone ${DEFAULT_ACTIONS_URL}/actions/checkout and fetch tag v3.
-
-To help people who don't want to mirror these actions in their git instances, the default value is https://codeberg.org
-To help people run actions totally in their network, they can change the value and copy all necessary action repositories into their git server.
-
-Of course we should support the form in future PRs like
-
-```yaml
-steps:
-  - uses: codeberg.org/actions/checkout@v3
-```
-
-although Github don't support this form.
 
 ## Other (`other`)
 

admin/index.md

@@ -15,3 +15,4 @@ These documents are targeted to people who run Forgejo on their machines.
 - [Email setup](email-setup)
 - [Incoming Email](incoming-email)
 - [Logging Configuration](logging-documentation)
+- [Actions](actions)