mirror of
https://gitea.com/gitea/blog.git
synced 2024-06-02 00:11:23 +05:30
fix: new lines
This commit is contained in:
Jason Song
parent
8e03b6a346
commit
25478c9609
|
|
@ -6,9 +6,10 @@ tags: ["actions"]
|
|||
draft: false
|
||||
---
|
||||
|
||||
Gitea 1.19.0 includes a new feature called Gitea Actions. This is a built-in CI system of Gitea, similar and compatible to GitHub Actions.
|
||||
Gitea 1.19.0 includes a new feature called Gitea Actions.
|
||||
This is a built-in CI system of Gitea, similar and compatible to GitHub Actions.
|
||||
|
||||
This blog will explain some details about Gitea Actions, including how to use it and how it works.
|
||||
This blog will explain some details about Gitea Actions, including how to use it and how it works.
|
||||
It should be noted that the information presented pertains to the current situation, and may become outdated in the future.
|
||||
|
||||
<!--more-->
|
||||
|
|
@ -46,7 +47,9 @@ Of course, you can also wrap this binary in something like a system service, sup
|
|||
Before proceeding any further, we suggest running it as a command line to ensure that it works with your environment, especially if you are running a runner on your local host.
|
||||
In order to avoid consuming too many resources and affecting the Gitea instance, it is also recommended to start runners on separate machines from the Gitea instance.
|
||||
|
||||
Also, make sure that Docker is installed. While it is not strictly necessary, it is common usage. We will discuss this later.
|
||||
Also, make sure that Docker is installed.
|
||||
While it is not strictly necessary, it is common usage.
|
||||
We will discuss this later.
|
||||
|
||||
Before running a runner, you should first register it to your Gitea instance using the following command:
|
||||
|
||||
|
|
@ -58,16 +61,23 @@ There are two arguments required, `instance` and `token`.
|
|||
|
||||
`instance` refers to the address of your Gitea instance, like `http://192.168.8.8:3000` or `https://gitea.com`.
|
||||
The runner and job containers (which are started by the runner to execute jobs) will connect to this address.
|
||||
This means that it could be different from the `ROOT_URL` of your Gitea instance, which is configured for web access. It is always a bad idea to use a loopback address such as `127.0.0.1` or `localhost`, as we will discuss later. If you are unsure which address to use, the LAN address is usually the right choice.
|
||||
This means that it could be different from the `ROOT_URL` of your Gitea instance, which is configured for web access.
|
||||
It is always a bad idea to use a loopback address such as `127.0.0.1` or `localhost`, as we will discuss later.
|
||||
If you are unsure which address to use, the LAN address is usually the right choice.
|
||||
|
||||
`token` is used for authentication and identification, such as `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`. It is one-time use only and cannot be used to register multiple runners.
|
||||
`token` is used for authentication and identification, such as `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`.
|
||||
It is one-time use only and cannot be used to register multiple runners.
|
||||
You can obtain tokens from `your_gitea.com/admin/runners`.
|
||||
|
||||
|
||||
|
||||
If you cannot find this page, it is likely that you have a wrong version of Gitea or have not enabled Actions. Please check the steps above.
|
||||
If you cannot find this page, it is likely that you have a wrong version of Gitea or have not enabled Actions.
|
||||
Please check the steps above.
|
||||
|
||||
After registering, a new file named `.runner` will appear in the current directory. This file stores the registration information. Please do not edit it manually. If this file is missing or corrupted, you can simply remove it and register again.
|
||||
After registering, a new file named `.runner` will appear in the current directory.
|
||||
This file stores the registration information.
|
||||
Please do not edit it manually.
|
||||
If this file is missing or corrupted, you can simply remove it and register again.
|
||||
|
||||
Finally, it's time to start the runner.
|
||||
|
||||
|
|
@ -119,7 +129,11 @@ You can upload it as a file with the extension `.yaml` in the directory `.gitea/
|
|||
You might notice that this is fairly similar from the [Quickstart for GitHub Actions](https://docs.github.com/en/actions/quickstart).
|
||||
That is because Gitea Actions is designed to be compatible with GitHub Actions wherever possible.
|
||||
|
||||
Be careful, the demo file contains some emojis. Please make sure your database supports them, especially when using MySQL. If the charset is not `utf8mb4`, errors will occur, such as `Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`. See [Database Preparation](https://docs.gitea.io/en-us/database-prep/#mysql). Alternatively, you can use this demo without emojis:
|
||||
Be careful, the demo file contains some emojis.
|
||||
Please make sure your database supports them, especially when using MySQL.
|
||||
If the charset is not `utf8mb4`, errors will occur, such as `Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`.
|
||||
See [Database Preparation](https://docs.gitea.io/en-us/database-prep/#mysql).
|
||||
Alternatively, you can use this demo without emojis:
|
||||
|
||||
```yaml
|
||||
name: Gitea Actions Demo
|
||||
|
|
@ -142,7 +156,8 @@ jobs:
|
|||
- run: echo "This job's status is ${{ gitea.status }}."
|
||||
```
|
||||
|
||||
The line `on: [push]` indicates that the workflow will be triggered when you push commits to this repository. However, when you upload the YAML file, it also pushes a commit, so you should see a new task in the Actions tab.
|
||||
The line `on: [push]` indicates that the workflow will be triggered when you push commits to this repository.
|
||||
However, when you upload the YAML file, it also pushes a commit, so you should see a new task in the Actions tab.
|
||||
|
||||
|
||||
|
||||
|
|
@ -152,7 +167,8 @@ Great job! You have successfully started working with Actions.
|
|||
|
||||
#### Why is Actions not enabled by default?
|
||||
|
||||
We know it's annoying to enable Actions for the whole instance and each repository one by one, but not everyone likes or needs this feature. We believe that more work needs to be done to improve Gitea Actions before it deserves any further special treatment.
|
||||
We know it's annoying to enable Actions for the whole instance and each repository one by one, but not everyone likes or needs this feature.
|
||||
We believe that more work needs to be done to improve Gitea Actions before it deserves any further special treatment.
|
||||
|
||||
#### Should we use `${{ github.xyz }}` or `${{ gitea.xyz }}` in workflow files?
|
||||
|
||||
|
|
@ -171,26 +187,32 @@ Yes, it depends on where you obtain the registration token.
|
|||
|
||||
If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.
|
||||
|
||||
Please note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. We may provide options to control this in the future.
|
||||
Please note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners.
|
||||
We may provide options to control this in the future.
|
||||
|
||||
#### Is it possible to register runners for a specific user (not organization)?
|
||||
|
||||
Not yet. It is technically possible to implement, but we need to discuss whether it is necessary.
|
||||
Not yet.
|
||||
It is technically possible to implement, but we need to discuss whether it is necessary.
|
||||
|
||||
#### What are the labels for runners used for?
|
||||
|
||||
You may have noticed that every runner has labels such as `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-20.04`, and `ubuntu-18.04`. These labels are used for job matching.
|
||||
You may have noticed that every runner has labels such as `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-20.04`, and `ubuntu-18.04`.
|
||||
These labels are used for job matching.
|
||||
|
||||
For example, `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label. You can also add custom labels to a runner when registering it, which we will discuss later.
|
||||
For example, `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label.
|
||||
You can also add custom labels to a runner when registering it, which we will discuss later.
|
||||
|
||||
#### Where will the runner download scripts when using actions such as `actions/checkout@v3`?
|
||||
|
||||
You may be aware that there are tens of thousands of [marketplace actions](https://github.com/marketplace?type=actions) in GitHub.
|
||||
However, when you write `uses: actions/checkout@v3`, it actually downloads the scripts from [gitea.com/actions/checkout](http://gitea.com/actions/checkout) by default (not GitHub).
|
||||
This is a mirror of [github.com/actions/checkout](http://github.com/actions/checkout), but it's impossible to mirror all of them. That's why you may encounter failures when trying to use some actions that haven't been mirrored.
|
||||
This is a mirror of [github.com/actions/checkout](http://github.com/actions/checkout), but it's impossible to mirror all of them.
|
||||
That's why you may encounter failures when trying to use some actions that haven't been mirrored.
|
||||
|
||||
The good news is that you can specify the URL prefix to use actions from anywhere.
|
||||
This is an extra syntax in Gitea Actions. For example:
|
||||
This is an extra syntax in Gitea Actions.
|
||||
For example:
|
||||
|
||||
- `uses: https://github.com/xxx/xxx@xxx`
|
||||
- `uses: https://gitea.com/xxx/xxx@xxx`
|
||||
|
|
@ -198,15 +220,19 @@ This is an extra syntax in Gitea Actions. For example:
|
|||
|
||||
Be careful, the `https://` or `http://` prefix is necessary!
|
||||
|
||||
Alternatively, 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](https://docs.gitea.io/en-us/config-cheat-sheet/#actions-actions).
|
||||
Alternatively, 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](https://docs.gitea.io/en-us/config-cheat-sheet/#actions-actions).
|
||||
|
||||
This is one of the differences from GitHub Actions, but it should allow users much more flexibility in how they run Actions.
|
||||
|
||||
#### How to limit the permission of the runners?
|
||||
|
||||
Runners have no more permissions than simply connecting to your Gitea instance. When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job. If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](https://docs.gitea.io/en-us/usage/secrets/) to it.
|
||||
Runners have no more permissions than simply connecting to your Gitea instance.
|
||||
When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job.
|
||||
If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](https://docs.gitea.io/en-us/usage/secrets/) to it.
|
||||
|
||||
Refined permission control to Actions is a complicated job. In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
|
||||
Refined permission control to Actions is a complicated job.
|
||||
In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
|
||||
|
||||
#### How to avoid being hacked?
|
||||
|
||||
|
|
@ -227,25 +253,32 @@ Here's how we do it on [gitea.com](http://gitea.com/):
|
|||
|
||||
## Design
|
||||
|
||||
Gitea Actions has multiple parts. Let's explain them one by one.
|
||||
Gitea Actions has multiple parts.
|
||||
Let's explain them one by one.
|
||||
|
||||
### Act
|
||||
|
||||
The [nektos/act](https://github.com/nektos/act) project is an excellent tool that allows you to run your GitHub Actions locally. We were inspired by this and wondered if it would be possible to run actions for Gitea.
|
||||
The [nektos/act](https://github.com/nektos/act) project is an excellent tool that allows you to run your GitHub Actions locally.
|
||||
We were inspired by this and wondered if it would be possible to run actions for Gitea.
|
||||
|
||||
However, while [nektos/act](https://github.com/nektos/act) is designed as a command line tool, what we actually need is a Go library with adjustments for Gitea. So we forked it as [gitea/act](https://gitea.com/gitea/act).
|
||||
However, while [nektos/act](https://github.com/nektos/act) is designed as a command line tool, what we actually need is a Go library with adjustments for Gitea.
|
||||
So we forked it as [gitea/act](https://gitea.com/gitea/act).
|
||||
|
||||
This is a soft fork that will periodically follow the upstream. Although some custom commits have been added, we will try our best to avoid changing too much of the original code.
|
||||
This is a soft fork that will periodically follow the upstream.
|
||||
Although some custom commits have been added, we will try our best to avoid changing too much of the original code.
|
||||
|
||||
The forked act is just a shim or adapter for Gitea's specific usage. There are some additional commits that have been made, such as:
|
||||
The forked act is just a shim or adapter for Gitea's specific usage.
|
||||
There are some additional commits that have been made, such as:
|
||||
|
||||
- Outputting execution logs to logger hook so they can be reported to Gitea
|
||||
- Disabling the GraphQL URL, since Gitea doesn't support it
|
||||
- Starting a new container for every job instead of reusing to ensure isolation.
|
||||
|
||||
These modifications have no reason to be merged into the upstream. They don't make sense if the user just wants to run trusted actions locally.
|
||||
These modifications have no reason to be merged into the upstream.
|
||||
They don't make sense if the user just wants to run trusted actions locally.
|
||||
|
||||
However, there may be overlaps in the future, such as a required bug fix or new feature needed by both projects. In these cases, we will contribute the changes back to the upstream repository.
|
||||
However, there may be overlaps in the future, such as a required bug fix or new feature needed by both projects.
|
||||
In these cases, we will contribute the changes back to the upstream repository.
|
||||
|
||||
### Act runner
|
||||
|
||||
|
|
@ -253,17 +286,22 @@ Gitea's runner is called act runner because it's based on act.
|
|||
|
||||
Like other CI runners, we designed it as an external part of Gitea, which means it should run on a different server than Gitea.
|
||||
|
||||
To ensure that the runner connects to the correct Gitea instance, we need to register it with a token. Additionally, the runner will introduce itself to Gitea and declare what kind of jobs it can run by reporting its labels.
|
||||
To ensure that the runner connects to the correct Gitea instance, we need to register it with a token.
|
||||
Additionally, the runner will introduce itself to Gitea and declare what kind of jobs it can run by reporting its labels.
|
||||
|
||||
Earlier, we mentioned that `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label.
|
||||
But how does the runner know to run `ubuntu-latest`? The answer lies in mapping the label to an environment.
|
||||
That's why when you add custom labels during registration, you will need to input some complex content like `my_custom_label:docker://centos:7`.
|
||||
This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`.
|
||||
|
||||
Docker isn't the only option, though. The act also supports running jobs directly on the host.
|
||||
This is achieved through labels like `linux_arm:host`. This label indicates that the runner can take a job that needs to run on `linux_arm` and run it directly on the host.
|
||||
Docker isn't the only option, though.
|
||||
The act also supports running jobs directly on the host.
|
||||
This is achieved through labels like `linux_arm:host`.
|
||||
This label indicates that the runner can take a job that needs to run on `linux_arm` and run it directly on the host.
|
||||
|
||||
The label's design follows the format `label[:schema[:args]]`. If the schema is omitted, it defaults to `host`. So,
|
||||
The label's design follows the format `label[:schema[:args]]`.
|
||||
If the schema is omitted, it defaults to `host`.
|
||||
So,
|
||||
|
||||
- `my_custom_label:docker://node:18`: Run jobs labeled with `my_custom_label` using the `node:18` Docker image.
|
||||
- `my_custom_label:host`: Run jobs labeled with `my_custom_label` directly on the host.
|
||||
|
|
@ -277,7 +315,8 @@ However, we did not think it was a good idea to have Gitea listen on a new port.
|
|||
Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP.
|
||||
We chose to use gRPC over HTTP.
|
||||
|
||||
We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up. More information about gRPC can be found on [its website](https://grpc.io/).
|
||||
We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up.
|
||||
More information about gRPC can be found on [its website](https://grpc.io/).
|
||||
|
||||
### Network architecture
|
||||
|
||||
|
|
@ -294,7 +333,9 @@ The act runner must be able to connect to Gitea to receive tasks and send back t
|
|||
|
||||
#### Connection 2, job containers to Gitea instance
|
||||
|
||||
The job containers have different network namespaces than the runner, even if they are on the same machine. They need to connect to Gitea to fetch codes if there is `actions/checkout@v3` in the workflow, for example. Fetching code is not always necessary to run some jobs, but it is required in most cases.
|
||||
The job containers have different network namespaces than the runner, even if they are on the same machine.
|
||||
They need to connect to Gitea to fetch codes if there is `actions/checkout@v3` in the workflow, for example.
|
||||
Fetching code is not always necessary to run some jobs, but it is required in most cases.
|
||||
|
||||
If you use a loopback address to register a runner, the runner can connect to Gitea when it is on the same machine.
|
||||
However, if a job container tries to fetch code from localhost, it will fail because Gitea is not in the same container.
|
||||
|
|
@ -313,9 +354,11 @@ In fact, your Gitea instance can serve as both the actions marketplace and the i
|
|||
|
||||
#### Connection 4, job containers to internet
|
||||
|
||||
When using actions such as `actions/setup-go@v4`, it may be necessary to download resources from the internet to set up the Go language environment in job containers. Therefore, access to the internet is required for the successful completion of these actions.
|
||||
When using actions such as `actions/setup-go@v4`, it may be necessary to download resources from the internet to set up the Go language environment in job containers.
|
||||
Therefore, access to the internet is required for the successful completion of these actions.
|
||||
|
||||
However, it is optional as well. You can use your own custom actions to avoid relying on internet access, or you can use your packaged Docker image to run jobs with all dependencies installed.
|
||||
However, it is optional as well.
|
||||
You can use your own custom actions to avoid relying on internet access, or you can use your packaged Docker image to run jobs with all dependencies installed.
|
||||
|
||||
#### Summary
|
||||
|
||||
|
|
@ -329,9 +372,11 @@ If you encounter any network issues while using Gitea Actions, hopefully the ima
|
|||
|
||||
#### Why choose GitHub Actions? Why not something compatible with GitLab CI/CD?
|
||||
|
||||
[@lunny](https://gitea.com/lunny) has explained this in the [issue to implement actions](https://github.com/go-gitea/gitea/issues/13539). Furthermore, Actions is not only a CI/CD system but also an automation tool.
|
||||
[@lunny](https://gitea.com/lunny) has explained this in the [issue to implement actions](https://github.com/go-gitea/gitea/issues/13539).
|
||||
Furthermore, Actions is not only a CI/CD system but also an automation tool.
|
||||
|
||||
There have also been numerous [marketplace actions](https://github.com/marketplace?type=actions) implemented in the open-source world. It is exciting to be able to reuse them.
|
||||
There have also been numerous [marketplace actions](https://github.com/marketplace?type=actions) implemented in the open-source world.
|
||||
It is exciting to be able to reuse them.
|
||||
|
||||
#### Has Gitea Actions achieved full compatibility with GitHub Actions?
|
||||
|
||||
|
|
@ -344,7 +389,8 @@ Not yet, we are working on it.
|
|||
This is valid syntax.
|
||||
It means that it should run on runners that have both the `label_a` **and** `label_b` labels.
|
||||
<!-- TODO: https://discord.com/channels/322538954119184384/323701541297192961/1088938879039570001 -->
|
||||
Unfortunately, act runner does not work this way. As mentioned, we map labels to environments:
|
||||
Unfortunately, act runner does not work this way.
|
||||
As mentioned, we map labels to environments:
|
||||
|
||||
- `ubuntu` → `ubuntu:22.04`
|
||||
- `centos` → `centos:8`
|
||||
|
|
@ -358,7 +404,8 @@ But we need to map label groups to environments instead, like so:
|
|||
We also need to re-design how tasks are assigned to runners.
|
||||
A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`.
|
||||
Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`.
|
||||
This is not a technical problem, it was just overlooked in the early design. See [runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
|
||||
This is not a technical problem, it was just overlooked in the early design.
|
||||
See [runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
|
||||
|
||||
Currently, the act runner attempts to match everyone in the labels and uses the first match it finds.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue