mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-05 17:45:46 +00:00
Add version v28 (#564)
<!-- cloudflare-preview --> Preview: https://pr-564.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/564 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>
This commit is contained in:
Lunny Xiao authored and 
bircni committed
1 parent
deb2f068d4
commit
ba60edbbda
338 files changed
+114457
-47
No files matched your search
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Actions",
|
||||
"position": 30,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/actions",
|
||||
"description": "Automating workflows with Actions"
|
||||
}
|
||||
}
|
||||
@@ -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`.
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "comparison"
|
||||
sidebar_position: 120
|
||||
---
|
||||
|
||||
# Compared to GitHub Actions
|
||||
|
||||
Gitea Actions is designed to be compatible with GitHub Actions, with the differences below.
|
||||
|
||||
## Additional features
|
||||
|
||||
### Absolute action URLs
|
||||
|
||||
`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
|
||||
|
||||
See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/).
|
||||
|
||||
### Support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly on 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`
|
||||
|
||||
[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.
|
||||
|
||||
### Complex `runs-on`
|
||||
|
||||
[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) 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
|
||||
|
||||
`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](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.
|
||||
|
||||
### Create an error annotation
|
||||
|
||||
[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
|
||||
|
||||
[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 have no section of their own in the job log.
|
||||
|
||||
### Services steps
|
||||
|
||||
Service steps have no section of their own in the job log.
|
||||
|
||||
## Different behavior
|
||||
|
||||
### Job token permissions (`permissions`)
|
||||
|
||||
`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
|
||||
|
||||
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](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability) is not checked, so contexts like `env` work in more places.
|
||||
@@ -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 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.
|
||||
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`.
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 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.
|
||||
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.
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
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`?
|
||||
|
||||
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).
|
||||
|
||||
To use an action from elsewhere, name its host:
|
||||
|
||||
- `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 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?
|
||||
|
||||
Official binaries are released for Linux, macOS and Windows.
|
||||
Other systems supported by Go and Docker work in theory.
|
||||
|
||||
## 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]`?
|
||||
|
||||
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?
|
||||
|
||||
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?
|
||||
|
||||
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 |
|
||||
| schedule | not applicable |
|
||||
| workflow_dispatch | not applicable |
|
||||
| workflow_call | not applicable |
|
||||
| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
|
||||
| issue_comment | `created`, `edited`, `deleted` |
|
||||
| pull_request<br/>pull_request_target | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`, `milestoned`, `demilestoned`, `review_requested`, `review_request_removed` |
|
||||
| pull_request_review | `submitted`, `edited` |
|
||||
| pull_request_review_comment | `created`, `edited` |
|
||||
| release | `published`, `edited` |
|
||||
| registry_package | `published` |
|
||||
| workflow_run | `requested`, `in_progress`, `completed` |
|
||||
|
||||
> Without an explicit `types:` filter, `pull_request` and `pull_request_target` only run on `opened`, `reopened` and `synchronize`, matching GitHub. All other events run on every activity type they support.
|
||||
|
||||
> 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.
|
||||
|
||||
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).
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Great job! You have successfully started working with Actions.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
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), which is the runner for Gitea Actions.
|
||||
|
||||
:::tip
|
||||
For detailed installation, configuration, and usage instructions, see the [Gitea Runner documentation](/runner/).
|
||||
:::
|
||||
|
||||
## 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.
|
||||
|
||||
Once you have a registration token, follow the [Gitea Runner documentation](/runner/) to install, configure, and run your runner.
|
||||
@@ -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: ./...` 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.
|
||||
|
||||
## 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
date: "2024-04-10T22:21:00+08:00"
|
||||
slug: "actions-variables"
|
||||
sidebar_position: 25
|
||||
---
|
||||
|
||||
# Variables
|
||||
|
||||
## Environment variables
|
||||
|
||||
These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
|
||||
|
||||
| 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_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` |
|
||||
| `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/` |
|
||||
|
||||
## 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. See [Event payload](#event-payload). | `{...}` |
|
||||
| `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` |
|
||||
|
||||
### Event payload
|
||||
|
||||
`gitea.event` is the webhook payload of the event that triggered the run, so which fields exist depends on `gitea.event_name`.
|
||||
The same payload is written as JSON to the file at `gitea.event_path`.
|
||||
|
||||
Payloads use Gitea's webhook format, which is close to GitHub's but not identical. Differences are noted below.
|
||||
Reading a field that the payload does not have returns an empty value instead of failing, so `${{ gitea.event.pull_request.number }}` is empty on a `push` run.
|
||||
|
||||
These fields exist in almost every payload:
|
||||
|
||||
| Name | Description | Example |
|
||||
|---|---|---|
|
||||
| `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
|
||||
| `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` |
|
||||
| `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
|
||||
| `gitea.event.repository.private` | Whether the repository is private. | `false` |
|
||||
| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` |
|
||||
| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` |
|
||||
|
||||
The remaining fields are specific to one or a few events:
|
||||
|
||||
| Name | Events | Description | Example |
|
||||
|---|---|---|---|
|
||||
| `gitea.event.schedule` | `schedule` | The cron expression that triggered the run. | `*/5 * * * *` |
|
||||
| `gitea.event.inputs.<name>` | `workflow_dispatch`, `workflow_call` | A raw input value. Prefer `${{ inputs.<name> }}`, which also applies the input's `default`. | `true` |
|
||||
| `gitea.event.workflow` | `workflow_dispatch` | The file name of the dispatched workflow. | `ci.yaml` |
|
||||
| `gitea.event.ref` | `push`, `create`, `delete`, `workflow_dispatch` | The ref of the event. Unlike GitHub, `create` and `delete` use the full ref instead of the short name. | `refs/heads/main` |
|
||||
| `gitea.event.ref_type` | `create`, `delete` | The type of ref: `branch` or `tag`. | `tag` |
|
||||
| `gitea.event.before`<br/>`gitea.event.after` | `push` | The commit SHA before and after the push. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
|
||||
| `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
|
||||
| `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
|
||||
| `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
|
||||
| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` |
|
||||
| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` |
|
||||
| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` |
|
||||
| `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
|
||||
| `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
|
||||
| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` |
|
||||
| `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
|
||||
| `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
|
||||
| `gitea.event.pull_request.number`<br/>`gitea.event.pull_request.title`<br/>`gitea.event.pull_request.body`<br/>`gitea.event.pull_request.draft`<br/>`gitea.event.pull_request.merged`<br/>`gitea.event.pull_request.state`<br/>`gitea.event.pull_request.labels`<br/>`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |
|
||||
| `gitea.event.pull_request.head.ref`<br/>`gitea.event.pull_request.head.sha`<br/>`gitea.event.pull_request.head.repo.full_name` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The source branch of the pull request. | `feature-branch` |
|
||||
| `gitea.event.pull_request.base.ref`<br/>`gitea.event.pull_request.base.sha` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The target branch of the pull request. | `main` |
|
||||
| `gitea.event.review.type` | `pull_request_review`, `pull_request_review_comment` | The kind of review: `pull_request_review_approved`, `pull_request_review_rejected` or `pull_request_review_comment`. GitHub uses `review.state` with the values `approved`, `changes_requested` and `commented`. | `pull_request_review_approved` |
|
||||
| `gitea.event.review.content` | `pull_request_review`, `pull_request_review_comment` | The body of the review. GitHub names this field `review.body`. | `Ship it` |
|
||||
| `gitea.event.changes.title.from`<br/>`gitea.event.changes.body.from` | `issues`, `issue_comment`, `pull_request` | The previous value. Only set when `action` is `edited`. | `Old title` |
|
||||
| `gitea.event.release.tag_name`<br/>`gitea.event.release.name`<br/>`gitea.event.release.body`<br/>`gitea.event.release.draft`<br/>`gitea.event.release.prerelease` | `release` | The release the event happened on. | `v1.2.3` |
|
||||
| `gitea.event.package.name`<br/>`gitea.event.package.type`<br/>`gitea.event.package.version` | `registry_package` | The package the event happened on. | `gitea` |
|
||||
| `gitea.event.workflow_run.id`<br/>`gitea.event.workflow_run.event`<br/>`gitea.event.workflow_run.status`<br/>`gitea.event.workflow_run.conclusion`<br/>`gitea.event.workflow_run.head_branch`<br/>`gitea.event.workflow_run.head_sha` | `workflow_run` | The workflow run that the event reports on. | `success` |
|
||||
|
||||
`schedule` runs have no webhook of their own. Their payload is the payload of the push that registered the schedule, with `schedule`, `repository`, `sender` and, for organization-owned repositories, `organization` filled in.
|
||||
Only those fields are meaningful, and `sender.login` is always `gitea-actions`.
|
||||
|
||||
## 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.
|
||||
Reference in new issue
Block a user