gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-08 14:35:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add 1.27 rc0 documentation (#453)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/453
Reviewed-by: Zettat123 <39446+zettat123@noreply.gitea.com>
This commit is contained in:
Lunny Xiao
2026-07-01 17:14:52 +00:00
parent 24fdff218d
commit 1033f033bc
328 changed files with 75235 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
versioned_docs/version-1.27/usage/actions/_category_.json Normal file
View File

@@ -0,0 +1,9 @@
{
"label": "Actions",
"position": 30,
"link": {
"type": "generated-index",
"slug": "/usage/actions",
"description": "Automating workflows with Actions"
}
}

27
versioned_docs/version-1.27/usage/actions/badge.md Normal file
View File

@@ -0,0 +1,27 @@
---
date: "2023-02-25T00:00:00+00:00"
slug: "badge"
sidebar_position: 110
---
# Badge
Gitea has its builtin Badge system which allows you to display the status of your repository in other places. You can use the following badges:
## Workflow Badge
The Gitea Actions workflow badge is a badge that shows the status of the latest workflow run.
It is designed to be compatible with [GitHub Actions workflow badge](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge).
You can use the following URL to get the badge:
```
https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}/badge.svg?branch={branch}&event={event}&style={style}
```
- `{owner}`: The owner of the repository.
- `{repo}`: The name of the repository.
- `{workflow_file}`: The name of the workflow file.
- `{branch}`: Optional. The branch of the workflow. Default to your repository's default branch.
- `{event}`: Optional. The event of the workflow. Default to none.
- `{style}`: Optional. Style of the badge, either `flat` or `flat-square`. Default to `flat`.

104
versioned_docs/version-1.27/usage/actions/comparison.md Normal file
View File

@@ -0,0 +1,104 @@
---
date: "2023-04-27T15:00:00+08:00"
slug: "comparison"
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.
## 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`.
### 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
## 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.
### 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.
## 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.
### 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.
### Expressions
For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), only [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) is supported.
## Missing UI features
### Pre and Post steps
Pre and Post steps don't have their own section in the job log user interface.
### Services steps
Services steps don't have their own section in the job log user interface.
## 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.
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)。
### 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).

98
versioned_docs/version-1.27/usage/actions/design.md Normal file
View File

