mirror of
https://codeberg.org/forgejo/docs.git
synced 2024-12-23 22:20:43 -05:00
docs: actions administration documentation
# Conflicts: # admin/actions.md
This commit is contained in:
Earl Warren
Caesar Schinas
parent
23b9e29125
commit
014bade547
3 changed files with 118 additions and 32 deletions
115
admin/actions.md
Normal file
115
admin/actions.md
Normal file
|
|
@ -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 <contact@forgejo.org>"
|
||||
aka "Forgejo Releases <release@forgejo.org>"
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
|
@ -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