diff --git a/docs/content/doc/actions.en-us.md b/docs/content/doc/actions.en-us.md new file mode 100644 index 000000000..7cd2ba054 --- /dev/null +++ b/docs/content/doc/actions.en-us.md @@ -0,0 +1,13 @@ +--- +date: "2023-04-27T14:00:00+08:00" +title: "Actions" +slug: "actions" +weight: 36 +toc: false +draft: false +menu: + sidebar: + name: "Usage - Actions" + weight: 31 + identifier: "actions" +--- diff --git a/docs/content/doc/actions/act-runner.en-us.md b/docs/content/doc/actions/act-runner.en-us.md new file mode 100644 index 000000000..7c1f5c73c --- /dev/null +++ b/docs/content/doc/actions/act-runner.en-us.md @@ -0,0 +1,206 @@ +--- +date: "2023-04-27T15:00:00+08:00" +title: "Act Runner" +slug: "usage/actions/act-runner" +weight: 20 +draft: false +toc: false +menu: + sidebar: + parent: "actions" + name: "Act Runner" + weight: 20 + identifier: "actions-runner" +--- + +# Act Runner + +This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner of Gitea Actions. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +It is recommended to run jobs in a docker container, so you need to install docker first. +And make sure that the docker daemon is running. + +Other OCI container engines which are compatible with Docker's API should also work, but are untested. + +However, if you are sure that you want to run jobs directly on the host only, then docker is not required. + +## Installation + +There are multiple ways to install the act runner. + +### Download the binary + +You can download the binary from the [release page](https://gitea.com/gitea/act_runner/releases). +However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/act_runner/). + +When you download the binary, please make sure that you have downloaded the correct one for your platform. +You can check it by running the following command: + +```bash +chmod +x act_runner +./act_runner --version +``` + +If you see the version information, it means that you have downloaded the correct binary. + +### Use the docker image + +You can use the docker image from the [docker hub](https://hub.docker.com/r/gitea/act_runner/tags). +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. + +```bash +docker pull gitea/act_runner:latest # for the latest stable release +docker pull gitea/act_runner:nightly # for the latest nightly build +``` + +## Configuration + +Configuration is done via a configuration file. It is optional, and the default configuration will be used when no configuration file is specified. + +You can generate a configuration file by running the following command: + +```bash +./act_runner generate-config +``` + +The default configuration is safe to use without any modification, so you can just use it directly. + +```bash +./act_runner generate-config > config.yaml +./act_runner --config config.yaml [command] +``` + +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: + +```bash +docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ... +``` + +You may notice the commands above are both incomplete, because it is not the time to run the act runner yet. +Before running the act runner, we need to register it to your Gitea instance first. + +## Registration + +Registration is required before running the act runner, because the runner needs to know where to get jobs from. +And it is also important to Gitea instance to identify the runner. + +### Runner levels + +You can register a runner in different levels, it can be: + +- Instance level: The runner will run jobs for all repositories in the instance. +- Organization level: The runner will run jobs for all repositories in the organization. +- Repository level: The runner will run jobs for the repository it belongs to. + +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. + +### Obtain a registration token + +The level of the runner determines where to obtain the registration token. + +- Instance level: The admin settings page, like `/admin/runners`. +- Organization level: The organization settings page, like `//settings/runners`. +- Repository level: The repository settings page, like `///settings/runners`. + +If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled. + +The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`. + +### Register the runner + +The act runner can be registered by running the following command: + +```bash +./act_runner register +``` + +Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section. + +```bash +./act_runner --config config.yaml register +``` + +You will be asked to input the registration information step by step. Includes: + +- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`. +- The registration token. +- The runner name, which is optional. If you leave it blank, the hostname will be used. +- The runner labels, which is optional. If you leave it blank, the default labels will be used. + +You may be confused about the runner labels, which will be explained later. + +If you want to register the runner in a non-interactive way, you can use arguments to do it. + +```bash +./act_runner register --no-interactive --instance --token --name --labels +``` + +When you have registered the runner, you can find a new file named `.runner` 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. + +If you want to store the registration information in another place, you can specify it in the configuration file, +and don't forget to specify the `--config` option. + +### Register the runner with docker + +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. + +```bash +docker run \ + -v $(pwd)/config.yaml:/config.yaml \ + -v $(pwd)/data:/data \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -e CONFIG_FILE=/config.yaml \ + -e GITEA_INSTANCE_URL= \ + -e GITEA_RUNNER_REGISTRATION_TOKEN= \ + -e GITEA_RUNNER_NAME= \ + -e GITEA_RUNNER_LABELS= \ + --name my_runner \ + -d gitea/act_runner:nightly +``` + +You may notice that we have mounted the `/var/run/docker.sock` into the container. +It is because the act runner will run jobs in docker containers, so it needs to communicate with the docker daemon. +As mentioned, you can remove it if you want to run jobs in the host directly. +To be clear, the "host" actually means the container which is running the act runner now, instead of the host machine. + +### Labels + +The labels of a runner are used to determine which jobs the runner can run, and how to run them. + +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`. +It is a comma-separated list, and each item is a label. + +Let's take `ubuntu-22.04:docker://node:16-bullseye` as an example. +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`. + +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://`. +You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md). + +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. +However, we suggest you to use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it. + +One more thing is that it is recommended to register the runner if you want to change the labels. +It may be annoying to do this, so we may provide a better way to do it in the future. + +## Running + +After you have registered the runner, you can run it by running the following command: + +```bash +./act_runner daemon +# or +./act_runner daemon --config config.yaml +``` + +The runner will fetch jobs from the Gitea instance and run them automatically. + +Since act runner is still in development, it is recommended to check the latest version and upgrade it regularly. diff --git a/docs/content/doc/actions/comparison.en-us.md b/docs/content/doc/actions/comparison.en-us.md new file mode 100644 index 000000000..f916440af --- /dev/null +++ b/docs/content/doc/actions/comparison.en-us.md @@ -0,0 +1,171 @@ +--- +date: "2023-04-27T15:00:00+08:00" +title: "Compared to GitHub Actions" +slug: "usage/actions/comparison" +weight: 30 +draft: false +toc: false +menu: + sidebar: + parent: "actions" + name: "Comparison" + weight: 30 + identifier: "actions-comparison" +--- + +# Compared to GitHub Actions + +Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them. + +**Table of Contents** + +{{< toc >}} + +## Additional features + +### Absolute action URLs + +Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository. +Like `uses: https://github.com/actions/checkout@v3` or `uses: http://your_gitea.com/owner/repo@branch`. + +### Actions written in Go + +Gitea Actions supports writing actions in Go. +See [Creating Go Actions](https://blog.gitea.io/2023/04/creating-go-actions/). + +## Unsupported workflows syntax + +### `concurrency` + +It's used to run a single job at a time. +See [Using concurrency](https://docs.github.com/en/actions/using-jobs/using-concurrency). + +It's ignored by Gitea Actions now. + +### `run-name` + +The name for workflow runs generated from the workflow. +See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name). + +It's ignored by Gitea Actions now. + +### `permissions` and `jobs..permissions` + +See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions). + +It's ignored by Gitea Actions now. + +### `jobs..timeout-minutes` + +See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes). + +It's ignored by Gitea Actions now. + +### `jobs..continue-on-error` + +See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error). + +It's ignored by Gitea Actions now. + +### `jobs..environment` + +See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment). + +It's ignored by Gitea Actions now. + +### Complex `runs-on` + +See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on). + +Gitea Actions only supports `runs-on: xyz` or `runs-on: [xyz]` now. + +### `workflow_dispatch` + +See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch). + +It's ignored by Gitea Actions now. + +### `hashFiles` expression + +See [Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles) + +Gitea Actions doesn't support it now, if you use it, the result will always be empty string. + +As a workaround, you can use [go-hashfiles](https://gitea.com/actions/go-hashfiles) instead. + +## Missing features + +### Variables + +See [Variables](https://docs.github.com/en/actions/learn-github-actions/variables). + +It's under development. + +### Problem Matchers + +Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI. +See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md). + +It's ignored by Gitea Actions now. + +### Create an error annotation + +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) + +It's ignored by Gitea Actions now. + +## Missing UI features + +### Pre and Post steps + +Pre and Post steps don't have their own section in the job log user interface. + +## Different behavior + +### Downloading actions + +Gitea Actions doesn't download actions from GitHub by default. +"By default" means that you don't specify the host in the `uses` field, like `uses: actions/checkout@v3`. +As a contrast, `uses: https://github.com/actions/checkout@v3` has specified host. + +The missing host will be filled with `https://gitea.com` if you don't configure it. +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). + +As mentioned, it's configurable. +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" > }})). + +### Context availability + +Context availability is not checked, so you can use the env context on more places. +See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability). + +## Known issues + +### `docker/build-push-action@v4` + +See [act_runner#119](https://gitea.com/gitea/act_runner/issues/119#issuecomment-738294). + +`ACTIONS_RUNTIME_TOKEN` is a random string in Gitea Actions, not a JWT. +But the `docker/build-push-action@v4` tries to parse the token as JWT and doesn't handle the error, so the job fails. + +There are two workarounds: + +Set the `ACTIONS_RUNTIME_TOKEN` to empty manually, like: + +``` yml +- name: Build and push + uses: docker/build-push-action@v4 + env: + ACTIONS_RUNTIME_TOKEN: '' + with: +... +``` + +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: + +``` yml +- name: Build and push + uses: docker/build-push-action@master + with: +... +``` diff --git a/docs/content/doc/actions/design.en-us.md b/docs/content/doc/actions/design.en-us.md new file mode 100644 index 000000000..45764079f --- /dev/null +++ b/docs/content/doc/actions/design.en-us.md @@ -0,0 +1,135 @@ +--- +date: "2023-04-27T15:00:00+08:00" +title: "Design of Gitea Actions" +slug: "usage/actions/design" +weight: 40 +draft: false +toc: false +menu: + sidebar: + parent: "actions" + name: "Design" + weight: 40 + identifier: "actions-design" +--- + +# Design of Gitea Actions + +Gitea Actions has multiple components. This document describes them individually. + +**Table of Contents** + +{{< toc >}} + +## 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. + +However, while [nektos/act](https://github.com/nektos/act) is designed as a command line tool, what we actually needed was a Go library with modifications specifically 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. + +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. + +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 + +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. + +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. + +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. +- `my_custom_label`: Same as `my_custom_label:host`. +- `my_custom_label:vm:ubuntu-latest`: (Example only, not implemented) Run jobs labeled with `my_custom_label` using a virtual machine with the `ubuntu-latest` ISO. + +## Communication protocol + +As act runner is an independent part of Gitea, we needed a protocol for runners to communicate with the Gitea instance. +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/). + +## Network architecture + +Let's examine the overall network architecture. +This will help you troubleshoot some problems and explain why it's a bad idea to register a runner with a loopback address of the Gitea instance. + +![network](/images/usage/actions/network.png) + +There are four network connections marked in the picture, and the direction of the arrows indicates the direction of establishing the connections. + +### Connection 1, act runner to Gitea instance + +The act runner must be able to connect to Gitea to receive tasks and send back the execution results. + +### 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. + +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. + +### Connection 3, act runner to internet + +When you use some actions like `actions/checkout@v3`, the act runner downloads the scripts, not the job containers. +By default, it downloads from [gitea.com](http://gitea.com/), so it requires access to the internet. +It also downloads some docker images from Docker Hub by default, which also requires internet access. + +However, internet access is not strictly necessary. +You can configure your Gitea instance to fetch actions or images from your intranet facilities. + +In fact, your Gitea instance can serve as both the actions marketplace and the image registry. +You can mirror actions repositories from GitHub to your Gitea instance, and use them as normal. +And [Gitea Container Registry](https://docs.gitea.io/en-us/usage/packages/container/) can be used as a Docker image registry. + +### 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. + +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 + +Using Gitea Actions only requires ensuring that the runner can connect to the Gitea instance. +Internet access is optional, but not having it will require some additional work. +In other words: The runner works best when it can query the internet itself, but you don't need to expose it to the internet (in either direction). + +If you encounter any network issues while using Gitea Actions, hopefully the image above can help you troubleshoot them. diff --git a/docs/content/doc/actions/faq.en-us.md b/docs/content/doc/actions/faq.en-us.md new file mode 100644 index 000000000..bec41db3e --- /dev/null +++ b/docs/content/doc/actions/faq.en-us.md @@ -0,0 +1,166 @@ +--- +date: "2023-04-27T15:00:00+08:00" +title: "Frequently Asked Questions of Gitea Actions" +slug: "usage/actions/faq" +weight: 100 +draft: false +toc: false +menu: + sidebar: + parent: "actions" + name: "FAQ" + weight: 100 + identifier: "actions-faq" +--- + +# Frequently Asked Questions of Gitea Actions + +This page contains some common questions and answers about Gitea Actions. + +**Table of Contents** + +{{< toc >}} + +## 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. + +## Is it possible to enable Actions for new repositories by default for my own instance? + +Yes, when you enable Actions for the instance, you can choose to enable the `actions` unit for all new repositories by default. + +```ini +[repository] +DEFAULT_REPO_UNITS = ...,repo.actions +``` + +## Should we use `${{ github.xyz }}` or `${{ gitea.xyz }}` in workflow files? + +You can use `github.xyz` and Gitea will work fine. +As mentioned, Gitea Actions is designed to be compatible with GitHub Actions. +However, we recommend using `gitea.xyz` in case Gitea adds something that GitHub does not have to avoid different kinds of secrets in your workflow file (and because you are using this workflow on Gitea, not GitHub). +Still, this is completely optional since both options have the same effect at the moment. + +## 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. + +## 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. + +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: + +- `uses: https://github.com/xxx/xxx@xxx` +- `uses: https://gitea.com/xxx/xxx@xxx` +- `uses: http://your_gitea_instance.com/xxx@xxx` + +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). + +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. + +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? + +There are two types of possible attacks: unknown runner stealing the code or secrets from your repository, or malicious scripts controlling your runner. + +Avoiding the former means not allowing people you don't know to register runners for your repository, organization, or instance. + +The latter is a bit more complicated. +If you're using a private Gitea instance for your company, you may not need to worry about security since you trust your colleagues and can hold them accountable. + +For public instances, things are a little different. +Here's how we do it on [gitea.com](http://gitea.com/): + +- We only register runners for the "gitea" organization, so our runners will not execute jobs from other repositories. +- Our runners always run jobs with isolated containers. While it is possible to do this directly on the host, we choose not to for more security. +- To run actions for fork pull requests, approval is required. See [#22803](https://github.com/go-gitea/gitea/pull/22803). +- If someone registers their own runner for their repository or organization on [gitea.com](http://gitea.com/), we have no objections and will just not use it in our org. However, they should take care to ensure that the runner is not used by other users they do not know. + +## Which operating systems are supported by act runner? + +It works well on Linux, macOS, and Windows. +While other operating systems are theoretically supported, they require further testing. + +One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures. + +For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default. +Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun). + +```yaml +defaults: + run: + shell: powershell +``` + +## 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. + +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. + +## What if it runs on multiple labels, such as `runs-on: [label_a, label_b]`? + +This is valid syntax. +It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on). +Unfortunately, act runner does not work this way. +As mentioned, we map labels to environments: + +- `ubuntu` → `ubuntu:22.04` +- `centos` → `centos:8` + +But we need to map label groups to environments instead, like so: + +- `[ubuntu]` → `ubuntu:22.04` +- `[with-gpu]` → `linux:with-gpu` +- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu` + +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). + +Currently, the act runner attempts to match everyone in the labels and uses the first match it finds. + +## What is the difference between agent labels and custom labels for a runner? + +![labels](/images/usage/actions/labels.png) + +Agent labels are reported to the Gitea instance by the runner during registration. +Custom labels, on the other hand, are added manually by a Gitea administrator or owners of the organization or repository (depending on the level of the runner). + +However, the design here needs improvement, as it currently has some rough edges. +You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`. +However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end. +This default may not match user expectations. +See [runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71). + +In the meantime, we suggest that you re-register your runner if you want to change its labels. + +## Will there be more implementations for Gitea Actions runner? + +Although we would like to provide more options, our limited manpower means that act runner will be the only officially supported runner. +However, both Gitea and act runner are completely open source, so anyone can create a new/better implementation. +We support your choice, no matter how you decide. +In case you fork act runner to create your own version: Please contribute the changes back if you can and if you think your changes will help others as well. diff --git a/docs/content/doc/actions/overview.en-us.md b/docs/content/doc/actions/overview.en-us.md new file mode 100644 index 000000000..ef52465e2 --- /dev/null +++ b/docs/content/doc/actions/overview.en-us.md @@ -0,0 +1,55 @@ +--- +date: "2023-04-27T15:00:00+08:00" +title: "Gitea Actions" +slug: "usage/actions/overview" +weight: 1 +draft: false +toc: false +menu: + sidebar: + parent: "actions" + name: "Overview" + weight: 1 + identifier: "actions-overview" +--- + +# Gitea Actions + +Starting with Gitea **1.19**, Gitea Actions are available as a built-in CI/CD solution. + +**Table of Contents** + +{{< toc >}} + +## Name + +It is similar and compatible to [GitHub Actions](https://github.com/features/actions), and its name is inspired by it too. +To avoid confusion, we have clarified the spelling here: + +- "Gitea Actions" (with an "s", both words capitalized) is the name of the Gitea feature. +- "GitHub Actions" is the name of the GitHub feature. +- "Actions" could refer to either of the above, depending on the context. So it refers to "Gitea Actions" in this document. +- "action" or "actions" refer to some scripts/plugins to be used, like "actions/checkout@v3" or "actions/cache@v3". + +## Runners + +Just like other CI/CD solutions, Gitea doesn't run the jobs itself, but delegates the jobs to runners. +The runner of Gitea Actions is called [act runner](https://gitea.com/gitea/act_runner), it is a standalone program and also written in Go. +It is based on a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act). + +Because the runner is deployed independently, there could be potential security issues. +To avoid them, please follow two simple rules: + +- Don't use a runner you don't trust for your repository, organization or instance. +- Don't provide a runner to a repository, organization or instance you don't trust. + +For Gitea instances used internally, such as instances used by enterprises or individuals, neither of these two rules is a problem, they are naturally so. +However, for public Gitea instances, such as [gitea.com](https://gitea.com), these two rules should be kept in mind when adding or using runners. + +## Status + +Gitea Actions is still under development, so there may be some bugs and missing features. +And breaking changes may be made before it's stable (v1.20 or later). + +If the situation changes, we will update it here. +So please refer to the content here when you find outdated articles elsewhere. diff --git a/docs/content/doc/actions/quickstart.en-us.md b/docs/content/doc/actions/quickstart.en-us.md new file mode 100644 index 000000000..74bbedea2 --- /dev/null +++ b/docs/content/doc/actions/quickstart.en-us.md @@ -0,0 +1,141 @@ +--- +date: "2023-04-27T15:00:00+08:00" +title: "Quick Start" +slug: "usage/actions/quickstart" +weight: 10 +draft: false +toc: false +menu: + sidebar: + parent: "actions" + name: "Quick Start" + weight: 10 + identifier: "actions-quickstart" +--- + +# Quick Start + +This page will guide you through the process of using Gitea Actions. + +**Table of Contents** + +{{< toc >}} + +## Set up Gitea + +First of all, you need a Gitea instance. +You can follow the [documentation]({{ < relref "doc/installation/from-package.en-us.md" > }}) to set up a new instance or upgrade your existing one. +It doesn't matter how you install or run Gitea, as long as its version is 1.19.0 or higher. + +Actions are disabled by default, so you need to add the following to the configuration file to enable it: + +```ini +[actions] +ENABLED=true +``` + +If you want to learn more or encounter any problems while configuring it, please refer to the [Configuration Cheat Sheet]({{ < relref "doc/administration/config-cheat-sheet.en-us.md#actions-actions" > }}). + +### Set up runner + +Gitea Actions requires [act runner](https://gitea.com/gitea/act_runner) to run the jobs. +In order to avoid consuming too many resources and affecting the Gitea instance, it is recommended to start runners on separate machines from the Gitea instance. + +You can use the [pre-built binaries](http://dl.gitea.com/act_runner) or the [docker images](https://hub.docker.com/r/gitea/act_runner/tags) to set up the runner. + +Before proceeding any further, we suggest running it as a command line with pre-built binaries to ensure that it works with your environment, especially if you are running a runner on your local host. +And it could be easier to debug if something goes wrong. + +The runner can run the jobs in isolated Docker containers, so you need to make sure that the Docker has been installed and Docker daemon is running. +While it is not strictly necessary, because the runner can also run the jobs directly on the host, it depends on how you configure it. +However, it is recommended to use Docker to run the jobs, because it is more secure and easier to manage. + +Before running a runner, you should first register it to your Gitea instance using the following command: + +```bash +./act_runner register --no-interactive --instance --token +``` + +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`. +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. +You can obtain tokens from `/admin/runners`. + +![register runner](/images/usage/actions/register-runner.png) + +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: + +```bash +./act_runner daemon +``` + +And you can see the new runner in the management page: + +![view runner](/images/usage/actions/view-runner.png) + +You can find more information by visiting [Act runner]({{ < relref "doc/actions/act-runner.en-us.md" > }}). + +### Use Actions + +Even if Actions is enabled for the Gitea instance, repositories still disable Actions by default. + +To enable it, go to the settings page of your repository like `your_gitea.com//repo/settings` and enable `Enable Repository Actions`. + +![enable actions](/images/usage/actions/enable-actions.png) + +The next steps may be rather complicated. +You will need to study [the workflow syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) for Actions and write the workflow files you want. + +However, we can just start from a simple demo: + +```yaml +name: Gitea Actions Demo +run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀 +on: [push] + +jobs: + Explore-Gitea-Actions: + runs-on: ubuntu-latest + steps: + - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event." + - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!" + - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}." + - name: Check out repository code + uses: actions/checkout@v3 + - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner." + - run: echo "🖥️ The workflow is now ready to test your code on the runner." + - name: List files in the repository + run: | + ls ${{ gitea.workspace }} + - run: echo "🍏 This job's status is ${{ gitea.status }}." +``` + +You can upload it as a file with the extension `.yaml` in the directory `.gitea/workflows/` of the repository, for example `.gitea/workflows/demo.yaml`. +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]( {{ < relref "doc/installation/database-preparation.en-us.md#mysql" > }}) for more information. + +Alternatively, you can remove all emojis from the demo file and try again. + +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. + +![view job](/images/usage/actions/view-job.png) + +Great job! You have successfully started working with Actions. diff --git a/docs/content/doc/usage/push.zh-tw.md b/docs/content/doc/usage/push.zh-tw.md index 5fe5052c1..7647b6b02 100644 --- a/docs/content/doc/usage/push.zh-tw.md +++ b/docs/content/doc/usage/push.zh-tw.md @@ -54,7 +54,7 @@ Push to create is a feature that allows you to push to a repository that does no ## Enabling Push To Create -In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet]({{< relref "doc/administration/config-cheat-sheet.zh-tw.md#repository-repository" >}}). +In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet]({{ < relref "doc/administration/config-cheat-sheet.zh-tw.md#repository-repository" > }}). ## Using Push To Create diff --git a/docs/static/images/usage/actions/enable-actions.png b/docs/static/images/usage/actions/enable-actions.png new file mode 100644 index 000000000..8e38bd9a8 Binary files /dev/null and b/docs/static/images/usage/actions/enable-actions.png differ diff --git a/docs/static/images/usage/actions/labels.png b/docs/static/images/usage/actions/labels.png new file mode 100644 index 000000000..d6e847950 Binary files /dev/null and b/docs/static/images/usage/actions/labels.png differ diff --git a/docs/static/images/usage/actions/network.png b/docs/static/images/usage/actions/network.png new file mode 100644 index 000000000..afaa5ddd3 Binary files /dev/null and b/docs/static/images/usage/actions/network.png differ diff --git a/docs/static/images/usage/actions/register-runner.png b/docs/static/images/usage/actions/register-runner.png new file mode 100644 index 000000000..a260e44f4 Binary files /dev/null and b/docs/static/images/usage/actions/register-runner.png differ diff --git a/docs/static/images/usage/actions/view-job.png b/docs/static/images/usage/actions/view-job.png new file mode 100644 index 000000000..493869969 Binary files /dev/null and b/docs/static/images/usage/actions/view-job.png differ diff --git a/docs/static/images/usage/actions/view-runner.png b/docs/static/images/usage/actions/view-runner.png new file mode 100644 index 000000000..f25d2643f Binary files /dev/null and b/docs/static/images/usage/actions/view-runner.png differ