diff --git a/admin/actions.md b/admin/actions.md new file mode 100644 index 00000000..b778a9f0 --- /dev/null +++ b/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 " + 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 `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. 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)