Skip to content

Commit 8f314c6

Browse files
wolfogresilverwindtechknowlogick
authored
Docs for Gitea Actions (#24405)
A new documentation section for Gitea Actions. Some content comes from: - [Hacking on Gitea Actions](https://blog.gitea.io/2023/03/hacking-on-gitea-actions/) - The README of [act_runner](https://gitea.com/gitea/act_runner) - @ChristopherHX's excellent overview of the differences between Gitea Actions and GitHub Actions in [this comment](#13539 (comment)). --------- Co-authored-by: silverwind <me@silverwind.io> Co-authored-by: techknowlogick <techknowlogick@gitea.io>
1 parent b8c19e7 commit 8f314c6

14 files changed

+888
-1
lines changed

‎docs/content/doc/actions.en-us.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
date: "2023-04-27T14:00:00+08:00"
3+
title: "Actions"
4+
slug: "actions"
5+
weight: 36
6+
toc: false
7+
draft: false
8+
menu:
9+
sidebar:
10+
name: "Usage - Actions"
11+
weight: 31
12+
identifier: "actions"
13+
---

‎docs/content/doc/actions/act-runner.en-us.md

+206
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
date: "2023-04-27T15:00:00+08:00"
3+
title: "Act Runner"
4+
slug: "usage/actions/act-runner"
5+
weight: 20
6+
draft: false
7+
toc: false
8+
menu:
9+
sidebar:
10+
parent: "actions"
11+
name: "Act Runner"
12+
weight: 20
13+
identifier: "actions-runner"
14+
---
15+
16+
# Act Runner
17+
18+
This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner of Gitea Actions.
19+
20+
**Table of Contents**
21+
22+
{{< toc >}}
23+
24+
## Requirements
25+
26+
It is recommended to run jobs in a docker container, so you need to install docker first.
27+
And make sure that the docker daemon is running.
28+
29+
Other OCI container engines which are compatible with Docker's API should also work, but are untested.
30+
31+
However, if you are sure that you want to run jobs directly on the host only, then docker is not required.
32+
33+
## Installation
34+
35+
There are multiple ways to install the act runner.
36+
37+
### Download the binary
38+
39+
You can download the binary from the [release page](https://gitea.com/gitea/act_runner/releases).
40+
However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/act_runner/).
41+
42+
When you download the binary, please make sure that you have downloaded the correct one for your platform.
43+
You can check it by running the following command:
44+
45+
```bash
46+
chmod +x act_runner
47+
./act_runner --version
48+
```
49+
50+
If you see the version information, it means that you have downloaded the correct binary.
51+
52+
### Use the docker image
53+
54+
You can use the docker image from the [docker hub](https://hub.docker.com/r/gitea/act_runner/tags).
55+
Just like the binary, you can use the latest nightly build by using the `nightly` tag, while the `latest` tag is the latest stable release.
56+
57+
```bash
58+
docker pull gitea/act_runner:latest # for the latest stable release
59+
docker pull gitea/act_runner:nightly # for the latest nightly build
60+
```
61+
62+
## Configuration
63+
64+
Configuration is done via a configuration file. It is optional, and the default configuration will be used when no configuration file is specified.
65+
66+
You can generate a configuration file by running the following command:
67+
68+
```bash
69+
./act_runner generate-config
70+
```
71+
72+
The default configuration is safe to use without any modification, so you can just use it directly.
73+
74+
```bash
75+
./act_runner generate-config > config.yaml
76+
./act_runner --config config.yaml [command]
77+
```
78+
79+
When you are using the docker image, you can specify the configuration file by using the `CONFIG_FILE` environment variable. Make sure that the file is mounted into the container as a volume:
80+
81+
```bash
82+
docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
83+
```
84+
85+
You may notice the commands above are both incomplete, because it is not the time to run the act runner yet.
86+
Before running the act runner, we need to register it to your Gitea instance first.
87+
88+
## Registration
89+
90+
Registration is required before running the act runner, because the runner needs to know where to get jobs from.
91+
And it is also important to Gitea instance to identify the runner.
92+
93+
### Runner levels
94+
95+
You can register a runner in different levels, it can be:
96+
97+
- Instance level: The runner will run jobs for all repositories in the instance.
98+
- Organization level: The runner will run jobs for all repositories in the organization.
99+
- Repository level: The runner will run jobs for the repository it belongs to.
100+
101+
Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this.
102+
103+
### Obtain a registration token
104+
105+
The level of the runner determines where to obtain the registration token.
106+
107+
- Instance level: The admin settings page, like `<your_gitea.com>/admin/runners`.
108+
- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/runners`.
109+
- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/runners`.
110+
111+
If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.
112+
113+
The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`.
114+
115+
### Register the runner
116+
117+
The act runner can be registered by running the following command:
118+
119+
```bash
120+
./act_runner register
121+
```
122+
123+
Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section.
124+
125+
```bash
126+
./act_runner --config config.yaml register
127+
```
128+
129+
You will be asked to input the registration information step by step. Includes:
130+
131+
- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`.
132+
- The registration token.
133+
- The runner name, which is optional. If you leave it blank, the hostname will be used.
134+
- The runner labels, which is optional. If you leave it blank, the default labels will be used.
135+
136+
You may be confused about the runner labels, which will be explained later.
137+
138+
If you want to register the runner in a non-interactive way, you can use arguments to do it.
139+
140+
```bash
141+
./act_runner register --no-interactive --instance <intance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
142+
```
143+
144+
When you have registered the runner, you can find a new file named `.runner` in the current directory.
145+
This file stores the registration information.
146+
Please do not edit it manually.
147+
If this file is missing or corrupted, you can simply remove it and register again.
148+
149+
If you want to store the registration information in another place, you can specify it in the configuration file,
150+
and don't forget to specify the `--config` option.
151+
152+
### Register the runner with docker
153+
154+
If you are using the docker image, behaviour will be slightly different. Registration and running are combined into one step in this case, so you need to specify the registration information when running the act runner.
155+
156+
```bash
157+
docker run \
158+
-v $(pwd)/config.yaml:/config.yaml \
159+
-v $(pwd)/data:/data \
160+
-v /var/run/docker.sock:/var/run/docker.sock \
161+
-e CONFIG_FILE=/config.yaml \
162+
-e GITEA_INSTANCE_URL=<instance_url> \
163+
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
164+
-e GITEA_RUNNER_NAME=<runner_name> \
165+
-e GITEA_RUNNER_LABELS=<runner_labels> \
166+
--name my_runner \
167+
-d gitea/act_runner:nightly
168+
```
169+
170+
You may notice that we have mounted the `/var/run/docker.sock` into the container.
171+
It is because the act runner will run jobs in docker containers, so it needs to communicate with the docker daemon.
172+
As mentioned, you can remove it if you want to run jobs in the host directly.
173+
To be clear, the "host" actually means the container which is running the act runner now, instead of the host machine.
174+
175+
### Labels
176+
177+
The labels of a runner are used to determine which jobs the runner can run, and how to run them.
178+
179+
The default labels are `ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`.
180+
It is a comma-separated list, and each item is a label.
181+
182+
Let's take `ubuntu-22.04:docker://node:16-bullseye` as an example.
183+
It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job will be run in a docker container with the image `node:16-bullseye`.
184+
185+
If the default image is insufficient for your needs, and you have enough disk space to use a better and bigger one, you can change it to `ubuntu-22.04:docker://<the image you like>`.
186+
You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md).
187+
188+
If you want to run jobs in the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`, the `:host` is optional.
189+
However, we suggest you to use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
190+
191+
One more thing is that it is recommended to register the runner if you want to change the labels.
192+
It may be annoying to do this, so we may provide a better way to do it in the future.
193+
194+
## Running
195+
196+
After you have registered the runner, you can run it by running the following command:
197+
198+
```bash
199+
./act_runner daemon
200+
# or
201+
./act_runner daemon --config config.yaml
202+
```
203+
204+
The runner will fetch jobs from the Gitea instance and run them automatically.
205+
206+
Since act runner is still in development, it is recommended to check the latest version and upgrade it regularly.

‎docs/content/doc/actions/comparison.en-us.md

+171
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
date: "2023-04-27T15:00:00+08:00"
3+
title: "Compared to GitHub Actions"
4+
slug: "usage/actions/comparison"
5+
weight: 30
6+
draft: false
7+
toc: false
8+
menu:
9+
sidebar:
10+
parent: "actions"
11+
name: "Comparison"
12+
weight: 30
13+
identifier: "actions-comparison"
14+
---
15+
16+
# Compared to GitHub Actions
17+
18+
Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them.
19+
20+
**Table of Contents**
21+
22+
{{< toc >}}
23+
24+
## Additional features
25+
26+
### Absolute action URLs
27+
28+
Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository.
29+
Like `uses: https://github.com/actions/checkout@v3` or `uses: http://your_gitea.com/owner/repo@branch`.
30+
31+
### Actions written in Go
32+
33+
Gitea Actions supports writing actions in Go.
34+
See [Creating Go Actions](https://blog.gitea.io/2023/04/creating-go-actions/).
35+
36+
## Unsupported workflows syntax
37+
38+
### `concurrency`
39+
40+
It's used to run a single job at a time.
41+
See [Using concurrency](https://docs.github.com/en/actions/using-jobs/using-concurrency).
42+
43+
It's ignored by Gitea Actions now.
44+
45+
### `run-name`
46+
47+
The name for workflow runs generated from the workflow.
48+
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name).
49+
50+
It's ignored by Gitea Actions now.
51+
52+
### `permissions` and `jobs.<job_id>.permissions`
53+
54+
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).
55+
56+
It's ignored by Gitea Actions now.
57+
58+
### `jobs.<job_id>.timeout-minutes`
59+
60+
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes).
61+
62+
It's ignored by Gitea Actions now.
63+
64+
### `jobs.<job_id>.continue-on-error`
65+
66+
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error).
67+
68+
It's ignored by Gitea Actions now.
69+
70+
### `jobs.<job_id>.environment`
71+
72+
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment).
73+
74+
It's ignored by Gitea Actions now.
75+
76+
### Complex `runs-on`
77+
78+
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
79+
80+
Gitea Actions only supports `runs-on: xyz` or `runs-on: [xyz]` now.
81+
82+
### `workflow_dispatch`
83+
84+
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch).
85+
86+
It's ignored by Gitea Actions now.
87+
88+
### `hashFiles` expression
89+
90+
See [Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)
91+
92+
Gitea Actions doesn't support it now, if you use it, the result will always be empty string.
93+
94+
As a workaround, you can use [go-hashfiles](https://gitea.com/actions/go-hashfiles) instead.
95+
96+
## Missing features
97+
98+
### Variables
99+
100+
See [Variables](https://docs.github.com/en/actions/learn-github-actions/variables).
101+
102+
It's under development.
103+
104+
### Problem Matchers
105+
106+
Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
107+
See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md).
108+
109+
It's ignored by Gitea Actions now.
110+
111+
### Create an error annotation
112+
113+
See [Creating an annotation for an error](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)
114+
115+
It's ignored by Gitea Actions now.
116+
117+
## Missing UI features
118+
119+
### Pre and Post steps
120+
121+
Pre and Post steps don't have their own section in the job log user interface.
122+
123+
## Different behavior
124+
125+
### Downloading actions
126+
127+
Gitea Actions doesn't download actions from GitHub by default.
128+
"By default" means that you don't specify the host in the `uses` field, like `uses: actions/checkout@v3`.
129+
As a contrast, `uses: https://github.com/actions/checkout@v3` has specified host.
130+
131+
The missing host will be filled with `https://gitea.com` if you don't configure it.
132+
That means `uses: actions/checkout@v3` will download the action from [gitea.com/actions/checkout](https://gitea.com/actions/checkout), instead of [github.com/actions/checkout](https://github.com/actions/checkout).
133+
134+
As mentioned, it's configurable.
135+
If you want your runners to download actions from GitHub or your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`. See [Configuration Cheat Sheet](({{ < relref "doc/administration/config-cheat-sheet.en-us.md#actions-actions" > }})).
136+
137+
### Context availability
138+
139+
Context availability is not checked, so you can use the env context on more places.
140+
See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability).
141+
142+
## Known issues
143+
144+
### `docker/build-push-action@v4`
145+
146+
See [act_runner#119](https://gitea.com/gitea/act_runner/issues/119#issuecomment-738294).
147+
148+
`ACTIONS_RUNTIME_TOKEN` is a random string in Gitea Actions, not a JWT.
149+
But the `docker/build-push-action@v4` tries to parse the token as JWT and doesn't handle the error, so the job fails.
150+
151+
There are two workarounds:
152+
153+
Set the `ACTIONS_RUNTIME_TOKEN` to empty manually, like:
154+
155+
``` yml
156+
- name: Build and push
157+
uses: docker/build-push-action@v4
158+
env:
159+
ACTIONS_RUNTIME_TOKEN: ''
160+
with:
161+
...
162+
```
163+
164+
The bug has been fixed in a newer [commit](https://gitea.com/docker/build-push-action/commit/d8823bfaed2a82c6f5d4799a2f8e86173c461aba?style=split&whitespace=show-all#diff-1af9a5bdf96ddff3a2f3427ed520b7005e9564ad), but it has not been released. So you could use the latest version by specifying the branch name, like:
165+
166+
``` yml
167+
- name: Build and push
168+
uses: docker/build-push-action@master
169+
with:
170+
...
171+
```

0 commit comments

Comments
 (0)