mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-05 01:25:46 +00:00
docs: document self:, builtin:, $/ and runner tracing (#553)
Documents the `self:` and `builtin:` action prefixes from https://github.com/go-gitea/gitea/pull/39358, https://gitea.com/gitea/runner/pulls/1233 and https://gitea.com/gitea/runner/pulls/871, workflow-relative `$/` actions, and the runner's OpenTelemetry tracing from https://gitea.com/gitea/runner/pulls/1206. 1. Trims the action resolution and `DEFAULT_ACTIONS_URL` docs to state each fact once. 1. Drops outdated runner content from the FAQ and design pages. 1. Syncs zh-cn and zh-tw, including a port of the token permissions page they now link to. _Written by Claude._ Reviewed-on: https://gitea.com/gitea/docs/pulls/553 Reviewed-by: bircni <[email protected]> Co-authored-by: silverwind <[email protected]>
This commit is contained in:
silverwind authored and 
bircni committed
1 parent
f9124b16db
commit
c4caf767ad
19 files changed
+476
-444
No files matched your search
@@ -1702,18 +1702,9 @@ PROXY_HOSTS = *.github.com
|
||||
- `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
|
||||
- `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
|
||||
|
||||
`DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
|
||||
For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
|
||||
And it can be changed to `self` to make it `root_url_of_your_gitea/actions/checkout@v4`.
|
||||
|
||||
Please note that using `self` is not recommended for most cases, as it could make names globally ambiguous.
|
||||
Additionally, it requires you to mirror all the actions you need to your Gitea instance, which may not be worth it.
|
||||
Therefore, please use `self` only if you understand what you are doing.
|
||||
|
||||
In earlier versions (`<= 1.19`), `DEFAULT_ACTIONS_URL` could be set to any custom URLs like `https://gitea.com` or `http://your-git-server,https://gitea.com`, and the default value was `https://gitea.com`.
|
||||
However, later updates removed those options, and now the only options are `github` and `self`, with the default value being `github`.
|
||||
However, if you want to use actions from other git server, you can use a complete URL in `uses` field, it's supported by Gitea (but not GitHub).
|
||||
Like `uses: https://gitea.com/actions/checkout@v4` or `uses: http://your-git-server/actions/checkout@v4`.
|
||||
`DEFAULT_ACTIONS_URL` sets where runners download actions without a host.
|
||||
With `github`, `uses: actions/checkout@v4` resolves to `https://github.com/actions/checkout@v4`, with `self` to `<ROOT_URL>/actions/checkout@v4`.
|
||||
`self` requires mirroring every action you use to your instance, so prefer naming the host per action instead: `uses: self:owner/repo@ref` for your instance, or a full URL like `uses: https://gitea.com/actions/checkout@v4` for any other host.
|
||||
|
||||
## Other (`other`)
|
||||
|
||||
|
||||
@@ -6,104 +6,94 @@ sidebar_position: 120
|
||||
|
||||
# Compared to GitHub Actions
|
||||
|
||||
Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them.
|
||||
Gitea Actions is designed to be compatible with GitHub Actions, with the differences below.
|
||||
|
||||
## 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@v4` or `uses: http://your_gitea.com/owner/repo@branch`.
|
||||
`uses:` accepts an absolute URL to any git host, e.g. `uses: https://gitea.com/actions/checkout@v4`.
|
||||
|
||||
### Action prefixes
|
||||
|
||||
`uses:` accepts these prefixes:
|
||||
|
||||
- `self:` references your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
|
||||
- `builtin:` runs an action built into Gitea Runner, which needs no download and no Node in the job image, e.g. `uses: builtin:checkout`
|
||||
|
||||
`builtin:checkout` accepts the `repository`, `ref`, `token`, `path` and `fetch-depth` inputs of `actions/checkout` with the same defaults, and fails on any other input.
|
||||
|
||||
### Workflow-relative actions
|
||||
|
||||
`$/` references the repository and commit of the workflow, or of the enclosing composite action, e.g. `uses: $/.gitea/actions/build`.
|
||||
Unlike `./`, it needs no checkout first.
|
||||
|
||||
### Actions written in Go
|
||||
|
||||
Gitea Actions supports writing actions in Go.
|
||||
See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/).
|
||||
|
||||
### Support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly on schedule
|
||||
|
||||
Github Actions doesn't support that. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
|
||||
`schedule` also accepts `@yearly`, `@monthly`, `@weekly`, `@daily` and `@hourly`, which [GitHub does not](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
|
||||
|
||||
## Unsupported workflows syntax
|
||||
|
||||
### `jobs.<job_id>.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.
|
||||
[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.
|
||||
|
||||
### 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).
|
||||
[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) supports:
|
||||
|
||||
Gitea Actions supports:
|
||||
- Static strings: `runs-on: self-hosted`
|
||||
- Arrays of labels: `runs-on: [linux, self-hosted]`
|
||||
- String expressions: `runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
|
||||
- Arrays containing expressions: `runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
|
||||
|
||||
|
||||
## Missing features
|
||||
|
||||
### Package repository authorization
|
||||
|
||||
The `GITEA_TOKEN` for a job running within a repository should be able to publish to the associated package repository (i.e. to upload OCI images). See the "packages" scope for the "default access" in [Automatic token authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
|
||||
|
||||
This is not implemented in Gitea Actions now. A workaround for Gitea Actions is to use a Personal Access Token (PAT). See this [github issue and comment](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692) for tracking this feature.
|
||||
`GITEA_TOKEN` cannot publish to the package registry of its repository, e.g. to push OCI images.
|
||||
Use a personal access token instead, see [this issue](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692).
|
||||
|
||||
### 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.
|
||||
[Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.
|
||||
|
||||
### 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.
|
||||
[Error annotations](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) are ignored.
|
||||
|
||||
### Expressions
|
||||
|
||||
For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), Gitea Actions supports standard GitHub functions (e.g. `success()`, `failure()`, `always()`, `cancelled()`, `format()`, `toJSON()`) and context variables (like `github`, `matrix`, `vars`, `env`).
|
||||
[Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions) support the standard GitHub functions and contexts.
|
||||
|
||||
## Missing UI features
|
||||
|
||||
### Pre and Post steps
|
||||
|
||||
Pre and Post steps don't have their own section in the job log user interface.
|
||||
Pre and post steps have no section of their own in the job log.
|
||||
|
||||
### Services steps
|
||||
|
||||
Services steps don't have their own section in the job log user interface.
|
||||
Service steps have no section of their own in the job log.
|
||||
|
||||
## Different behavior
|
||||
|
||||
### Job token permissions (`permissions`)
|
||||
|
||||
Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
|
||||
|
||||
The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
|
||||
GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
|
||||
|
||||
`permissions` and `jobs.<job_id>.permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access.
|
||||
GitHub-only scopes like `statuses`, `checks`, `deployments`, `id-token`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`.
|
||||
See [Actions job token permissions](token-permissions.md).
|
||||
|
||||
### Downloading actions
|
||||
|
||||
Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
|
||||
We have since restricted this option to only allow two values (`github` and `self`).
|
||||
When set to `github`, the new default, Gitea will download non-fully-qualified actions from `https://github.com`.
|
||||
For example, if you use `uses: actions/checkout@v4`, it will download the checkout repository from `https://github.com/actions/checkout.git`.
|
||||
|
||||
If you want to download an action from another git hoster, you can use an absolute URL, e.g. `uses: https://gitea.com/actions/checkout@v4`.
|
||||
|
||||
If your Gitea instance is in an intranet or a restricted area, you can set the URL to `self` to only download actions from your own instance by default.
|
||||
Of course, you can still use absolute URLs in workflows.
|
||||
|
||||
More details about the `[actions].DEFAULT_ACTIONS_URL` configuration can be found in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`.
|
||||
See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
|
||||
For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-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).
|
||||
[Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability) is not checked, so contexts like `env` work in more places.
|
||||
@@ -19,7 +19,7 @@ Additionally, the runner will introduce itself to Gitea and declare what kind of
|
||||
|
||||
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`.
|
||||
That's why each label of a runner names an environment, 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.
|
||||
@@ -34,7 +34,6 @@ 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
|
||||
|
||||
@@ -43,7 +42,7 @@ 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.
|
||||
The protocol is defined in [actions-proto-def](https://gitea.com/gitea/actions-proto-def), its Go code lives in [actionslib](https://gitea.com/gitea/actionslib).
|
||||
More information about gRPC can be found on [its website](https://grpc.io/).
|
||||
|
||||
## Network architecture
|
||||
@@ -71,7 +70,8 @@ However, if a job container tries to fetch code from localhost, it will fail bec
|
||||
### Connection 3, runner to internet
|
||||
|
||||
When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
|
||||
By default, it downloads from [github.com](http://github.com/), so it requires access to the internet. If you configure the `DEFAULT_ACTIONS_URL` to `self`, then it will download from your Gitea instance by default. Then it will not connect to internet when downloading the action itself.
|
||||
By default, it downloads them from [github.com](https://github.com/), which requires internet access.
|
||||
With `DEFAULT_ACTIONS_URL` set to `self`, or with `uses: self:owner/repo@ref`, it downloads them from your Gitea instance instead.
|
||||
It also downloads some docker images from Docker Hub by default, which also requires internet access.
|
||||
|
||||
However, internet access is not strictly necessary.
|
||||
|
||||
+17
-69
@@ -27,50 +27,24 @@ Still, this is completely optional since both options have the same effect at th
|
||||
|
||||
## Where will the runner download scripts when using actions such as `actions/checkout@v4`?
|
||||
|
||||
There are tens of thousands of [actions scripts](https://github.com/marketplace?type=actions) in GitHub, and when you write `uses: actions/checkout@v4`, it downloads the scripts from [github.com/actions/checkout](http://github.com/actions/checkout) by default.
|
||||
But what if you want to use actions from other places such as gitea.com instead of GitHub?
|
||||
From `https://github.com` by default, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`, see the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
|
||||
|
||||
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:
|
||||
To use an action from elsewhere, name its host:
|
||||
|
||||
- `uses: https://gitea.com/xxx/xxx@xxx`
|
||||
- `uses: https://github.com/xxx/xxx@xxx`
|
||||
- `uses: http://your_gitea_instance.com/xxx@xxx`
|
||||
|
||||
Be careful, the `https://` or `http://` prefix is necessary!
|
||||
|
||||
This is one of the differences from GitHub Actions which supports actions scripts only from GitHub.
|
||||
But it should allow users much more flexibility in how they run Actions.
|
||||
|
||||
Alternatively, if you want your runners to download actions from your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`.
|
||||
See [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
|
||||
- `uses: https://gitea.com/owner/repo@ref`
|
||||
- `uses: http://your_gitea_instance.com/owner/repo@ref`
|
||||
- `uses: self:owner/repo@ref` for your own Gitea instance
|
||||
|
||||
## 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](usage/actions/secrets.md) 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.
|
||||
Runners only connect to your Gitea instance.
|
||||
For each job, a runner gets a `GITEA_TOKEN` limited to the job's repository, see [Actions job token permissions](token-permissions.md).
|
||||
To give a job access to more private repositories or external systems, pass it [secrets](usage/actions/secrets.md).
|
||||
|
||||
## Which operating systems are supported by Gitea Runner?
|
||||
|
||||
We released official binaries for Linux, macOS, and Windows.
|
||||
While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
|
||||
|
||||
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
|
||||
```
|
||||
Official binaries are released for Linux, macOS and Windows.
|
||||
Other systems supported by Go and Docker work in theory.
|
||||
|
||||
## How to avoid being hacked?
|
||||
|
||||
@@ -99,42 +73,13 @@ 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, the runner does not work this way until v0.2.11.
|
||||
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/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
|
||||
|
||||
Currently, the runner attempts to match everyone in the labels and uses the first match it finds.
|
||||
The job runs on a runner that has all of the labels, as on [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
|
||||
The runner uses the environment of the first label it has.
|
||||
|
||||
## What is the difference between agent labels and custom labels for a runner?
|
||||
|
||||
|
||||
|
||||
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/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.
|
||||
Gitea no longer has custom labels.
|
||||
A runner declares its labels every time it starts, from its `runner.labels` configuration or the labels given at registration, so change them there and restart the runner.
|
||||
|
||||
## Will there be more implementations for Gitea Actions runner?
|
||||
|
||||
@@ -177,3 +122,6 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
|
||||
|
||||
Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
|
||||
The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.
|
||||
|
||||
To share within the same user or organization, add the private repositories under its **Settings** > **Actions** > **General** > **Cross-Repository Access** instead.
|
||||
See [Cross-repository access](token-permissions.md#cross-repository-access).
|
||||
@@ -102,8 +102,8 @@ Only a workflow that runs on an event that posts a commit status (`push`, `pull_
|
||||
|
||||
Scoped workflows can call reusable workflows:
|
||||
|
||||
- A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
|
||||
- A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
|
||||
- A **local** reference (`uses: ./...` or `uses: $/...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
|
||||
- A **cross-repository** reference (`uses: owner/repo/...@ref` or `uses: self:owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
|
||||
|
||||
A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
|
||||
|
||||
|
||||
Reference in new issue
Block a user