mirror of
https://codeberg.org/forgejo/docs.git
synced 2024-12-24 22:32:43 -05:00
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>
This commit is contained in:
Earl Warren
Caesar Schinas
commit
9b68661c22
3 changed files with 142 additions and 32 deletions
139
admin/actions.md
Normal file
139
admin/actions.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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`)
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue