From 014bade5474b0d7a1d7f481b1b8aa80f26ddda24 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Sun, 28 May 2023 19:15:53 +0200 Subject: [PATCH 1/2] docs: actions administration documentation # Conflicts: # admin/actions.md --- admin/actions.md | 115 ++++++++++++++++++++++++++++++++++++ admin/config-cheat-sheet.md | 34 +---------- admin/index.md | 1 + 3 files changed, 118 insertions(+), 32 deletions(-) create mode 100644 admin/actions.md diff --git a/admin/actions.md b/admin/actions.md new file mode 100644 index 00000000..aa9b6a5e --- /dev/null +++ b/admin/actions.md @@ -0,0 +1,115 @@ +--- +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 and can be activated by adding the following to `app.ini`: + +```yaml +[actions] +ENABLED = true +``` + +Forgejo 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) into `/usr/local/bin/forgejo-runner` and change its permissions with `chmod +x /usr/local/bin/forgejo-runner`. + +The binaries are signed and should be verified to match with the following : + +```shell +$ wget https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64 +$ wget 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-amd64.asc forgejo-runner-amd64 +Good signature from "Forgejo " + aka "Forgejo Releases " +``` + +## Registration + +The runner is driven by a Forgejo instance and must register itself. 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-amd64 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 it manually unless you know what you are doing.", + "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 Forgejo runner is successfully registered, it can be run from the directory in which the `.runner` file is found with: + +```shell +$ forgejo-runner-amd64 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 runner that will show 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 in the `Actions` tab of the repository. + +If no runner is available, Forgejo will wait for it and submit the job as soon as it connects. + +## Job environment + +The jobs defined in the files found in `.forgejo/workflows` specify the environment they need with `runs-on`. Each 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` matches a label that starts with `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. diff --git a/admin/config-cheat-sheet.md b/admin/config-cheat-sheet.md index 3d78e54e..c15496a9 100644 --- a/admin/config-cheat-sheet.md +++ b/admin/config-cheat-sheet.md @@ -1330,38 +1330,8 @@ PROXY_HOSTS = *.github.com ## Actions (`actions`) -- `ENABLED`: **false**: Enable/Disable actions capabilities -- `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` 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. +- `ENABLED`: **false**: Enable/Disable actions +- `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" ## Other (`other`) diff --git a/admin/index.md b/admin/index.md index 727930b1..d7cc502a 100644 --- a/admin/index.md +++ b/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) From 8b6b61054c4151d173fd2f475306c62d856bcf8d Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Mon, 29 May 2023 09:57:48 +0200 Subject: [PATCH 2/2] provide details on the Docker & LXC requirements --- admin/actions.md | 60 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/admin/actions.md b/admin/actions.md index aa9b6a5e..b778a9f0 100644 --- a/admin/actions.md +++ b/admin/actions.md @@ -4,35 +4,59 @@ 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 and can be activated by adding the following to `app.ini`: +`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 does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so. +`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) into `/usr/local/bin/forgejo-runner` and change its permissions with `chmod +x /usr/local/bin/forgejo-runner`. - -The binaries are signed and should be verified to match with the following : +Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) and verify their signature: ```shell -$ wget https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64 -$ wget https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64.asc +$ 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-amd64.asc forgejo-runner-amd64 +$ gpg --verify forgejo-runner.asc forgejo-runner Good signature from "Forgejo " aka "Forgejo Releases " ``` +### 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 runner is driven by a Forgejo instance and must register itself. 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: +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. @@ -40,7 +64,7 @@ The runner is driven by a Forgejo instance and must register itself. It will be For instance, using a token obtained for a test repository from `next.forgejo.org`: ```shell -forgejo-runner-amd64 register --no-interactive --token {TOKEN} --name runner --instance https://next.forgejo.org --labels ubuntu-latest:docker://node:16-buster,self-hosted +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 @@ -51,7 +75,7 @@ It will create a `.runner` file that looks like: ```json { - "WARNING": "This file is automatically generated. Do not edit it manually unless you know what you are doing.", + "WARNING": "This file is automatically generated. Do not edit.", "id": 6, "uuid": "fcd0095a-291c-420c-9de7-965e2ebaa3e8", "name": "runner", @@ -63,10 +87,10 @@ It will create a `.runner` file that looks like: ## Running -Once Forgejo runner is successfully registered, it can be run from the directory in which the `.runner` file is found with: +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-amd64 daemon +$ forgejo-runner daemon INFO[0000] Starting runner daemon ``` @@ -81,7 +105,7 @@ jobs: - run: echo All Good ``` -Will send a job request to the runner that will show logs such as: +Will send a job request to the `Forgejo runner` that will display logs such as: ```shell ... @@ -92,13 +116,13 @@ INFO[2023-05-28T18:54:53+02:00] task 29 repo is earl-warren/test https://code.fo [/test] ✅ Success - Main echo All Good ``` -It will also show in the `Actions` tab of the repository. +It will also show a similar output in the `Actions` tab of the repository. -If no runner is available, Forgejo will wait for it and submit the job as soon as it connects. +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 with `runs-on`. Each runner declares, with the `--labels` option` which one they support so Forgejo knows to submit jobs accordingly. For instance if a job has: +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 @@ -108,7 +132,7 @@ the job will be submitted to a runner that registered with `--labels ubuntu-late ### Docker -If `runs-on` matches a label that starts with `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. +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