@@ -0,0 +1,98 @@
---
date: "2023-04-27T15:00:00+08:00"
slug: "design"
sidebar_position: 140
---
# Design of Gitea Actions
Gitea Actions has multiple components. This document describes them individually.
## Gitea Runner
Gitea Runner is based on a hard fork of [nektos/act](https://github.com/nektos/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 runner 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 the 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, runner to Gitea instance
The 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@v4` 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, 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.
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](usage/packages/container.md) can be used as a Docker image registry.
### Connection 4, job containers to internet
When using actions such as `actions/setup-go@v5`, 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.

175
versioned_docs/version-1.27/usage/actions/faq.md Normal file
View File

@@ -0,0 +1,175 @@
---
date: "2023-04-27T15:00:00+08:00"
slug: "faq"
sidebar_position: 200
---
# Frequently Asked Questions
This page contains some common questions and answers about Gitea Actions.
## Is it possible to disable 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]
; remove repo.actions will not enable actions for newly created repositories.
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.
## 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?
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://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).
## 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.
## 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
```
## 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.
## 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, 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.
## 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/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 Gitea Runner will be the only officially supported runner at the moment.
However, both Gitea and Gitea Runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
In case you fork Gitea 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.
## What workflow trigger events does Gitea support?
All events listed in this table are supported events and are compatible with GitHub.
For events supported only by GitHub, see GitHub's [documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows).
| trigger event | activity types |
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
| create | not applicable |
| delete | not applicable |
| fork | not applicable |
| gollum | not applicable |
| push | not applicable |
| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
| issue_comment | `created`, `edited`, `deleted` |
| pull_request | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronized`, `labeled`, `unlabeled` |
| pull_request_review | `submitted`, `edited` |
| pull_request_review_comment | `created`, `edited` |
| release | `published`, `edited` |
| registry_package | `published` |
| workflow_dispatch | not applicable |
| workflow_run | `requested`, `completed` |
> For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
> Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
## How to share actions and reusable workflows from private repositories?
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.

38
versioned_docs/version-1.27/usage/actions/overview.md Normal file
View File

@@ -0,0 +1,38 @@
---
date: "2023-04-27T15:00:00+08:00"
slug: "overview"
sidebar_position: 1
---
# Overview
Starting with Gitea **1.19**, Gitea Actions are available as a built-in CI/CD solution.
## Name
It is similar and mostly 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@v4" 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 [Gitea Runner](https://gitea.com/gitea/runner), it is a standalone program and also written in Go.
An important part of the application comes from a hard fork 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 stable enough for production usage and we use Gitea Actions in all the repositories in https://gitea.com/gitea.

138
versioned_docs/version-1.27/usage/actions/quickstart.md Normal file
View File

@@ -0,0 +1,138 @@
---
date: "2023-04-27T15:00:00+08:00"
slug: "quickstart"
sidebar_position: 10
---
# Quick Start
This page will guide you through the process of using Gitea Actions.
## Set up Gitea
First of all, you need a Gitea instance.
You can follow the [documentation](installation/from-package.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.
Since 1.21.0, Actions are enabled by default. If you are using versions before 1.21.0, 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](../../administration/config-cheat-sheet.md#actions-actions).
### Set up runner
Gitea Actions requires [Gitea Runner](https://gitea.com/gitea/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/gitea-runner) or the [docker images](https://hub.docker.com/r/gitea/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 localhost.
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
./runner register --no-interactive --instance <instance> --token <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`.
Each token can be used to create multiple runners, until it is replaced with a new token using the reset link.
You can obtain different levels of 'tokens' from the following places to create the corresponding level of 'runners':
- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/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
./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 [Gitea Runner](runner.mdx).
### 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/<owner>/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@v4
- 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 ${{ job.status }}."
```
:::warning
Certain actions may not function correctly within SHA256 repositories or when Gitea runs on subpath. This includes [actions/checkout](https://github.com/actions/checkout/issues/1843).
:::
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](../../installation/database-preparation.md#mysqlmariadb) 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.

459
versioned_docs/version-1.27/usage/actions/runner.mdx Normal file
View File

@@ -0,0 +1,459 @@
---
date: "2023-04-27T15:00:00+08:00"
slug: "runner"
sidebar_position: 20
---
# Gitea Runner
This page will introduce the [Gitea Runner](https://gitea.com/gitea/runner) in detail, which is the runner for Gitea Actions.
## Requirements
Currently the runner supports three modes in which it can be run.
1. Host: runner will run as an application on the host. This provides no encapsulation.
2. Docker (recommended): Runs jobs in a [Docker](https://docker.com) container. If you choose this mode, you need to [install Docker](https://docs.docker.com/engine/install/) first and make sure that the Docker daemon is running.
3. Docker-in-Docker (DinD): Puts the runner into rootless mode. It then runs in a Docker container with its own Docker daemon that has fewer privileges. It will spawn job containers from there. Best security but more complex setup.
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.
There are multiple ways to install the runner.
## Installation with binary
### Download the binary
You can download the binary from the [release page](https://gitea.com/gitea/runner/releases).
However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/gitea-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 if you are in a Unix-style OS.
```bash
chmod +x runner
./runner --version
```
If you see the version information, it means that you have downloaded the correct binary.
### Obtain a registration token
You can register a runner at 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.
Before registering the runner and running it, you need a registration token. The level of the runner determines where to obtain the registration token.
- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/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`.
A registration token can also be obtained from the Gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
```
gitea --config /etc/gitea/app.ini actions generate-runner-token
```
You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variables to set a global runner registration token when Gitea starts, for example:
```
openssl rand -hex 24 > /some-dir/runner-token
export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
./gitea --config ...
```
The token from the environment is valid until you reset the token (re-create a new one) via the web UI or API.
Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.
### 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
./runner generate-config
```
The default configuration is safe to use without any modification, so you can just use it directly.
```bash
./runner generate-config > config.yaml
./runner --config config.yaml [command]
```
### Register the runner
Registration is required before running Gitea Runner, because the runner needs to know where to get jobs from. It is also important for the Gitea instance to identify the runner.
If this has been installed using the binary package, the runner can be registered by running the following command.
```bash
./runner register
```
Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section.
```bash
./runner --config config.yaml register
```
You will be asked to input the registration information step by step. This 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
./runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_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.
#### Ephemeral Runners
Ephemeral runners provide a security hardening mechanism for enabling organization- or instance-wide runners without requiring full user trust. Once a job is assigned within a spot VM or container, the runner's exposed credentials are automatically revoked—blocking it from polling further jobs before any untrusted code runs, while still allowing it to report progress until completion by either Gitea or the runner.
Gitea Runner **0.2.12+** is required.
The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the runner.
```bash
./runner register --ephemeral
```
```bash
./runner --config config.yaml register --ephemeral
```
```bash
./runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
```
The runner must be registered each time it is intended to receive a job. After completing the single job it is designed to execute, the runner terminates.
To automate the registration and startup of new runners when a job is queued, use the `workflow_job` webhook.
### Start the runner from the command line
After you have registered the runner, you can run it with the following command:
```shell
./runner daemon
```
or
```bash
./runner daemon --config config.yaml
```
The runner will fetch jobs from the Gitea instance and run them automatically.
### Start the runner with Systemd
It is also possible to run Gitea Runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `runner` user on your system, and create the following file in `/etc/systemd/system/runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `runner` binary, its configuration file, and the home directory of the `runner` user.
```ini
[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/runner
After=docker.service
[Service]
ExecStart=/usr/local/bin/runner daemon --config /etc/runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/runner
TimeoutSec=0
RestartSec=10
Restart=always
User=runner
[Install]
WantedBy=multi-user.target
```
Then:
```bash
# load the new systemd unit file
sudo systemctl daemon-reload
# start the service and enable it at boot
sudo systemctl enable runner --now
```
If using Docker, the `runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
### Start the runner with LaunchDaemon (macOS)
Mac uses `launchd` in place of systemd for registering daemon processes. By default, daemons run as the root user, so if desired an unprivileged `_runner` user can be created via the `dscl` tool. The following file should then be created in the directory `/Library/LaunchDaemon/com.gitea.runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.gitea.runner</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/runner</string>
<string>daemon</string>
<string>--config</string>
<string>/etc/runner/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>WorkingDirectory</key>
<string>/var/lib/runner</string>
<key>StandardOutPath</key>
<string>/var/lib/runner/runner.log</string>
<key>StandardErrorPath</key>
<string>/var/lib/runner/runner.err</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME</key>
<string>/var/lib/runner</string>
</dict>
<key>UserName</key>
<string>_runner</string>
</dict>
</plist>
```
Then:
```bash
sudo launchctl load /Library/LaunchDaemon/com.gitea.runner.plist
```
You can also set up a Linux or Windows service to let the runner run automatically.
## Install with the docker image
### Pull the image
You can use the docker image from [Docker Hub](https://hub.docker.com/r/gitea/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 docker.io/gitea/runner:latest # for the latest stable release
```
If you want to use the newest or experimental features, you can also use the nightly image.
```bash
docker pull docker.io/gitea/runner:nightly # for the latest nightly build
```
### Configuration
Configuration is optional, but you can also generate a config file with docker:
```bash
docker run --entrypoint="" --rm -it docker.io/gitea/runner:latest runner generate-config > config.yaml
```
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 incomplete because it is not time to run the runner yet.
Before running the runner, we need to register it to your Gitea instance first.
### Start the runner with docker
If you are using the docker image, behavior 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 runner.
A quick start with docker run along with a minimal parameter set is shown below. You need to get the `<registration_token>` from the above step, and set a unique name for `<gitea_runner_name>` and for `<container_name>`.
```bash
docker run \
-e GITEA_INSTANCE_URL=<instance_url> \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-e GITEA_RUNNER_NAME=<gitea_runner_name> \
--name <container_name> \
-v /var/run/docker.sock:/var/run/docker.sock \
-d docker.io/gitea/runner:latest
```
You can add more parameters to use a custom config, add a `data` directory for non-volatile file storage, etc.
```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=<instance_url> \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-e GITEA_RUNNER_NAME=<gitea_runner_name> \
-e GITEA_RUNNER_LABELS=<runner_labels> \
--name <container_name> \
-d docker.io/gitea/runner:latest
```
You may notice that we have mounted `/var/run/docker.sock` into the container.
This is because with this setup, the runner will execute jobs in temporary Docker containers, so it needs to communicate with the Docker daemon.
As mentioned, you can remove it if you want to run jobs on the host directly.
To be clear, the "host" actually means the container that is running the runner now, instead of the host machine.
---
To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
```bash
docker run \
-e GITEA_INSTANCE_URL=<instance_url> \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-e GITEA_RUNNER_EPHEMERAL=1 \
-e GITEA_RUNNER_NAME=<runner_name> \
--name my_runner \
-d docker.io/gitea/runner:nightly
```
```bash
docker run \
-v $PWD/config.yaml:/config.yaml \
-v /var/run/docker.sock:/var/run/docker.sock \
-e CONFIG_FILE=/config.yaml \
-e GITEA_INSTANCE_URL=<instance_url> \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-e GITEA_RUNNER_EPHEMERAL=1 \
-e GITEA_RUNNER_NAME=<runner_name> \
-e GITEA_RUNNER_LABELS=<runner_labels> \
--name my_runner \
-d docker.io/gitea/runner:nightly
```
Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
### Start the runner using docker compose
You could also set up the runner using the following `docker-compose.yml`:
```yml
version: "3.8"
services:
runner:
image: docker.io/gitea/runner:nightly
environment:
CONFIG_FILE: /config.yaml
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
GITEA_RUNNER_NAME: "${RUNNER_NAME}"
GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
volumes:
- ./config.yaml:/config.yaml
- ./data:/data
- /var/run/docker.sock:/var/run/docker.sock
```
When using docker, there is no requirement to enter the container and manually run `./runner daemon` command as shown below. Once the container has been started successfully, it will show up as an active runner in your Gitea instance.
---
To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
```yml
version: "3.8"
services:
runner:
image: docker.io/gitea/runner:nightly
environment:
CONFIG_FILE: /config.yaml
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
GITEA_RUNNER_NAME: "${RUNNER_NAME}"
GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
GITEA_RUNNER_EPHEMERAL: "1"
volumes:
- ./config.yaml:/config.yaml
- /var/run/docker.sock:/var/run/docker.sock
```
Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
### More start examples
A couple more usage examples can be found in the [runner](https://gitea.com/gitea/runner/src/branch/main/examples) repository.
## Advanced Configurations
### Configuring cache when starting a runner using the docker image
If you do not intend to use `actions/cache` in your workflow, you can ignore this section.
If you use `actions/cache` without any additional configuration, it will return the following error:
> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
The error occurs because the runner container and job container are on different networks, so the job container cannot access the runner container.
Therefore, it is essential to configure the cache action to ensure its proper functioning. Follow these steps:
- 1. Obtain the LAN IP address of the host machine where the runner container is running.
- 2. Find an available port number on the host machine where the runner container is running.
- 3. Configure the following settings in the configuration file:
```yaml
cache:
enabled: true
dir: ""
# Use the LAN IP obtained in step 1
host: "192.168.8.17"
# Use the port number obtained in step 2
port: 8088
```
- 4. When starting the container, map the cache port to the host machine:
```bash
docker run \
--name gitea-docker-runner \
-p 8088:8088 \
-d docker.io/gitea/runner:nightly
```
### 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://<the image you like>`.
You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md).
If you want to run jobs on the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`; `:host` is optional.
However, we suggest you use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
Starting with Gitea 1.21, you can change labels by modifying `runners.labels` in the runner configuration file (if you don't have a configuration file, please refer to [configuration tutorials](#configuration)).
The runner will use these new labels as soon as you restart it, i.e., by calling `./runner daemon --config config.yaml`.

119
versioned_docs/version-1.27/usage/actions/scoped-workflows.md Normal file
View File

@@ -0,0 +1,119 @@
---
date: "2026-06-26T00:00:00+00:00"
slug: "scoped-workflows"
sidebar_position: 60
---
# Scoped Workflows
Scoped workflows let you maintain Actions workflows in one central **source** repository and have them run automatically on many other repositories, without copying the workflow files into each one.
A workflow file committed under a source repository's scoped-workflow directory runs on every repository that the source applies to (a "consuming" repository). Each run executes **in the consuming repository's own context**: its runners, secrets, `GITEA_TOKEN`, and branch, while the workflow **content is read from the source repository**. This is useful for mandating shared CI across an organization or instance: linting, security scans, compliance or policy checks, and similar.
## Levels
A source repository can be registered at two levels:
- **Owner level**: registered by an organization or user. The source's workflows run on every repository owned by that organization or user.
- **Instance level**: registered by a site administrator. The source's workflows run on **every** repository on the instance.
The same repository may be registered at both levels; it is still evaluated once per matching event.
:::note
Instance-level sources apply to **every** repository on the instance, and a required one cannot be opted out. Detection runs on every repository's events. Register them deliberately.
:::
## Configuration
Scoped workflows live in a directory that is separate from regular workflows. It is controlled by `SCOPED_WORKFLOW_DIRS` in the `[actions]` section of `app.ini`:
```ini
[actions]
SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
```
- The default is `.gitea/scoped_workflows`.
- It may list multiple directories (comma-separated).
- It **must not overlap** with `WORKFLOW_DIRS` (the regular workflow directories, by default `.gitea/workflows` and `.github/workflows`).
- Leaving it empty means no directory holds scoped workflows, so none are found or run. The settings page still appears and sources can still be registered, but no scoped workflow runs.
Keeping scoped workflows in their own directory means a source repository's *own* Actions are unaffected: only files under `SCOPED_WORKFLOW_DIRS` are treated as scoped workflows.
## Providing scoped workflows from a repository
1. In the would-be source repository, commit your workflow files under the scoped-workflow directory on its **default branch**, for example `.gitea/scoped_workflows/lint.yaml`:
```yaml
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "lint the consuming repository here"
```
2. Register the repository as a source:
- **Organization**: *Organization Settings -> Actions -> Scoped Workflows*
- **User**: *User Settings -> Actions -> Scoped Workflows*
- **Instance (admin)**: *Site Administration -> Actions -> Scoped Workflows*
Search for and add the repository. From then on, its scoped workflows apply to the consuming repositories at that level.
The source repository is within its own scope, so it runs these workflows on itself like any other consumer.
## How scoped workflows run
- The run belongs to the **consuming** repository and uses its runners, secrets, `GITEA_TOKEN`, and ref. It behaves like a normal run there, including rerun, logs, and commit statuses.
- The workflow **content is read from the source** repository, pinned to the source's default-branch commit at the time of the event.
- Detection uses the consuming repository's event, so the workflow's `on:` triggers (such as `push` and `pull_request`) must match that event.
## Opting out
A consuming repository can disable a scoped workflow it does not want, from its **Actions** page (the workflow appears under its source). A workflow that has been marked **required** (see below) can never be disabled or opted out by a consuming repository.
## Required workflows and the merge gate
On the Scoped Workflows settings page you can mark individual workflows as **required** and give each one or more **status-check patterns** (one glob per line). A required scoped workflow:
- Cannot be disabled by consuming repositories.
- Gates pull-request merges: a consuming pull request can only be merged once a commit status matching **every** pattern has **passed** (must-present-and-pass). A required check that never posts a status **blocks** the merge rather than being silently skipped, so disabling Actions on the consumer cannot bypass it.
The status-check context a scoped run posts has the form:
```
<source repo full name>: <workflow display name> / <job> (<event>)
```
The settings page previews these "Expected status checks" for each workflow and marks the ones your patterns match, so you can confirm a pattern is correct. A common pattern wildcards the job and event, for example `my-org/ci-repo: Lint / *`.
Enforcement scope:
- A required check is enforced on any target branch that has a **branch protection rule**, even one whose own status checks are disabled.
- A target branch with **no** protection rule is not gated.
:::warning
Only a workflow that runs on an event that posts a commit status (`push`, `pull_request`, `pull_request_target`, `release`) can be required. A workflow that runs only on events like `workflow_dispatch`, `schedule` or `workflow_call` posts no status, so marking it required would block every consuming pull request forever. The settings page warns you in this case.
:::
## Reusable workflows (`uses:`)
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 reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
## Security considerations
A source repository's workflow content is executed in every repository it applies to, and its step scripts and their output are written to that repository's Actions logs, readable by anyone who can view the consuming repository's Actions.
- Registering a **private** repository as a source therefore discloses its workflow logic through those logs. Only register repositories whose workflow content may be shared with every consuming repository.
## Limitations
- `on: schedule` and `on: workflow_run` are currently not supported as scoped workflow triggers.
- Scoped workflow content is read from the source's default branch; other branches of the source are not used.

35
versioned_docs/version-1.27/usage/actions/secrets.md Normal file
View File

@@ -0,0 +1,35 @@
---
date: "2024-07-10T09:23:00+02:00"
slug: "secrets"
sidebar_position: 50
---
# Secrets
Secrets allow you to store sensitive information in your user, organization or repository.
Secrets are available on Gitea 1.19+ and are only visible in 1.20+ when ACTIONS are enabled.
# Naming your secrets
The following rules apply to secret names:
- Secret names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
- Secret names must not start with the `GITHUB_` and `GITEA_` prefix.
- Secret names must not start with a number.
- Secret names are not case-sensitive.
- Secret names must be unique at the level they are created at.
For example, a secret created at the repository level must have a unique name in that repository, and a secret created at the organization level must have a unique name at that level.
### Using secrets
After creating configuration variables, they will be automatically filled in the `secrets` context.
They can be accessed through expressions like `${{ secrets.SECRET_NAME }}` in the workflow.
### Precedence
If a secret with the same name exists at multiple levels, the secret at the lowest level takes precedence. For example, if an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence.

115
versioned_docs/version-1.27/usage/actions/token-permissions.md Normal file
View File

@@ -0,0 +1,115 @@
---
date: "2026-03-19T00:00:00+01:00"
slug: "token-permissions"
sidebar_position: 30
---
# Actions job token permissions (`GITEA_TOKEN`)
Every Actions job receives a built-in token (`GITEA_TOKEN`) which can be used to access Gitea (Git over HTTP(S), API requests, etc.).
This page documents how Gitea decides what the token is allowed to do.
In workflows, it is available as `${{ secrets.GITEA_TOKEN }}`. These settings and `permissions:` only affect `GITEA_TOKEN` (not other secrets like personal access tokens). For API calls, see [API authentication](../../development/api-usage.md#authentication).
## Where permissions come from
Gitea determines the job token permissions in this order:
1. Job-level `permissions:` (`jobs.<job_id>.permissions`)
2. Workflow-level `permissions:` (top-level)
3. Default permissions from settings (owner or repository)
The result is then **clamped** by the configured maximum token permissions (see below).
## Supported workflow syntax
Gitea supports the GitHub Actions-compatible `permissions:` keyword.
### Scalar values
```yaml
permissions: read-all # or: write-all
```
### Scoped mapping
```yaml
permissions:
contents: read
issues: write
pull-requests: none
```
Valid access mode values for each scope are `read`, `write`, and `none`.
### Supported scopes
- `contents` (applies to `code` and `releases`)
- `code`
- `releases`
- `issues`
- `pull-requests`
- `actions`
- `wiki`
- `projects`
- `packages` (if supported by the target feature)
If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit.
### Compatibility notes
Gitea supports a subset of GitHub Actions permission scopes.
GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not currently supported by Gitea Actions.
Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions:
- `code`
- `releases`
- `wiki`
- `projects`
## Default permission mode
If neither the workflow nor the job defines `permissions:`, Gitea uses the configured default mode:
- **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default).
- **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default.
## Maximum token permissions (clamping)
You can configure a maximum permission per repository unit.
The job's effective permissions are computed as:
`effective = min(requested, maximum)`
This means workflows can reduce permissions for a job, but cannot exceed your configured maximum.
If you don't configure a maximum, the maximum defaults to `write` for all scopes.
## Where to configure
You can configure defaults and maximums at:
- **User / Organization**: `Settings` → `Actions` → `General`
- **Repository**: `Settings` → `Actions` → `General`
- For repositories in an organization, the repository can follow the owner-level configuration, or opt out with **Override owner-level configuration**.
Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled.
## Fork pull requests
For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings.
## Cross-repository access
By default, `GITEA_TOKEN` only has access to:
- The job's repository (according to the computed permissions)
- Public repositories (read-only)
Access to other private repositories is denied by default.
A user or organization can allow read-only access to selected private repositories via **Settings → Actions → General → Cross-Repository Access**.
Private repositories can also allow selected collaborative owners via **Settings → Actions → General**.
This allows the private repositories of those owners to read the current private repository for Actions use, such as private actions and reusable workflows.
Fork pull request workflows never gain cross-repository access to private repositories, even if those repositories are listed.

140
versioned_docs/version-1.27/usage/actions/variables.md Normal file
View File

@@ -0,0 +1,140 @@
---
date: "2024-04-10T22:21:00+08:00"
slug: "actions-variables"
sidebar_position: 25
---
# Variables
## User-defined variables
You can create configuration variables on the user, organization and repository level.
The level of the variable depends on where you created it. When creating a variable, the
key will be converted to uppercase. You need use uppercase on the yaml file.
### Naming conventions
The following rules apply to variable names:
- Variable names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
- Variable names must not start with the `GITHUB_` and `GITEA_` prefix.
- Variable names must not start with a number.
- Variable names are case-insensitive.
- Variable names must be unique at the level they are created at.
- Variable names must not start with `CI`.
### Using variables
After creating configuration variables, they will be automatically filled in the `vars` context.
They can be accessed through expressions like `${{ vars.VARIABLE_NAME }}` in the workflow.
### Precedence
If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence:
A repository variable will always be chosen over an organization/user variable.
## Pre-defined context variables
These variables are available in workflow expressions via `${{ gitea.<name> }}`. For compatibility, `${{ github.<name> }}` works as an alias.
| Name | Description | Example |
|---|---|---|
| `gitea.action`<br/>`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
| `gitea.action_ref`<br/>`github.action_ref` | The ref of the action being executed. | `v4` |
| `gitea.action_repository`<br/>`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
| `gitea.action_status`<br/>`github.action_status` | The current result of a composite action. | `success` |
| `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
| `gitea.base_ref`<br/>`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
| `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
| `gitea.event`<br/>`github.event` | The full event webhook payload as an object. | `{...}` |
| `gitea.event_name`<br/>`github.event_name` | The name of the event that triggered the workflow run. | `push` |
| `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
| `gitea.head_ref`<br/>`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
| `gitea.job`<br/>`github.job` | The `job_id` of the current job. | `build` |
| `gitea.ref`<br/>`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
| `gitea.ref_name`<br/>`github.ref_name` | The short ref name. | `main` |
| `gitea.ref_protected`<br/>`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
| `gitea.ref_type`<br/>`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
| `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` |
| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `gitea` |
| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
| `gitea.retention_days`<br/>`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
| `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
| `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
| `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
| `gitea.secret_source`<br/>`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
| `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
| `gitea.sha`<br/>`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
| `gitea.workflow`<br/>`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
| `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
| `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
## Pre-defined environment variables
These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
### Standard environment variables
| Name | Description | Example |
|---|---|---|
| `CI` | Always set to `true`. | `true` |
| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` |
| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` |
| `GITHUB_ACTIONS` | Always set to `true`. | `true` |
| `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` |
| `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` |
| `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
| `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
| `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` |
| `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` |
| `GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
| `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
| `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
| `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
| `GITHUB_JOB` | The `job_id` of the current job. | `build` |
| `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
| `GITHUB_REF_NAME` | The short ref name. | `main` |
| `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
| `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` |
| `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` |
| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` |
| `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
| `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
| `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
| `GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.com` |
| `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
| `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` |
### Runner environment variables
| Name | Description | Example |
|---|---|---|
| `RUNNER_ARCH` | The architecture of the runner. | `X64` |
| `RUNNER_OS` | The operating system of the runner. | `Linux` |
| `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` |
| `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` |
### Internal environment variables
These are used internally by the runner and actions. They are typically not needed in workflows directly.
| Name | Description | Example |
|---|---|---|
| `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` |
| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` |
| `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` |
| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |