Author SHA1 Message Date
Lunny Xiao ad383f9f84 Merge branch 'main' into lunny/add_project_workflow 2026-10-22 23:47:45 +00:00
Lunny Xiao f9fa3e3258 docs(projects): move translations to the new i18n docs layout 2026-10-22 16:29:22 -07:00
Lunny Xiao 602612a046 docs(projects): document project workflow API 2026-10-22 16:24:28 -07:00
Lunny Xiao c902fe9253 Merge branch 'main' into lunny/add_project_workflow 2026-10-22 23:22:15 +00:00
silverwind 3b71a35b51 docs(projects): document workflow permissions and sync with the implementation
The "Issues/PRs opened" event was folded into "Added to project", pull
requests can only be closed by workflows, closed projects don't run
workflows, and actions run in a fixed order. The new Permissions
section defines who can manage workflows and that they then act
without further permission checks. Also fix the editor steps, a typo
and the zh-tw page's nonexistent "New Workflow" button.

Assisted-by: Claude Code:claude-opus-5-5
2026-10-22 13:19:59 +02:00
silverwind 7e9e42775c Merge branch 'main' into lunny/add_project_workflow 2026-02-19 07:56:40 +00:00
Lunny Xiao 85ac8fc4ba Add project workflow documentation 2025-11-25 11:33:30 -08:00
73 changed files with 5946 additions and 5964 deletions

No files matched your search

+3 -3
View File
@@ -8,7 +8,7 @@ on:
jobs:
build-docs:
runs-on: ubuntu-26.04
runs-on: ubuntu-24.04
env:
NODE_OPTIONS: --max-old-space-size=8192
# search only appears once the credentials are set, the build falls back
@@ -18,10 +18,10 @@ jobs:
PUBLIC_DOCSEARCH_INDEX_NAME: ${{ secrets.DOCSEARCH_INDEX_NAME }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6
- uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: 26
node-version: 24
cache: pnpm
- name: prepare awesome list
run: |
+2 -2
View File
@@ -15,10 +15,10 @@ jobs:
NODE_OPTIONS: --max-old-space-size=8192
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6
- uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: 26
node-version: 24
cache: pnpm
- name: prepare awesome list
run: |
+1 -1
View File
@@ -92,7 +92,7 @@ update-runner-docs:
update-runner-docs-released:
./update_runner_docs.sh --released
# freezes the current docs, runner or cli tree as a new version, see
# freezes the current docs or runner tree as a new version, see
# scripts/cut-version.mjs
.PHONY: cut-version
cut-version:
+1 -13
View File
@@ -3,14 +3,13 @@
The sources of [docs.gitea.com](https://docs.gitea.com), built with
[Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
The site covers four products, all served from this repository:
The site covers three products, all served from this repository:
| Product | Content | Versions | Languages |
| --- | --- | --- | --- |
| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 5 … 0 | English |
| CLI | `cli-docs/`, `cli-docs_versioned_docs/` | develop | English |
The enterprise documentation is built and deployed from its own repository and
reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
@@ -54,7 +53,6 @@ group from the `_category_.json` of its directory.
```shell
make cut-version PRODUCT=docs VERSION=1.28
make cut-version PRODUCT=runner VERSION=6
make cut-version PRODUCT=cli VERSION=0.1
```
This freezes the current tree, its translations and its sidebar. The label of
@@ -117,16 +115,6 @@ workflow runs weekly and opens a pull request whenever the runner's CLI or
example configuration changed. Generating them needs Go, since the script builds
the runner binary.
## CLI docs
The documentation of `gt`, the Gitea CLI from
[gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs, with
its sidebar in `cli-sidebars.js`. No series is documented yet, so `cli-docs/` is
served at `/cli/`. Once a release exists, cut its series and list it in
`cliSeries` in `packages/content-loader/src/products.ts`, which moves the develop
docs to `/cli/develop/`. The guides leave the flags of each command to
`gt <command> --help`.
## Deployment
`main` is built and published by the `Build and Publish Docs site` workflow, to
-55
View File
@@ -1,55 +0,0 @@
---
sidebar_position: 3
---
# Logging in
On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
your password.
## OAuth in a browser
```bash
gt auth login --host https://gitea.example.com --oauth
```
gt opens the instance's authorization page, so single sign-on and two-factor
authentication work as on the web. The browser has to run on the same machine as gt.
`--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
refreshes OAuth tokens on its own.
## Access token
Create a token under **Settings > Applications** on the instance and pass it on stdin:
```bash
gt auth login --host https://gitea.example.com --with-token < token.txt
```
The token needs `read:user`, and the scopes of what you do with gt, such as
`write:repository` and `write:issue` for working on pull requests.
## SSH key
gt can sign its requests with an SSH key registered for your account instead of using a
token:
```bash
gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
```
## Accounts
Tokens go to the system keyring, or with `--credential-store file` to gt's configuration
directory on machines without one. Run `gt auth login` once per instance and account.
gt picks the instance from the repository's remote or `--host`, and the account with
`gt auth switch` or `--user`. `gt auth status` lists your accounts and `gt auth logout`
removes one.
For instances behind an access proxy, `--header` and `--client-cert` add headers and a
client certificate.
## Git over HTTPS
`gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
clone and checkout commands need no setup.
-40
View File
@@ -1,40 +0,0 @@
---
sidebar_position: 4
---
# Using gt in CI
Give gt a token and an instance through the environment, and turn prompts off:
| Variable | Description |
| --- | --- |
| `GITEA_TOKEN` | Access token; gt never stores it |
| `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance |
| `GITEA_CLI_REPO` | Repository, like `--repo` |
`--no-input` makes a command fail instead of prompting, and `--yes` confirms changes in
advance.
## Gitea Actions
Gitea does not allow secret names that start with `GITEA_`, so store the token as, for
example, `GT_TOKEN`:
```yaml
on:
push:
branches: [main]
jobs:
staging:
runs-on: ubuntu-latest
env:
GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
GITEA_CLI_HOST: ${{ gitea.server_url }}
GITEA_CLI_REPO: ${{ gitea.repository }}
steps:
- run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
- run: gt workflow run deploy.yml --ref main --field env=staging --no-input
```
`gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when one fails.
-38
View File
@@ -1,38 +0,0 @@
---
sidebar_position: 1
slug: /
---
# Gitea CLI
[gt](https://gitea.com/gitea/cli) is the official command line client for Gitea. It works
with repositories, issues, pull requests, releases, Actions and the other resources of a
Gitea instance, from a terminal or a script.
:::info Development version
These pages describe builds from the `main` branch, published as `nightly` binaries and images.
:::
gt needs Gitea 28 or later, and Git for the commands that clone, check out or push.
## Getting started
1. [Install gt](installation.md).
2. [Log in](authentication.md):
```bash
gt auth login
```
3. Run commands in a clone of a repository on that instance, or select one with `--repo`:
```bash
gt issue list --label bug
gt pr checkout 13
gt issue view 42 --repo gitea.com/gitea/cli
```
`gt doctor` checks your setup and suggests a fix for each problem it finds.
`gt <command> --help` lists the flags of a command, and `gt help environment` the global
flags and environment variables.
-37
View File
@@ -1,37 +0,0 @@
---
sidebar_position: 2
---
# Installation
gt is a single binary for Linux, macOS, Windows and FreeBSD.
## Install script
The install script downloads gt from [dl.gitea.com](https://dl.gitea.com/gitea-cli/),
verifies its checksum and installs it.
```bash
# Linux, macOS, FreeBSD
curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
```
```powershell
# Windows
irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
```
Set `GITEA_CLI_VERSION` to install a specific version, or `nightly` for the latest build
of `main`.
## Other ways
- **Binaries:** download them from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/).
- **Docker:** the [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs
`gt` as its entry point.
- **Go:** `go install gitea.dev/cli/cmd/gt@latest`
## Shell completion and man pages
`gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell;
`gt completion <shell> --help` shows how to load it. `gt man` prints the manual.
-22
View File
@@ -1,22 +0,0 @@
---
sidebar_position: 5
---
# Output and scripting
Scripts should read JSON: the text output is meant for people and may change.
```bash
gt pr view 123 --json number,title,state
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
```
`--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
`--help` names them. `--jq` filters the result without needing jq installed. Piped lists
print as tab-separated values.
gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
authentication is missing or rejected; `gt help exit-codes` lists all codes.
`gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
commands you use often.
-1
View File
@@ -1 +0,0 @@
[]
-16
View File
@@ -1,16 +0,0 @@
// Sidebar of the gt (Gitea CLI) documentation (develop version).
// Released versions carry their own copy in
// cli-docs_versioned_sidebars/version-<version>-sidebars.json.
module.exports = {
cli: [
{
type: 'doc',
id: 'index',
label: 'What is gt?',
},
'installation',
'authentication',
'ci',
'scripting',
],
};
+2 -4
View File
@@ -1,13 +1,11 @@
# Redirects for legacy URLs and routes the site no longer serves directly.
# The api reference, the runner and the cli docs are separate products,
# published in english only, so they have no localized copy.
# The api reference and the runner docs are separate products, published in
# english only, so they have no localized copy.
/zh-cn/api/* /api/:splat 301
/zh-tw/api/* /api/:splat 301
/zh-cn/runner/* /runner/:splat 301
/zh-tw/runner/* /runner/:splat 301
/zh-cn/cli/* /cli/:splat 301
/zh-tw/cli/* /cli/:splat 301
# The version served at the root of a product is also reachable under its
# number, which is what the release notes and old links use.
+1 -3
View File
@@ -7,7 +7,6 @@
"https://docs.gitea.com/zh-cn/",
"https://docs.gitea.com/zh-tw/",
"https://docs.gitea.com/runner/",
"https://docs.gitea.com/cli/",
"https://docs.gitea.com/api/",
"https://docs.gitea.com/enterprise/"
],
@@ -16,8 +15,7 @@
"https://docs.gitea.com/1.2*/**",
"https://docs.gitea.com/*/1.2*/**",
"https://docs.gitea.com/api/1.2*/**",
"https://docs.gitea.com/runner/[0-9]/**",
"https://docs.gitea.com/cli/[0-9]*/**"
"https://docs.gitea.com/runner/[0-9]/**"
],
"selectors": {
"lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" },
+4 -7
View File
@@ -179,7 +179,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
- `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request.
- `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author.
- `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo.
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
- `DEFAULT_TITLE_SOURCE`: **auto**: Default source for the pull request title when opening a new PR. Valid options:
- `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message.
- `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing.
@@ -595,8 +595,7 @@ And the following unique queues:
authentication provided email.
- `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy
authentication provided full name.
- `REVERSE_PROXY_LIMIT`: **1**: Interpret the X-Real-IP, X-Forwarded-For or Forwarded header, in that order, and set this as the remote IP for the request.
The client port is taken from the header value or, with X-Real-IP, from X-Real-Port.
- `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request.
Number of trusted proxy count. Set to zero to not use these headers.
- `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
- `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`.
@@ -1356,7 +1355,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
- `JWT_SECRET_URI`: **_empty_**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/oauth2_jwt_secret`)
- `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you.
- `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider
- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options. `tea` is accepted as an alias of `gitea-cli`.
- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea, gitea-app**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options.
- `CUSTOM_SCHEMES`: **_empty_**: By default, OAuth2 applications can only use "http" and "https" as their redirect URI schemes.
If you need to use other schemes (e.g. for desktop applications), you can specify them here as a comma-separated list.
For example: set "my-scheme, com.example.app" to support "my-scheme://..." and "com.example.app://..." redirect URIs.
@@ -1468,7 +1467,6 @@ These lists are enforced on direct connections only. When a proxy is configured
- `CHUNKED_UPLOAD_PATH`: **tmp/package-upload**: Path for chunked uploads. Defaults to `APP_DATA_PATH` + `tmp/package-upload`
- `LIMIT_TOTAL_OWNER_COUNT`: **-1**: Maximum count of package versions a single owner can have (`-1` means no limits)
- `LIMIT_TOTAL_OWNER_SIZE`: **-1**: Maximum size of packages a single owner can use (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `MAX_DECOMPRESSION_RATIO`: **200**: Maximum inflation ratio while reading an upload's metadata from an archive
- `LIMIT_SIZE_ALPINE`: **-1**: Maximum size of an Alpine upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_CARGO`: **-1**: Maximum size of a Cargo upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_CHEF`: **-1**: Maximum size of a Chef upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
@@ -1489,9 +1487,8 @@ These lists are enforced on direct connections only. When a proxy is configured
- `LIMIT_SIZE_RPM`: **-1**: Maximum size of a RPM upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_TERRAFORM_MODULE`: **-1**: Maximum size of a Terraform module archive upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`). Archives are additionally capped at 32 MiB decompressed.
- `LIMIT_SIZE_TERRAFORM_STATE`: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_TERRAFORM_STATE``: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
## Mirror (`mirror`)
-1
View File
@@ -16,7 +16,6 @@ aliases:
4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work.
6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling.
7. Make sure the reverse-proxy sets the `X-Real-IP` header, otherwise Gitea uses a client-sent value. For example `header_up X-Real-IP {remote_host}` in Caddy's `reverse_proxy`, `RequestHeader set X-Real-IP "expr=%{REMOTE_ADDR}"` in Apache or `http-request set-header X-Real-IP %[src]` in HAProxy. To log the client port, also set `X-Real-Port`, for example `proxy_set_header X-Real-Port $remote_port;` in nginx.
### Use a sub-path
-1
View File
@@ -73,7 +73,6 @@ By default, this creates a token with very limited permissions. To complete your
- `activitypub`
- `admin`
- `commitstatus` (included in `repository`)
- `issue`
- `misc`
- `notification`
+1 -6
View File
@@ -111,9 +111,6 @@ Gitea token scopes are as follows:
| **admin** | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts). |
| &nbsp;&nbsp;&nbsp; **read:admin** | Grants read access for admin operations, such as getting cron jobs or registered user emails. |
| &nbsp;&nbsp;&nbsp; **write:admin** | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts. |
| **commitstatus** | `/repos/{owner}/{repo}/statuses/{sha}` and `/repos/{owner}/{repo}/commits/{ref}/status(es)` API routes: Commit status operations. |
| &nbsp;&nbsp;&nbsp; **read:commitstatus** | Grants read access to commit statuses. Included in `read:repository`. |
| &nbsp;&nbsp;&nbsp; **write:commitstatus** | Grants read/write access to commit statuses, such as reporting CI results. Included in `write:repository`. |
| **issue** | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations. |
| &nbsp;&nbsp;&nbsp; **read:issue** | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones. |
| &nbsp;&nbsp;&nbsp; **write:issue** | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones. |
@@ -144,9 +141,7 @@ Gitea creates OAuth applications for the following services by default on startu
|-----------|-----------|---------|
|[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`|
|[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`|
|[Gitea CLI](https://gitea.com/gitea/cli)|Gitea CLI|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
|Gitea App|Official Gitea mobile app|`b757811a-05c8-4c76-8d74-a5ee3d2073f2`|
|[gitea-vscode](https://gitea.com/gitea/gitea-vscode)|VS Code extension|`75a9ec3e-42b5-40cb-9144-9ea96ecd56a6`|
|[tea](https://gitea.com/gitea/tea)|tea|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
To prevent unexpected behavior, they are being displayed as locked in the UI and their creation can instead be controlled by the `DEFAULT_APPLICATIONS` parameter in `app.ini`.
+1 -23
View File
@@ -8,7 +8,7 @@ aliases:
# Database Preparation
You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. PostgreSQL, MySQL and MSSQL are covered here. If you plan to use SQLite, you can ignore this chapter.
You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter.
:::warning
Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type.
@@ -177,28 +177,6 @@ All steps below requires that the database engine of your choice is installed on
You should be prompted to enter password for the database user, and connected to the database.
## MSSQL
1. As an administrator, create the login, a database with case-sensitive collation, and its user. Replace the password `'gitea'` with a secure one:
```sql
CREATE LOGIN gitea WITH PASSWORD = 'gitea';
CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
GO
USE giteadb;
CREATE USER gitea FOR LOGIN gitea;
ALTER ROLE db_owner ADD MEMBER gitea;
GO
```
Upgrades change the database schema, so the user needs `db_owner`, or `db_ddladmin`, `db_datareader` and `db_datawriter`. With the latter, also run `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;` as administrator.
2. On your Gitea server, test the connection to the database:
```sh
sqlcmd -S 203.0.113.3 -U gitea -d giteadb
```
## Database Connection over TLS
If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data.
+12 -2
View File
@@ -16,7 +16,17 @@ Gitea Actions is designed to be compatible with GitHub Actions, with the differe
### Action prefixes
`uses:` accepts the `self:` prefix to reference your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`.
`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
@@ -82,7 +92,7 @@ See [Actions job token permissions](token-permissions.md).
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) and [Action prefixes](#action-prefixes).
For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).
### Context availability
+58 -72
View File
@@ -9,67 +9,53 @@ sidebar_position: 25
## Environment variables
These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
A `GITEA_*` name listed with a `GITHUB_*` name holds the same value.
| Name | Description | Example |
|---|---|---|
| `ACT` | Always set to `true`, unless the runner is configured with `runner.set_act_env: false`. | `true` |
| `CI` | Always set to `true`. | `true` |
| `GITEA_ACTION`<br/>`GITHUB_ACTION` | The `id` of the current step, or its index when it has none. | `0` |
| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | The path where the action is located. Only set in composite actions. | `/var/run/act/actions/***` |
| `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 of the action. | `actions/checkout` |
| `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | Always set to `true`. `GITEA_ACTIONS` is useful to distinguish Gitea Actions from other CI systems. | `true` |
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `v5.2.4` |
| `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | The username of the user that triggered the workflow. | `alice` |
| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | The ID of the user that triggered the workflow. | `1` |
| `GITEA_API_URL`<br/>`GITHUB_API_URL` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
| `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. | `/var/run/act/workflow/envs.txt` |
| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/var/run/act/workflow/event.json` |
| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
| `GITEA_JOB`<br/>`GITHUB_JOB` | The `job_id` of the current job. | `build` |
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/var/run/act/workflow/outputcmd.txt` |
| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/var/run/act/workflow/pathcmd.txt` |
| `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. | `true` |
| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | The owner and repository name. | `owner/repo` |
| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | The ID of the repository. | `123` |
| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `owner` |
| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | The ID of the repository owner. | `45` |
| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` |
| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
| `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
| `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.example.com` |
| `GITEA_SHA`<br/>`GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/var/run/act/workflow/statecmd.txt` |
| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/var/run/act/workflow/step-summary-0.md` |
| `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | The username of the user that initiated the workflow run. May differ from `GITEA_ACTOR` on re-runs. | `alice` |
| `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
| `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | The commit SHA of the workflow file. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/owner/repo` |
| `TRACEPARENT` | The W3C trace context of the job's span, so instrumented tools can add spans to the job's trace. Only set when the runner exports traces, see [Monitoring](/runner/monitoring/#opentelemetry). | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
| `TRACESTATE` | Vendor-specific trace data that accompanies `TRACEPARENT`. Only set when the trace carries any. | `rojo=00f067aa0ba902b7` |
| `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 artifacts are kept, empty when kept forever. | `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 |
|---|---|---|
| `ImageOS` | The OS and release of the job's image, read by `setup-*` actions. | `ubuntu24` |
| `RUNNER_ARCH` | The architecture of the runner. | `X64` |
| `RUNNER_DEBUG` | Set to `1` when the `ACTIONS_STEP_DEBUG` secret is `true`, unset otherwise. | `1` |
| `RUNNER_ENVIRONMENT` | Always set to `self-hosted`. | `self-hosted` |
| `RUNNER_NAME` | The name of the runner executing the job. | `my-runner` |
| `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` |
| `RUNNER_WORKSPACE` | The parent directory of `GITEA_WORKSPACE`. | `/workspace/owner` |
### Internal environment variables
@@ -79,10 +65,10 @@ These are used internally by the runner and actions. They are typically not need
|---|---|---|
| `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 `id-token: write` is granted. | `***` |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.example.com/api/actions/oidc/token?` |
| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.example.com` |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.com/api/actions/oidc/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.example.com/api/actions_pipeline/` |
| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |
## Context variables
@@ -90,39 +76,39 @@ These variables are available in workflow expressions via `${{ gitea.<name> }}`.
| Name | Description | Example |
|---|---|---|
| `gitea.action`<br/>`github.action` | The `id` of the current step, or its index when it has none. | `0` |
| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/var/run/act/actions/***` |
| `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. | `alice` |
| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
| `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. | `/var/run/act/workflow/envs.txt` |
| `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. | `/var/run/act/workflow/event.json` |
| `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. | `/var/run/act/workflow/pathcmd.txt` |
| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `owner/repo` |
| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `owner` |
| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.example.com/owner/repo` |
| `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 artifacts are kept, empty when kept forever. | `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.example.com` |
| `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). | `***` |
| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `alice` |
| `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/owner/repo` |
| `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
@@ -138,11 +124,11 @@ 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. | `owner/repo` |
| `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.example.com/owner/repo` |
| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `alice` |
| `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:
@@ -157,12 +143,12 @@ The remaining fields are specific to one or a few events:
| `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.example.com/owner/repo/compare/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2...f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5` |
| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `alice` |
| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `alice/repo` |
| `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. | `Fix typo in README` |
| `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` |
-1
View File
@@ -36,7 +36,6 @@ The following package managers are currently supported:
| [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` |
| [Swift](usage/packages/swift.md) | Swift | `swift` |
| [Terraform](usage/packages/terraform.md) | - | `terraform` |
| [Terraform Module](usage/packages/terraform-module.md) | - | `terraform`, `terragrunt` |
| [Vagrant](usage/packages/vagrant.md) | - | `vagrant` |
**The following paragraphs only apply if Packages are not globally disabled!**
-170
View File
@@ -1,170 +0,0 @@
---
date: "2026-06-09T00:00:00+00:00"
slug: "terraform-module"
sidebar_position: 119
---
# Terraform Module Registry
Publish [Terraform](https://www.terraform.io/) modules for your user or organization and use them
from Terraform or Terragrunt. The registry implements the
[HashiCorp module registry protocol](https://developer.hashicorp.com/terraform/internals/module-registry-protocol),
so modules are referenced with the usual `HOST/NAMESPACE/NAME/PROVIDER` address.
## Requirements
- The [Terraform CLI](https://developer.hashicorp.com/terraform/install) or
[Terragrunt](https://terragrunt.gruntwork.io/).
- **Your Gitea instance must be served over HTTPS with a valid certificate.**
Terraform and Terragrunt only perform module registry discovery over HTTPS and reject
plain HTTP — including `http://localhost`. This is a requirement of the protocol, not of Gitea.
A module is addressed by three segments:
| Segment | Meaning |
| ----------- | ------------------------------------------------------------- |
| `namespace` | The owner of the module: a Gitea user or organization name. It must follow the same rules as `name`, so owners with a `.` in their name cannot publish modules. |
| `name` | The module name. Letters, digits, `-` and `_`, starting and ending with a letter or digit, up to 64 characters. |
| `provider` | The main provider the module targets, e.g. `aws`. Lowercase letters and digits, up to 64 characters. |
Versions follow [semantic versioning](https://semver.org/) and are stored in canonical form: a
leading `v` is dropped and missing segments are padded, so `v1.2.3` and `1.2.3` address the same
version, and `1.2` becomes `1.2.0`.
## Packaging a module
A module is published as a single `.tar.gz` archive, stored and served exactly as uploaded. The
module's `.tf` files must therefore be at the **archive root**. A source tarball downloaded from a Git
host wraps everything in a `repository-version/` directory and is rejected — repackage the module
directory's contents instead:
```shell
tar -czf vpc-1.0.0.tar.gz -C path/to/module .
```
The root module's inputs, outputs, providers and `README` are shown on the package page. Each
submodule found under `modules/<name>` is listed with its source address and links to its own page,
which shows the install snippet for that submodule along with its inputs, outputs, providers and
`README`. Only one level is indexed, so `modules/<name>/<nested>` is not listed. Anything else,
including `examples/`, is kept in the archive but is not indexed. A module that is only a collection of
submodules, with no root module, is also accepted. Files in JSON syntax (`.tf.json`) are accepted too,
but only `.tf` files are indexed.
## Authentication
Create a [personal access token](development/api-usage.md#authentication) with the `read:package` scope to download
private modules, and `write:package` to publish or delete them. Add it to your Terraform CLI
configuration file (`~/.terraformrc` or `%APPDATA%/terraform.rc`):
```hcl
credentials "gitea.example.com" {
token = "<your token>"
}
```
Modules owned by a public user or organization can be downloaded without a token.
## Publishing a module
Upload an archive with a `PUT` request, sending the file as the raw request body. Use
`curl --upload-file` rather than `--data-binary`: the latter sends a form content type that
the registry will not accept as an archive.
```shell
curl --user "your_username:your_token" \
--upload-file vpc-1.0.0.tar.gz \
https://gitea.example.com/api/packages/-/terraform/modules/{namespace}/{name}/{provider}/{version}
```
| Parameter | Description |
| ----------- | -------------------------------------- |
| `namespace` | The owner (user or organization). |
| `name` | The module name. |
| `provider` | The provider the module targets. |
| `version` | The module version (semver). |
For example, to publish version `1.0.0` of the `vpc` module for the `aws` provider under the `acme`
organization:
```shell
curl --user "your_username:your_token" \
--upload-file vpc-1.0.0.tar.gz \
https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
```
A successful upload returns `201 Created`. Published versions are immutable: uploading a version that
already exists returns `409 Conflict`. To replace a version, delete it first.
## Linking a module to a repository
A module always lives in a user or organization's package space — its namespace is that user or
organization, never a repository, because the registry address (`HOST/NAMESPACE/NAME/PROVIDER`) has no
repository segment. You cannot publish "into" a repository. Instead, a repository link is a display
association that surfaces the module on a repository's **Packages** tab. The workflow is:
1. **Publish** the module to the user or organization namespace, exactly as shown in
[Publishing a module](#publishing-a-module).
2. **Link** the package to a repository owned by that same user or organization: open the package,
go to its **Settings**, and select the repository (or use the
`POST /api/v1/packages/{owner}/terraform-module/{name}%2F{provider}/-/link/{repo}` API).
The link applies to the whole module — all of its versions, including ones published later — and can
be changed or removed at any time. It only affects where the module is listed in the UI; the address
used to consume it is unchanged (still `HOST/NAMESPACE/NAME/PROVIDER`, with no repository in it).
## Consuming a module
Reference the module by its registry address. With Terraform:
```hcl
module "vpc" {
source = "gitea.example.com/acme/vpc/aws"
version = "~> 1.0"
}
```
To use a submodule, append its path with the standard `//` separator:
```hcl
module "network" {
source = "gitea.example.com/acme/infra/google//modules/network"
version = "~> 1.0"
}
```
With Terragrunt, use the `tfr://` scheme and pass the version as a query parameter:
```hcl
terraform {
source = "tfr://gitea.example.com/acme/vpc/aws?version=1.0.0"
}
```
`terraform init` (or `terragrunt init`) resolves the address through the service discovery document
at `https://gitea.example.com/.well-known/terraform.json` and downloads the matching version.
## Deleting a version
```shell
curl --user "your_username:your_token" \
--request DELETE \
https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
```
A successful delete returns `204 No Content`. This requires the `write:package` scope. There is no
separate deprecation flow — deleting a version removes it from the registry.
## Limits
The stored archive is bounded by the instance-wide package limits (`LIMIT_SIZE_TERRAFORM_MODULE` and
`LIMIT_TOTAL_OWNER_SIZE`) set by your Gitea administrator; see the
[configuration cheat sheet](../../administration/config-cheat-sheet.md#packages-packages).
Independently of those settings, an archive may not exceed **32 MiB decompressed**. The registry
reads the whole archive to index it, and stops with `413 Request Entity Too Large` past that ceiling,
so raising `LIMIT_SIZE_TERRAFORM_MODULE` above 32 MiB does not allow larger modules. Real modules are
kilobyte-scale, so this only affects archives carrying unrelated payloads.
A `README` larger than **1 MiB**, of the root module or of a submodule, is not shown on the package
page. The module is still accepted and the file stays in the archive.
+1 -1
View File
@@ -4,6 +4,6 @@
"link": {
"type": "generated-index",
"slug": "/usage/projects",
"description": "Plan and track work with project boards"
"description": "Plan, track, and automate repository projects"
}
}
+77 -43
View File
@@ -2,81 +2,115 @@
date: "2025-11-25T18:58:22Z"
slug: "project-workflows"
sidebar_position: 1
description: "Automate project boards with event-driven filters and actions."
description: "Automate tasks on repository projects by reacting to events with filters and actions."
---
# Project Workflows
Project workflows automate a project board. When an issue or pull request in the project triggers an event, each enabled workflow for that event checks its filters and applies its actions. Workflows run in Gitea and need no runner.
Project workflows let you automate what happens on a repository project board whenever an issue or pull request triggers a supported event. The feature runs entirely inside Gitea, so no external runners or webhooks are required.
## Edit workflows
Users who can manage a project's workflows can create, edit, clone, enable, or disable them, see [Permissions](#permissions).
1. Open a project and select **Workflows**.
2. Select an event in the sidebar.
3. Set filters and actions, then select **Save**. To change an existing workflow, select **Edit** first.
## Open the workflow editor
An event can have several workflows. **Clone** copies the selected workflow so you can adapt it to other items. **Disable** pauses a workflow and keeps its configuration. **Remove** deletes it.
1. Navigate to the repository → **Projects** and open the board you want to automate.
2. Select **Workflows** in the menu at the top of the board.
3. Click an event in the left sidebar to edit its workflow.
4. Choose the event, add any filters, chain the actions you need, and save.
## Events
Every workflow lives inside the project it belongs to. If you need similar logic for another project, recreate or clone the workflow in that project.
| Event | Runs when | Filters | Actions |
| --- | --- | --- | --- |
| Item added to project | An item is added to the project or created in it | Apply to, labels | Move to column, labels, issue state |
| Item removed from project | An item is removed from the project | Apply to, labels | Labels, issue state |
| Item reopened | An item is reopened | Apply to, labels | Move to column, labels |
| Item closed | An item is closed | Apply to, labels | Move to column, labels |
| Item column changed | An item moves to another column | Apply to, columns, labels | Labels, issue state |
| Code changes requested | An official reviewer requests changes on a pull request | Labels | Move to column, labels |
| Code review approved | An official reviewer approves a pull request | Labels | Move to column, labels |
| Pull request merged | A pull request is merged | Labels | Move to column, labels |
## Concepts
Every workflow is composed of `event`, `filters`, and `actions`.
- **Event** - An Event defines when a workflow should be triggered. It represents specific activities such as an issue being added to the project, a pull request being merged, or a project column being changed.
- **Filter** - A Filter refines when an event should take effect. It allows users to specify conditions like issue type, labels, or project columns to ensure actions only run in targeted scenarios.
- **Action** - An Action defines what happens when the event and filters match. It performs operations such as adding labels, moving issues between columns, or changing the issue or pull request state.
## Supported events
| Event | Fires when |
| --- | --- |
| Issues/PRs closed | The issue or pull request is closed. |
| Issues/PRs reopened | A previously closed issue or pull request is reopened. |
| Added to project | An issue or pull request is added to the project, including when it is created in the project. |
| Removed from project | An issue or pull request is removed from the project. |
| Column changed | A card moves from one column to another. |
| Code changes requested | A reviewer requests changes on a pull request connected to the project. |
| Code review approved | A reviewer approves the pull request. |
| Pull request merged | The pull request is merged. |
Each event can have multiple workflows so you can handle the same trigger differently for separate sets of cards.
## Filters
A workflow without filters runs for every item.
Filters refine when an event should run. If none are configured, the workflow runs on every occurrence of the event.
- **Apply to**: issues, pull requests, or both.
- **When moved from column**, **When moved to column**: the column the item left or entered.
- **Only if it has labels**: the item must have all selected labels.
- **Apply to** - Specify the target type: `issues only`, `pull requests only`, or `issues and pull requests`.
- **Labels** - Trigger the event only if the issue or pull request contains one or more specified labels.
- **Move from column** - Filter events based on the original project column.
- **Move to column** - Filter events based on the destination project column.
You can combine filters to require multiple conditions (for example, PRs with the `needs-review` label moving into the "Review" column).
## Actions
A workflow needs at least one action. Actions run in this order:
A workflow moves the card first, then changes labels, then changes the issue state. Available actions are:
1. **Move to column**: moves the item to a column.
2. **Add labels**, **Remove labels**: changes the item's labels.
3. **Issue state**: closes or reopens the item. Workflows never reopen pull requests.
- **Add labels** - Automatically add one or more labels to the issue or pull request.
- **Remove labels** - Remove one or more specified labels.
- **Move to column** - Move the issue or pull request to a designated project column.
- **Issue state** - Close or reopen the issue. Pull requests can only be closed.
Workflow changes appear in the timeline as "Project workflow" followed by the event, and don't trigger other workflows. Workflows don't run in closed projects or for items in archived repositories.
Combine actions to build more complex automations (for example, move the card and apply labels in a single workflow).
## Managing workflows
### Enable or disable
Each workflow has its own toggle. Disable a workflow to pause it temporarily without losing its configuration. Disabled workflows are ignored even if the event fires. Workflows of closed projects don't run either.
### Clone an event workflow
Use **Clone** to duplicate the current workflow (event, filters, and actions). This is useful when you need several variations of the same trigger—adjust the copied filters/actions and save under a new name.
## Permissions
Anyone who can read a project can view its workflows. Managing them requires write access to the project and:
Permissions are checked when workflows are managed, not when they run.
- Repository project: write access to the repository's issues and pull requests.
- Organization project: organization owner or site administrator.
- User project: the project's owner.
Access tokens limited to public repositories can't manage workflows for organization or user projects. Workflows apply their actions regardless of who triggered the event.
- **Viewing** a project's workflows needs read access to the project.
- **Creating, editing, enabling, disabling and deleting** them needs write access to the project plus authority over every item it can hold: write access to both issues and pull requests of the repository for a repository project, being an organization owner or a site administrator for an organization project, and being the user for a user project. Tokens limited to public repositories can't manage workflows of organization or user projects.
- **A workflow runs** when its event happens to an item in an open project, if the item's repository isn't archived and belongs to the project's repository or owner, no matter who caused the event.
- **Its actions apply without further permission checks**, including adding labels to and closing pull requests. Pull requests are never reopened by workflows.
- Changes made by a workflow show in the timeline as done by "Project workflow" and are attributed to the user who triggered the event, like review requests made by CODEOWNERS. They don't trigger other workflows.
- Only users who can read an item can add it to a project or move its card, so a workflow never acts for someone on an item they can't see.
## API
Manage workflows under the project routes of a repository (`/repos/{owner}/{repo}/projects/{id}`), an organization (`/orgs/{org}/projects/{id}`) or the authenticated user (`/user/projects/{id}`):
Workflows can also be managed through the REST API under the project routes of a repository (`/repos/{owner}/{repo}/projects/{id}`), an organization (`/orgs/{org}/projects/{id}`) or the authenticated user (`/user/projects/{id}`):
| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `.../workflows` | List workflows |
| `GET` | `.../workflows` | List the project's workflows |
| `GET` | `.../workflows/{workflow_id}` | Get a workflow |
| `POST` | `.../workflows` | Create a workflow |
| `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields stay unchanged |
| `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields are left unchanged |
| `DELETE` | `.../workflows/{workflow_id}` | Delete a workflow |
A workflow has an `event` (`item_added_to_project`, `item_removed_from_project`, `item_reopened`, `item_closed`, `item_column_changed`, `code_changes_requested`, `code_review_approved` or `pull_request_merged`), an `enabled` flag, `filters` (`issue_type`, `source_column_id`, `target_column_id`, `label_ids`) and `actions` (`column_id`, `add_label_ids`, `remove_label_ids`, `issue_state`). Each event accepts only the filters and actions listed in [Events](#events).
A workflow has an `event` (`item_added_to_project`, `item_removed_from_project`, `item_reopened`, `item_closed`, `item_column_changed`, `code_changes_requested`, `code_review_approved` or `pull_request_merged`), an `enabled` flag, `filters` (`issue_type`, `source_column_id`, `target_column_id`, `label_ids`) and `actions` (`column_id`, `add_label_ids`, `remove_label_ids`, `issue_state`). The same [permissions](#permissions) apply as in the UI.
## Example
## Example: triage incoming bug reports
To route new bug reports to triage, create a workflow for **Item added to project**:
The following workflow keeps bug reports organized automatically:
- **Apply to**: Issues only
- **Only if it has labels**: `bug`
- **Move to column**: Triage
- **Add labels**: `needs-triage`
1. **Event:** Added to project.
2. **Filters:** Apply to `issues only`; Labels include `bug`.
3. **Actions:**
- Add labels → `needs-triage`.
- Move to column → "Needs Triage".
- Issue state → leave open (no change) but could optionally reopen to ensure visibility.
With this configuration every new bug issue when added to this project immediately lands in the right column with the correct label, so maintainers always know what still needs triage.
Start small, test the workflow on a single project, and expand the automation set as your team discovers repetitive tasks you can offload to workflows.
+13 -69
View File
@@ -9,36 +9,25 @@ aliases:
# Code Owners
Gitea reads the first CODEOWNERS file found at these locations, in order:
Gitea maintains code owner files. It looks for it in the following locations in this order:
- `./CODEOWNERS`
- `./docs/CODEOWNERS`
- `./.gitea/CODEOWNERS`
Pull requests use the base branch's rules. File views show owners from the commit
being viewed, including when browsing a branch, tag, or historical commit.
And stops at the first found file.
## Patterns and owners
File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
Each rule contains a pattern followed by users or organization teams.
Patterns starting with `*` or containing `/*` are parsed as glob expressions.
General patterns are parsed as regular expressions.
A leading `!` inverts a match.
Special rule characters like space, backslash and `#` must be escaped with a backslash.
When using regexp, since backslash needs to be escaped in rule level, literal dot should be written as `\\.`
Regexp specified in golang Regex format.
Regexp can start with `!` for negative rules - match all files except specified.
Example file:
```text
*.js @alice @bob # This is an inline comment
doc/*.md @charles # Patterns starting with "*" or containing "/*" are parsed as glob
src/**/db*.py @david # Use "**" to match any-level sub directories
.*\\.go @user1 @user2 # General patterns are parsed as regexp
test\\..*\\.js @user3 # !!! Do remeber: NOT "test.*.js", only regexp can be used for such cases
```bash
.*\\.go @user1 @user2 # This is comment
# Comment too
# You can assigning code owning for users or teams
frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
@@ -53,69 +42,24 @@ docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
Code owners listed in this file will automatically be requested to review pull requests
that modify files matching at least one corresponding rule.
## Sections
### Escaping
A section heading can supply default owners for the rules that follow it:
You can escape characters `#`, ` ` (space) and `\` with `\`, like:
```text
[Documentation] @org1/team-doc
*.md
README.md @alice
[Frontend] @bob
*.js
```
Owners on a rule replace the section's default owners. Section names are
case-insensitive; repeated headings belong to the same section. For each file, the
last matching rule in each named section applies. Matching rules outside named
sections retain Gitea's existing behavior: they all apply.
## Review request annotations
Use `## review-request=true` or `## review-request=false` to control automatic
review requests. A line annotation overrides a section annotation, which overrides
the global value. When none is set, individual code owners receive automatic review
requests only if they watch the repository and include pull requests in their watch
preferences. Team-level requests are enabled by default. An explicit `true` requests
a review regardless of the individual owner's watch preferences; `false` disables
automatic requests for the rule.
```text
## review-request=false # global default for following rules
*.js @alice ## review-request=true # only this rule
[Documentation] @org1/team-doc ## review-request=true
*.md
private/* @bob ## review-request=false
```
A standalone annotation changes the global default for subsequent rules.
Annotations on section headings apply until the next heading. Ordinary comments
start with `#`, including comments after annotations.
Disabling review requests keeps code owners visible when viewing a file and
does not waive approvals required by branch protection.
## Escaping
You need to escape characters `#`, ` ` (space) and `\` with backslash `\`, e.g.:
```text
dir/with\#hashtag @user1
path\ with\ space @user2
path/with\\backslash @user3
```
Some regexp characters (`.+*?()|[]{}^$\`) should be escaped with `\\`, e.g.:
Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
```
path/\\.with\\.dots
path/with\\+plus
```
## Branch Protection Rules
### Branch Protection Rules
When setting up branch protection rules, you may choose to enforce code owner approval of
modified files. This will block a PR from being merged until at least one code owner
@@ -123,7 +67,7 @@ has given approval for every applicable rule listed in the `CODEOWNERS` file.
For example, say you have the following `CODEOWNERS` file:
```text
```bash
.*\\.go @Bob
.*\\.md @Sally @Chris
migrations/.* @Alice
@@ -141,7 +141,7 @@ aliases:
- `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: 在默认的 squash 合并消息中,包括构成拉取请求的所有提交的提交消息。
- `ADD_CO_COMMITTER_TRAILERS`: **true**: 如果提交者与作者不匹配,在合并提交消息中添加`co-authored-by`和`co-committed-by`标记。
- `RETARGET_CHILDREN_ON_MERGE`: **true**: 当父合并请求被合并时,将子合并请求重新定向到父合并请求的目标分支。仅适用于头分支和基分支指向同一仓库的已合并合并请求。
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: 为新仓库设置"合并后默认删除合并请求分支"的默认值。
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: 为新仓库设置"合并后默认删除合并请求分支"的默认值。
### 仓库 - 工单 (`repository.issue`)
@@ -524,8 +524,7 @@ Gitea 创建以下非唯一队列:
- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理认证的 HTTP 头部名称,用于提供用户信息。
- `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理认证的 HTTP 头部名称,用于提供邮箱信息。
- `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理认证的 HTTP 头部名称,用于提供全名信息。
- `REVERSE_PROXY_LIMIT`: **1**: 按顺序解释 X-Real-IP、X-Forwarded-For 或 Forwarded 标头,并将其设置为请求的远程 IP。
客户端端口取自标头值,或在使用 X-Real-IP 时取自 X-Real-Port。
- `REVERSE_PROXY_LIMIT`: **1**: 解释 X-Forwarded-For 标头或 X-Real-IP 标头,并将其设置为请求的远程 IP。
可信代理计数。设置为零以不使用这些标头。
- `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: 逗号分隔的受信任代理服务器的 IP 地址和网络列表。使用 `*` 来信任全部。
- `DISABLE_GIT_HOOKS`: **true**: 设置为 `false` 以允许具有 Git 钩子权限的用户创建自定义 Git 钩子。
@@ -1196,7 +1195,7 @@ In-Reply-To =
- `JWT_SECRET_URI`:**_empty_**: 可以使用此配置选项,而不是在配置中定义`JWT_SECRET`,以向 Gitea 提供包含密钥的文件的路径(示例值:`file:/etc/gitea/oauth2_jwt_secret`)。
- `JWT_SIGNING_PRIVATE_KEY_FILE`:**jwt/private.pem**: 用于签署 OAuth2 令牌的私钥文件路径。路径相对于`APP_DATA_PATH`。仅当`JWT_SIGNING_ALGORITHM`设置为`RS256`,`RS384`,`RS512`,`ES256`,`ES384`或`ES512`时才需要此设置。文件必须包含 PKCS8 格式的 RSA 或 ECDSA 私钥。如果不存在密钥,则将为您创建一个 4096 位密钥。
- `MAX_TOKEN_LENGTH`:**32767**: 从 OAuth2 提供者接受的令牌/cookie 的最大长度。
- `DEFAULT_APPLICATIONS`:**git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: 在启动时预注册用于某些服务的 OAuth 应用程序。有关可用选项列表,请参阅[OAuth2 文档](/development/oauth2-provider.md)。
- `DEFAULT_APPLICATIONS`:**git-credential-oauth,git-credential-manager, tea**: 在启动时预注册用于某些服务的 OAuth 应用程序。有关可用选项列表,请参阅[OAuth2 文档](/development/oauth2-provider.md)。
## i18n (`i18n`)
@@ -1300,7 +1299,6 @@ ALLOW_DATA_URI_IMAGES = true
- `CHUNKED_UPLOAD_PATH`:**tmp/package-upload**: 分块上传的路径。默认为 `APP_DATA_PATH` + `tmp/package-upload`。
- `LIMIT_TOTAL_OWNER_COUNT`:**-1**: 单个所有者可以拥有的包版本的最大数量(`-1` 表示无限制)。
- `LIMIT_TOTAL_OWNER_SIZE`:**-1**: 单个所有者可以使用的包的最大大小(`-1` 表示无限制,格式为 `1000`、`1 MB`、`1 GiB`)。
- `MAX_DECOMPRESSION_RATIO`: **200**: Maximum inflation ratio while reading an upload's metadata from an archive
- `LIMIT_SIZE_ALPINE`:**-1**: Alpine 上传的最大大小(`-1` 表示无限制,格式为 `1000`、`1 MB`、`1 GiB`)。
- `LIMIT_SIZE_CARGO`:**-1**: Cargo 上传的最大大小(`-1` 表示无限制,格式为 `1000`、`1 MB`、`1 GiB`)。
- `LIMIT_SIZE_CHEF`:**-1**: Chef 上传的最大大小(`-1` 表示无限制,格式为 `1000`、`1 MB`、`1 GiB`)。
@@ -8,7 +8,7 @@ aliases:
# 数据库准备
在使用 Gitea 前,您需要准备一个数据库。Gitea 支持 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(内置) 和 MSSQL(>= 2012 SP4)这几种数据库。本页将指导您准备数据库。本文档涵盖 PostgreSQL、MySQL 和 MSSQL。如果您计划使用 SQLite,则可以忽略本章内容。
在使用 Gitea 前,您需要准备一个数据库。Gitea 支持 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(内置) 和 MSSQL(>= 2012 SP4)这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用,因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite,则可以忽略本章内容。
如果您使用不受支持的数据库版本,请通过 [联系我们](/help/support) 以获取有关我们的扩展支持的信息。我们可以为旧数据库提供测试和支持,并将这些修复集成到 Gitea 代码库中。
@@ -168,28 +168,6 @@ aliases:
您应该会被提示输入数据库用户的密码,并连接到数据库。
## MSSQL
1. 以管理员身份创建登录名、使用大小写敏感排序规则的数据库及其用户。请将密码 `'gitea'` 替换为安全的密码:
```sql
CREATE LOGIN gitea WITH PASSWORD = 'gitea';
CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
GO
USE giteadb;
CREATE USER gitea FOR LOGIN gitea;
ALTER ROLE db_owner ADD MEMBER gitea;
GO
```
升级会更改数据库结构,因此该用户需要 `db_owner`,或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用后者时,还需以管理员身份执行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
2. 在您的 Gitea 服务器上,测试与数据库的连接:
```sh
sqlcmd -S 203.0.113.3 -U gitea -d giteadb
```
## 使用 TLS 进行数据库连接
如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的,或者如果 Gitea 和数据库运行在同一台服务器上,那么可以省略本节,因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是,如果数据库实例位于公共网络上,请使用 TLS 对数据库连接进行加密,以防止第三方拦截流量数据。
@@ -18,7 +18,18 @@ Gitea Actions旨在与GitHub Actions兼容,差异如下。
<a id="action-prefixes"></a>
### Action前缀
`uses:`支持`self:`前缀,用于引用您自己的Gitea实例,例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`。
`uses:`支持以下前缀:
- `self:`引用您自己的Gitea实例,例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`
- `builtin:`运行Gitea Runner内置的Action,无需下载,Job镜像中也无需Node,例如`uses: builtin:checkout`
`builtin:checkout`支持`actions/checkout`的`repository`、`ref`、`token`、`path`和`fetch-depth`输入,默认值相同,其他输入会使步骤失败。
<a id="workflow-relative-actions"></a>
### 相对于工作流的Actions
`$/`引用工作流所在的仓库和提交,或外层复合Action所在的仓库和提交,例如`uses: $/.gitea/actions/build`。
与`./`不同,它无需事先检出代码。
### 使用Go编写Actions
@@ -84,7 +95,7 @@ Gitea Actions旨在与GitHub Actions兼容,差异如下。
未指定主机的Actions(如`uses: actions/checkout@v4`)会从`https://github.com`下载,当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载。
请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
其他来源请参阅[Action URL绝对路径](#absolute-action-urls)和[Action前缀](#action-prefixes)。
其他来源请参阅[Action URL绝对路径](#absolute-action-urls)、[Action前缀](#action-prefixes)和[相对于工作流的Actions](#workflow-relative-actions)。
### 上下文可用性
@@ -6,90 +6,10 @@ sidebar_position: 25
# 变量
## 环境变量
以下环境变量会在每次工作流运行时自动设置,可以直接访问(例如在 shell 脚本中使用 `$CI`)。
同时列出 `GITEA_*` 和 `GITHUB_*` 名称的变量值相同。
| 名称 | 描述 | 示例 |
|---|---|---|
| `ACT` | 始终为 `true`,除非 Runner 配置了 `runner.set_act_env: false`。 | `true` |
| `CI` | 始终为 `true`。 | `true` |
| `GITEA_ACTION`<br/>`GITHUB_ACTION` | 当前步骤的 `id`,未设置时为步骤的序号。 | `0` |
| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | Action 所在的路径。仅在复合 Action 中设置。 | `/var/run/act/actions/***` |
| `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | 正在执行的 Action 的 ref。 | `v4` |
| `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | Action 的所有者和仓库名称。 | `actions/checkout` |
| `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | 始终为 `true`。`GITEA_ACTIONS` 可用于区分 Gitea Actions 和其他 CI 系统。 | `true` |
| `GITEA_ACTIONS_RUNNER_VERSION` | 执行工作流的 Runner 的版本。 | `v5.2.4` |
| `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | 触发工作流的用户的用户名。 | `alice` |
| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | 触发工作流的用户的 ID。 | `1` |
| `GITEA_API_URL`<br/>`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` |
| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | 拉取请求的目标分支。 | `main` |
| `GITEA_DOCKER_WORKSPACE` | Docker 守护进程所见的工作区路径,用于绑定挂载到 Job 启动的容器中,例如在 compose 文件中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。仅在 Job 运行于容器中时设置。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
| `GITEA_ENV`<br/>`GITHUB_ENV` | 为后续步骤设置环境变量的文件路径。 | `/var/run/act/workflow/envs.txt` |
| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | 触发工作流的事件名称。 | `push` |
| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | 包含事件 Webhook 负载的文件路径。 | `/var/run/act/workflow/event.json` |
| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | 在 Gitea 中为空(不支持 GraphQL)。 | _(空)_ |
| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | 拉取请求的源分支。 | `feature-branch` |
| `GITEA_JOB`<br/>`GITHUB_JOB` | 当前 Job 的 `job_id`。 | `build` |
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | 设置步骤输出参数的文件路径。 | `/var/run/act/workflow/outputcmd.txt` |
| `GITEA_PATH`<br/>`GITHUB_PATH` | 为后续步骤添加系统 `PATH` 条目的文件路径。 | `/var/run/act/workflow/pathcmd.txt` |
| `GITEA_REF`<br/>`GITHUB_REF` | 触发工作流的完整 ref。 | `refs/heads/main` |
| `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | ref 的短名称。 | `main` |
| `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | 如果触发工作流的 ref 配置了分支保护,则为 `true`。 | `true` |
| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | ref 的类型:`branch` 或 `tag`。 | `branch` |
| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | 所有者和仓库名称。 | `owner/repo` |
| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | 仓库的 ID。 | `123` |
| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | 仓库所有者的用户名。 | `owner` |
| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | 仓库所有者的 ID。 | `45` |
| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | Artifact 的保留天数,永久保留时为空。 | `90` |
| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | 工作流运行的尝试次数。 | `1` |
| `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | 每次工作流运行的唯一编号。 | `1234` |
| `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | 特定工作流每次运行的唯一编号。 | `42` |
| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | Gitea 实例的 URL。 | `https://gitea.example.com` |
| `GITEA_SHA`<br/>`GITHUB_SHA` | 触发工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITEA_STATE`<br/>`GITHUB_STATE` | 设置步骤状态变量的文件路径。 | `/var/run/act/workflow/statecmd.txt` |
| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | 写入 Job 摘要的文件路径。 | `/var/run/act/workflow/step-summary-0.md` |
| `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | 发起工作流运行的用户的用户名。重新运行时可能与 `GITEA_ACTOR` 不同。 | `alice` |
| `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | 工作流的名称。 | `CI` |
| `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | 工作流文件的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | Runner 上的默认工作目录。 | `/workspace/owner/repo` |
| `TRACEPARENT` | Job span 的 W3C 追踪上下文,供已接入追踪的工具将 span 添加到 Job 的追踪中。仅在 Runner 导出追踪数据时设置,参见[监控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
| `TRACESTATE` | 随 `TRACEPARENT` 附带的厂商特定追踪数据。仅在追踪包含此类数据时设置。 | `rojo=00f067aa0ba902b7` |
### Runner 环境变量
| 名称 | 描述 | 示例 |
|---|---|---|
| `ImageOS` | Job 镜像的操作系统和版本,供 `setup-*` Action 读取。 | `ubuntu24` |
| `RUNNER_ARCH` | Runner 的架构。 | `X64` |
| `RUNNER_DEBUG` | 当 `ACTIONS_STEP_DEBUG` 密钥为 `true` 时设置为 `1`,否则不设置。 | `1` |
| `RUNNER_ENVIRONMENT` | 始终为 `self-hosted`。 | `self-hosted` |
| `RUNNER_NAME` | 执行 Job 的 Runner 的名称。 | `my-runner` |
| `RUNNER_OS` | Runner 的操作系统。 | `Linux` |
| `RUNNER_TEMP` | Runner 上临时目录的路径。 | `/tmp` |
| `RUNNER_TOOL_CACHE` | Runner 上工具缓存目录的路径。 | `/opt/hostedtoolcache` |
| `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的父目录。 | `/workspace/owner` |
### 内部环境变量
这些变量供 Runner 和 Action 内部使用,工作流中通常不需要直接使用。
| 名称 | 描述 | 示例 |
|---|---|---|
| `ACTIONS_CACHE_URL` | Actions 缓存服务的 URL。 | `http://192.168.1.10:8088/` |
| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用于 OIDC 请求的令牌。仅在授予 `id-token: write` 时设置。 | `***` |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | 请求 OIDC 令牌的 URL。仅在授予 `id-token: write` 时设置。 | `https://gitea.example.com/api/actions/oidc/token?` |
| `ACTIONS_RESULTS_URL` | 存储 Artifact 的 URL。 | `https://gitea.example.com` |
| `ACTIONS_RUNTIME_TOKEN` | Actions 流水线 API 的认证令牌。 | `***` |
| `ACTIONS_RUNTIME_URL` | Gitea Actions 流水线 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` |
## 用户定义的变量
您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时,变量的名称会被
转换为大写,在yaml文件中引用时需要使用大写。
### 命名规则
## 命名规则
以下规则适用于变量名:
@@ -100,11 +20,11 @@ sidebar_position: 25
- 变量名称在创建它们的级别上必须是唯一的。
- 变量名称不能为 `CI`。
### 使用
## 使用
创建配置变量后,它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似 `${{ vars.VARIABLE_NAME }}` 这样的表达式来使用它们。
### 优先级
## 优先级
如果同名变量存在于多个级别,则级别最低的变量优先。
仓库级别的变量总是比组织或者用户级别的变量优先被选中。
@@ -4,6 +4,6 @@
"link": {
"type": "generated-index",
"slug": "/usage/projects",
"description": "使用项目看板规划和跟踪工作"
"description": "规划、跟踪并自动化仓库项目"
}
}
@@ -2,81 +2,113 @@
date: "2025-11-25T18:58:22Z"
slug: "project-workflows"
sidebar_position: 1
description: "通过事件驱动的过滤器和动作自动化项目看板。"
description: "在仓库项目上使用事件、过滤器和动作组合来自动化重复操作。"
---
# 项目工作流
项目工作流可自动化项目看板。当项目中的问题或合并请求触发事件时,该事件下每个已启用的工作流都会检查其过滤条件并执行相应动作。工作流在 Gitea 中运行,无需运行器。
项目工作流可以在仓库项目看板上根据问题或拉取请求触发的事件自动执行操作。该功能无需外部 Runner 或 Webhook,完全在 Gitea 内部运行。
## 编辑工作流
有权管理项目工作流的用户可以创建、编辑、克隆、启用或禁用工作流,详见[权限](#权限)。
1. 打开项目并选择 **Workflows**。
2. 在侧边栏中选择事件。
3. 设置过滤器和动作,然后选择 **Save**。要修改现有工作流,请先选择 **Edit**。
## 打开工作流编辑器
一个事件可以有多个工作流。**Clone** 会复制选中的工作流,便于调整后用于其他条目。**Disable** 会暂停工作流并保留其配置。**Remove** 会删除工作流。
1. 进入仓库并打开需要自动化的 **Projects** 看板。
2. 在看板顶部的菜单中选择 **Workflows**。
3. 点击左侧栏中的事件以编辑其工作流。
4. 选择事件、追加过滤器、按顺序添加需要的动作并保存。
## 事件
每个工作流都存放在所属的项目下。如果另一个项目需要类似逻辑,请在目标项目中重新创建或克隆工作流。
| 事件 | 触发时机 | 过滤器 | 动作 |
| --- | --- | --- | --- |
| Item added to project | 条目被添加到项目或在项目中创建时 | Apply to、标签 | Move to column、标签、问题状态 |
| Item removed from project | 条目被移出项目时 | Apply to、标签 | 标签、问题状态 |
| Item reopened | 条目被重新打开时 | Apply to、标签 | Move to column、标签 |
| Item closed | 条目被关闭时 | Apply to、标签 | Move to column、标签 |
| Item column changed | 条目移至另一列时 | Apply to、列、标签 | 标签、问题状态 |
| Code changes requested | 正式审查者要求修改合并请求时 | 标签 | Move to column、标签 |
| Code review approved | 正式审查者批准合并请求时 | 标签 | Move to column、标签 |
| Pull request merged | 合并请求被合并时 | 标签 | Move to column、标签 |
## 基本概念
- **事件(Event)**:定义何时评估工作流,例如问题加入项目或卡片在列间移动。
- **过滤器(Filter)**:可选条件,只有满足条件才会执行动作,例如标签或列的变化。
- **动作(Action)**:当事件与过滤器匹配时 Gitea 要执行的操作,例如添加标签或移动卡片。
## 支持的事件
| 事件 | 触发时机 |
| --- | --- |
| 关闭问题/拉取请求 | 该问题或拉取请求被关闭。 |
| 重新打开问题/拉取请求 | 已关闭的条目被重新打开。 |
| 加入项目 | 问题或拉取请求被添加到该项目,包括在该项目中新建时。 |
| 从项目移除 | 条目被从项目中移出。 |
| 列发生变化 | 卡片从一个列移动到另一个列。 |
| 被请求修改 | 与项目关联的拉取请求收到修改请求。 |
| 审查通过 | 审查者批准了该拉取请求。 |
| 拉取请求已合并 | 该拉取请求被合并。 |
每个事件都可以配置多个工作流,以便在不同场景下对同一触发器执行不同操作。
## 过滤器
未设置过滤器的工作流会对每个条目运行。
过滤器用于进一步限定事件是否需执行。如果未配置过滤器,事件发生时工作流始终运行。
- **Apply to**:问题、合并请求或两者。
- **When moved from column**、**When moved to column**:条目离开或进入的列。
- **Only if it has labels**:条目必须包含所有选中的标签。
- **适用对象(Apply to)**:限定仅匹配 `issues only`、`pull requests only` 或同时匹配。
- **标签(Labels)**:仅当卡片已包含指定标签之一时运行。
- **来源列(Move from column)**:仅当卡片原本位于所选列之一时运行,常与“列发生变化”事件组合。
- **目标列(Move to column)**:仅当卡片移动到指定列时运行。
可以组合多个过滤器以同时满足多种条件,例如“带有 `needs-review` 标签的拉取请求移动到 “Review” 列”。
## 动作
工作流至少需要一个动作。动作按以下顺序执行:
工作流先移动卡片,再修改标签,最后更改问题状态。可用的动作包括:
1. **Move to column**:将条目移至某一列。
2. **Add labels**、**Remove labels**:更改条目的标签。
3. **Issue state**:关闭或重新打开条目。工作流不会重新打开合并请求。
- **添加标签(Add labels)**:为问题或拉取请求附加一个或多个标签。
- **移除标签(Remove labels)**:删除不再需要的标签。
- **移动到列(Move to column)**:将卡片移动到同一项目看板中的另一列。
- **问题状态(Issue state)**:关闭或重新打开关联的问题。拉取请求只能被关闭。
工作流所做的更改在时间线中显示为“Project workflow”及其后的事件名称,且不会触发其他工作流。工作流不会在已关闭的项目中运行,也不会处理已归档仓库中的条目。
通过组合多个动作,可在单个工作流中完成移动卡片、更新标签等多重操作。
## 管理工作流
### 启用或禁用
每个工作流都带有独立的开关。禁用后即使事件触发也会被忽略,适合临时暂停自动化而保留配置。已关闭项目的工作流也不会运行。
### 克隆事件工作流
点击 **Clone** 可以复制当前工作流(事件、过滤器与动作都会被复制)。在需要针对同一触发器设置不同条件时,复制并微调即可快速得到新的工作流。
## 权限
任何拥有项目读取权限的人都可以查看其工作流。管理工作流需要项目的写入权限,并满足以下条件:
权限在管理工作流时检查,而不是在工作流运行时检查。
- 仓库项目:拥有该仓库的问题和合并请求的写入权限。
- 组织项目:是组织所有者或站点管理员。
- 用户项目:是项目所有者。
仅限公开仓库的访问令牌无法管理组织或用户项目的工作流。无论谁触发事件,工作流都会执行其动作。
- **查看**项目的工作流需要该项目的读取权限。
- **创建、编辑、启用、禁用和删除**工作流需要该项目的写入权限,以及对该项目可容纳的所有条目的权限:仓库项目需要对该仓库的问题和拉取请求都拥有写入权限,组织项目需要是组织所有者或站点管理员,用户项目需要是该用户本人。仅限公开仓库的令牌不能管理组织或用户项目的工作流。
- **工作流在**开放项目中的条目发生对应事件时运行,前提是条目所在仓库未归档且属于该项目的仓库或所有者,与谁触发了事件无关。
- **其动作直接执行,不再进行权限检查**,包括为拉取请求添加标签和关闭拉取请求。工作流不会重新打开拉取请求。
- 工作流所做的更改在时间线中显示为由“项目工作流”完成,并归属于触发该事件的用户,与 CODEOWNERS 发起的审查请求相同。这些更改不会触发其他工作流。
- 只有能读取条目的用户才能将其加入项目或移动其卡片,因此工作流不会替用户操作其无法查看的条目。
## API
可通过仓库(`/repos/{owner}/{repo}/projects/{id}`)、组织(`/orgs/{org}/projects/{id}`)或已认证用户(`/user/projects/{id}`)的项目路由管理工作流:
也可以通过 REST API 管理工作流,路径位于仓库(`/repos/{owner}/{repo}/projects/{id}`)、组织(`/orgs/{org}/projects/{id}`)或当前用户(`/user/projects/{id}`)的项目路由下:
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `.../workflows` | 列出工作流 |
| `GET` | `.../workflows` | 列出项目的工作流 |
| `GET` | `.../workflows/{workflow_id}` | 获取工作流 |
| `POST` | `.../workflows` | 创建工作流 |
| `PATCH` | `.../workflows/{workflow_id}` | 编辑工作流,未提供的字段保持不变 |
| `DELETE` | `.../workflows/{workflow_id}` | 删除工作流 |
工作流包含 `event`(`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`)、`enabled` 标志、`filters`(`issue_type`、`source_column_id`、`target_column_id`、`label_ids`)以及 `actions`(`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`)。每个事件仅接受[事件](#事件)表中列出的过滤器和动作。
工作流包含 `event`(`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`)、`enabled` 开关、`filters`(`issue_type`、`source_column_id`、`target_column_id`、`label_ids`)以及 `actions`(`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`)。权限规则与界面操作相同,参见[权限](#权限)。
## 示例
## 示例:自动分流新的缺陷报告
要将新的缺陷报告分流至待分类列,请为 **Item added to project** 创建工作流:
以下工作流可以让缺陷报告自动进入待处理区:
- **Apply to**:Issues only
- **Only if it has labels**:`bug`
- **Move to column**:Triage
- **Add labels**:`needs-triage`
1. **事件:** 加入项目(Added to project)。
2. **过滤器:** 仅适用于 `issues only`;标签包含 `bug`。
3. **动作:**
- 添加标签 → `needs-triage`。
- 移动到列 → “Needs Triage”。
- 问题状态 → 保持打开(如有需要也可以强制重新打开以确保可见)。
配置完成后,每当新的缺陷问题加入该项目时都会立即拥有正确的标签并出现在指定列中,维护者可以第一时间看到需要分流的条目。
从简单规则开始,在单个项目中验证效果,再根据团队的重复性任务逐步扩展自动化逻辑。
@@ -8,7 +8,7 @@ aliases:
# 数据库准备
在使用 Gitea 前,您需要准备一个数据库。Gitea 支持 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(内置) 和 MSSQL(>= 2012 SP4)这几种数据库。本页将指导您准备数据库。本文档涵盖 PostgreSQL、MySQL 和 MSSQL。如果您计划使用 SQLite,则可以忽略本章内容。
在使用 Gitea 前,您需要准备一个数据库。Gitea 支持 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(内置) 和 MSSQL(>= 2012 SP4)这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用,因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite,则可以忽略本章内容。
如果您使用不受支持的数据库版本,请通过 [联系我们](/help/support) 以获取有关我们的扩展支持的信息。我们可以为旧数据库提供测试和支持,并将这些修复集成到 Gitea 代码库中。
@@ -168,28 +168,6 @@ aliases:
您应该会被提示输入数据库用户的密码,并连接到数据库。
## MSSQL
1. 以管理员身份创建登录名、使用大小写敏感排序规则的数据库及其用户。请将密码 `'gitea'` 替换为安全的密码:
```sql
CREATE LOGIN gitea WITH PASSWORD = 'gitea';
CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
GO
USE giteadb;
CREATE USER gitea FOR LOGIN gitea;
ALTER ROLE db_owner ADD MEMBER gitea;
GO
```
升级会更改数据库结构,因此该用户需要 `db_owner`,或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用后者时,还需以管理员身份执行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
2. 在您的 Gitea 服务器上,测试与数据库的连接:
```sh
sqlcmd -S 203.0.113.3 -U gitea -d giteadb
```
## 使用 TLS 进行数据库连接
如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的,或者如果 Gitea 和数据库运行在同一台服务器上,那么可以省略本节,因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是,如果数据库实例位于公共网络上,请使用 TLS 对数据库连接进行加密,以防止第三方拦截流量数据。
@@ -21,7 +21,15 @@ Gitea Actions旨在与GitHub Actions兼容,差异如下。
`uses:`支持以下前缀:
- `self:`引用您自己的Gitea实例,例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`
- `builtin:`运行Gitea Runner内置的Action,无需下载,也不依赖Node.js,例如`uses: builtin:checkout`
- `builtin:`运行Gitea Runner内置的Action,无需下载,Job镜像中也无需Node,例如`uses: builtin:checkout`
`builtin:checkout`支持`actions/checkout`的`repository`、`ref`、`token`、`path`和`fetch-depth`输入,默认值相同,其他输入会使步骤失败。
<a id="workflow-relative-actions"></a>
### 相对于工作流的Actions
`$/`引用工作流所在的仓库和提交,或外层复合Action所在的仓库和提交,例如`uses: $/.gitea/actions/build`。
与`./`不同,它无需事先检出代码。
### 使用Go编写Actions
@@ -87,7 +95,7 @@ Gitea Actions旨在与GitHub Actions兼容,差异如下。
未指定主机的Actions(如`uses: actions/checkout@v4`)会从`https://github.com`下载,当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载。
请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
其他来源请参阅[Action URL绝对路径](#absolute-action-urls)和[Action前缀](#action-prefixes)。
其他来源请参阅[Action URL绝对路径](#absolute-action-urls)、[Action前缀](#action-prefixes)和[相对于工作流的Actions](#workflow-relative-actions)。
### 上下文可用性
@@ -142,7 +142,7 @@ aliases:
- `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: 在預設的 squash 合併消息中,包括構成拉取請求的所有提交的提交消息。
- `ADD_CO_COMMITTER_TRAILERS`: **true**: 如果提交者與作者不匹配,在合併提交消息中添加`co-authored-by`和`co-committed-by`標記。
- `RETARGET_CHILDREN_ON_MERGE`: **true**: 當父合併請求被合併時,將子合併請求重新定向到父合併請求的目標分支。僅適用於頭分支和基分支指向同一儲存庫的已合併合併請求。
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: 為新儲存庫設定"合併後預設刪除合併請求分支"的預設值。
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: 為新儲存庫設定"合併後預設刪除合併請求分支"的預設值。
### 儲存庫 - 工單 (`repository.issue`)
@@ -529,8 +529,7 @@ Gitea 建立以下非唯一隊列:
- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理認證的 HTTP 頭部名稱,用於提供使用者資訊。
- `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理認證的 HTTP 頭部名稱,用於提供郵箱資訊。
- `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理認證的 HTTP 頭部名稱,用於提供全名資訊。
- `REVERSE_PROXY_LIMIT`: **1**: 依序解釋 X-Real-IP、X-Forwarded-For 或 Forwarded 標頭,並將其設定為請求的遠程 IP。
客戶端連接埠取自標頭值,或在使用 X-Real-IP 時取自 X-Real-Port。
- `REVERSE_PROXY_LIMIT`: **1**: 解釋 X-Forwarded-For 標頭或 X-Real-IP 標頭,並將其設定為請求的遠程 IP。
可信代理計數。設定為零以不使用這些標頭。
- `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: 逗號分隔的受信任代理伺服器的 IP 地址和網路列表。使用 `*` 來信任全部。
- `DISABLE_GIT_HOOKS`: **true**: 設定為 `false` 以允許具有 Git 鉤子權限的使用者建立自訂 Git 鉤子。
@@ -1202,7 +1201,7 @@ In-Reply-To =
- `JWT_SECRET_URI`:**_empty_**: 可以使用此設定選項,而不是在設定中定義`JWT_SECRET`,以向 Gitea 提供包含密鑰的文件的路徑(範例值:`file:/etc/gitea/oauth2_jwt_secret`)。
- `JWT_SIGNING_PRIVATE_KEY_FILE`:**jwt/private.pem**: 用於簽署 OAuth2 令牌的私鑰文件路徑。路徑相對於`APP_DATA_PATH`。僅當`JWT_SIGNING_ALGORITHM`設定為`RS256`,`RS384`,`RS512`,`ES256`,`ES384`或`ES512`時才需要此設定。文件必須包含 PKCS8 格式的 RSA 或 ECDSA 私鑰。如果不存在密鑰,則將為您建立一個 4096 位密鑰。
- `MAX_TOKEN_LENGTH`:**32767**: 從 OAuth2 提供者接受的令牌/cookie 的最大長度。
- `DEFAULT_APPLICATIONS`:**git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: 在啟動時預註冊用於某些服務的 OAuth 應用程式。有關可用選項列表,請參閱[OAuth2 文件](/development/oauth2-provider.md)。
- `DEFAULT_APPLICATIONS`:**git-credential-oauth,git-credential-manager, tea**: 在啟動時預註冊用於某些服務的 OAuth 應用程式。有關可用選項列表,請參閱[OAuth2 文件](/development/oauth2-provider.md)。
## i18n (`i18n`)
@@ -1306,7 +1305,6 @@ ALLOW_DATA_URI_IMAGES = true
- `CHUNKED_UPLOAD_PATH`:**tmp/package-upload**: 分塊上傳的路徑。預設為 `APP_DATA_PATH` + `tmp/package-upload`。
- `LIMIT_TOTAL_OWNER_COUNT`:**-1**: 單個所有者可以擁有的包版本的最大數量(`-1` 表示無限制)。
- `LIMIT_TOTAL_OWNER_SIZE`:**-1**: 單個所有者可以使用的包的最大大小(`-1` 表示無限制,格式為 `1000`、`1 MB`、`1 GiB`)。
- `MAX_DECOMPRESSION_RATIO`: **200**: Maximum inflation ratio while reading an upload's metadata from an archive
- `LIMIT_SIZE_ALPINE`:**-1**: Alpine 上傳的最大大小(`-1` 表示無限制,格式為 `1000`、`1 MB`、`1 GiB`)。
- `LIMIT_SIZE_CARGO`:**-1**: Cargo 上傳的最大大小(`-1` 表示無限制,格式為 `1000`、`1 MB`、`1 GiB`)。
- `LIMIT_SIZE_CHEF`:**-1**: Chef 上傳的最大大小(`-1` 表示無限制,格式為 `1000`、`1 MB`、`1 GiB`)。
@@ -8,7 +8,7 @@ aliases:
# 資料庫準備
在使用 Gitea 前,您需要準備一個資料庫。Gitea 支援 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(內置) 和 MSSQL(>= 2012 SP4)這幾種資料庫。本頁將指導您準備資料庫。本文件涵蓋 PostgreSQL、MySQL 和 MSSQL。如果您計劃使用 SQLite,則可以忽略本章內容。
在使用 Gitea 前,您需要準備一個資料庫。Gitea 支援 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(內置) 和 MSSQL(>= 2012 SP4)這幾種資料庫。本頁將指導您準備資料庫。由於 PostgreSQL 和 MySQL 在生產環境中被廣泛使用,因此本文件將僅涵蓋這兩種資料庫。如果您計劃使用 SQLite,則可以忽略本章內容。
如果您使用不受支援的資料庫版本,請通過 [聯繫我們](/help/support) 以獲取有關我們的擴展支援的資訊。我們可以為舊資料庫提供測試和支援,並將這些修復整合到 Gitea 程式碼庫中。
@@ -168,28 +168,6 @@ aliases:
您應該會被提示輸入資料庫使用者的密碼,並連接到資料庫。
## MSSQL
1. 以管理員身份建立登入名稱、使用大小寫敏感排序規則的資料庫及其使用者。請將密碼 `'gitea'` 替換為安全的密碼:
```sql
CREATE LOGIN gitea WITH PASSWORD = 'gitea';
CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
GO
USE giteadb;
CREATE USER gitea FOR LOGIN gitea;
ALTER ROLE db_owner ADD MEMBER gitea;
GO
```
升級會更改資料庫結構,因此該使用者需要 `db_owner`,或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用後者時,還需以管理員身份執行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
2. 在您的 Gitea 伺服器上,測試與資料庫的連接:
```sh
sqlcmd -S 203.0.113.3 -U gitea -d giteadb
```
## 使用 TLS 進行資料庫連接
如果 Gitea 和您的資料庫實例之間的通信是通過私有網路進行的,或者如果 Gitea 和資料庫運行在同一臺伺服器上,那麼可以省略本節,因為 Gitea 和資料庫實例之間的安全性不會受到嚴重威脅。但是,如果資料庫實例位於公共網路上,請使用 TLS 對資料庫連接進行加密,以防止第三方攔截流量資料。
@@ -18,7 +18,18 @@ Gitea Actions 旨在與 GitHub Actions 相容,差異如下。
<a id="action-prefixes"></a>
### Action 前綴
`uses:` 接受 `self:` 前綴,用於參照您自己的 Gitea 實例,例如 `uses: self:owner/repo@v1` 或 `uses: self:owner/repo/.gitea/workflows/build.yml@v1`。
`uses:` 接受以下前綴:
- `self:` 參照您自己的 Gitea 實例,例如 `uses: self:owner/repo@v1` 或 `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
- `builtin:` 執行 Gitea Runner 內建的 Action,無需下載,Job 映像檔中也不需要 Node,例如 `uses: builtin:checkout`
`builtin:checkout` 支援 `actions/checkout` 的 `repository`、`ref`、`token`、`path` 和 `fetch-depth` 輸入,預設值相同,其他輸入會使步驟失敗。
<a id="workflow-relative-actions"></a>
### 相對於工作流的 Actions
`$/` 參照工作流(或外層複合 Action)所在的儲存庫與提交,例如 `uses: $/.gitea/actions/build`。
與 `./` 不同,它不需要事先簽出程式碼。
### 使用Go編寫Actions
@@ -84,7 +95,7 @@ Gitea Actions 旨在與 GitHub Actions 相容,差異如下。
未指定主機的 Actions,例如 `uses: actions/checkout@v4`,會從 `https://github.com` 下載,若 `[actions].DEFAULT_ACTIONS_URL` 為 `self`,則從您自己的實例下載。
請參閱[設定速查表](../../administration/config-cheat-sheet.md#actions-actions)。
其他來源請參閱 [Action URL絕對路徑](#absolute-action-urls)和[Action 前綴](#action-prefixes)。
其他來源請參閱 [Action URL絕對路徑](#absolute-action-urls)、[Action 前綴](#action-prefixes)和[相對於工作流的 Actions](#workflow-relative-actions)。
### 上下文可用性
@@ -6,90 +6,10 @@ sidebar_position: 25
# 變量
## 環境變量
以下環境變量會在每次工作流執行時自動設定,可以直接存取(例如在 shell 腳本中使用 `$CI`)。
同時列出 `GITEA_*` 和 `GITHUB_*` 名稱的變量值相同。
| 名稱 | 描述 | 範例 |
|---|---|---|
| `ACT` | 始終為 `true`,除非 Runner 設定了 `runner.set_act_env: false`。 | `true` |
| `CI` | 始終為 `true`。 | `true` |
| `GITEA_ACTION`<br/>`GITHUB_ACTION` | 目前步驟的 `id`,未設定時為步驟的序號。 | `0` |
| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | Action 所在的路徑。僅在複合 Action 中設定。 | `/var/run/act/actions/***` |
| `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | 正在執行的 Action 的 ref。 | `v4` |
| `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | Action 的所有者和儲存庫名稱。 | `actions/checkout` |
| `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | 始終為 `true`。`GITEA_ACTIONS` 可用於區分 Gitea Actions 和其他 CI 系統。 | `true` |
| `GITEA_ACTIONS_RUNNER_VERSION` | 執行工作流的 Runner 的版本。 | `v5.2.4` |
| `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | 觸發工作流的使用者的使用者名稱。 | `alice` |
| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | 觸發工作流的使用者的 ID。 | `1` |
| `GITEA_API_URL`<br/>`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` |
| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | 拉取請求的目標分支。 | `main` |
| `GITEA_DOCKER_WORKSPACE` | Docker 守護程式所見的工作區路徑,用於綁定掛載到 Job 啟動的容器中,例如在 compose 檔案中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。僅在 Job 於容器中執行時設定。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
| `GITEA_ENV`<br/>`GITHUB_ENV` | 為後續步驟設定環境變量的檔案路徑。 | `/var/run/act/workflow/envs.txt` |
| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | 觸發工作流的事件名稱。 | `push` |
| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | 包含事件 Webhook 負載的檔案路徑。 | `/var/run/act/workflow/event.json` |
| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | 在 Gitea 中為空(不支援 GraphQL)。 | _(空)_ |
| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | 拉取請求的來源分支。 | `feature-branch` |
| `GITEA_JOB`<br/>`GITHUB_JOB` | 目前 Job 的 `job_id`。 | `build` |
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | 設定步驟輸出參數的檔案路徑。 | `/var/run/act/workflow/outputcmd.txt` |
| `GITEA_PATH`<br/>`GITHUB_PATH` | 為後續步驟新增系統 `PATH` 項目的檔案路徑。 | `/var/run/act/workflow/pathcmd.txt` |
| `GITEA_REF`<br/>`GITHUB_REF` | 觸發工作流的完整 ref。 | `refs/heads/main` |
| `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | ref 的短名稱。 | `main` |
| `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | 如果觸發工作流的 ref 設定了分支保護,則為 `true`。 | `true` |
| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | ref 的類型:`branch` 或 `tag`。 | `branch` |
| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | 所有者和儲存庫名稱。 | `owner/repo` |
| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | 儲存庫的 ID。 | `123` |
| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | 儲存庫所有者的使用者名稱。 | `owner` |
| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | 儲存庫所有者的 ID。 | `45` |
| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | Artifact 的保留天數,永久保留時為空。 | `90` |
| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | 工作流執行的嘗試次數。 | `1` |
| `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | 每次工作流執行的唯一編號。 | `1234` |
| `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | 特定工作流每次執行的唯一編號。 | `42` |
| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | Gitea 實例的 URL。 | `https://gitea.example.com` |
| `GITEA_SHA`<br/>`GITHUB_SHA` | 觸發工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITEA_STATE`<br/>`GITHUB_STATE` | 設定步驟狀態變量的檔案路徑。 | `/var/run/act/workflow/statecmd.txt` |
| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | 寫入 Job 摘要的檔案路徑。 | `/var/run/act/workflow/step-summary-0.md` |
| `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | 發起工作流執行的使用者的使用者名稱。重新執行時可能與 `GITEA_ACTOR` 不同。 | `alice` |
| `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | 工作流的名稱。 | `CI` |
| `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | 工作流檔案的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | Runner 上的預設工作目錄。 | `/workspace/owner/repo` |
| `TRACEPARENT` | Job span 的 W3C 追蹤上下文,供已接入追蹤的工具將 span 新增到 Job 的追蹤中。僅在 Runner 匯出追蹤資料時設定,參見[監控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
| `TRACESTATE` | 隨 `TRACEPARENT` 附帶的廠商特定追蹤資料。僅在追蹤包含此類資料時設定。 | `rojo=00f067aa0ba902b7` |
### Runner 環境變量
| 名稱 | 描述 | 範例 |
|---|---|---|
| `ImageOS` | Job 映像的作業系統和版本,供 `setup-*` Action 讀取。 | `ubuntu24` |
| `RUNNER_ARCH` | Runner 的架構。 | `X64` |
| `RUNNER_DEBUG` | 當 `ACTIONS_STEP_DEBUG` 密鑰為 `true` 時設定為 `1`,否則不設定。 | `1` |
| `RUNNER_ENVIRONMENT` | 始終為 `self-hosted`。 | `self-hosted` |
| `RUNNER_NAME` | 執行 Job 的 Runner 的名稱。 | `my-runner` |
| `RUNNER_OS` | Runner 的作業系統。 | `Linux` |
| `RUNNER_TEMP` | Runner 上暫存目錄的路徑。 | `/tmp` |
| `RUNNER_TOOL_CACHE` | Runner 上工具快取目錄的路徑。 | `/opt/hostedtoolcache` |
| `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的上層目錄。 | `/workspace/owner` |
### 內部環境變量
這些變量供 Runner 和 Action 內部使用,工作流中通常不需要直接使用。
| 名稱 | 描述 | 範例 |
|---|---|---|
| `ACTIONS_CACHE_URL` | Actions 快取服務的 URL。 | `http://192.168.1.10:8088/` |
| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用於 OIDC 請求的令牌。僅在授予 `id-token: write` 時設定。 | `***` |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | 請求 OIDC 令牌的 URL。僅在授予 `id-token: write` 時設定。 | `https://gitea.example.com/api/actions/oidc/token?` |
| `ACTIONS_RESULTS_URL` | 儲存 Artifact 的 URL。 | `https://gitea.example.com` |
| `ACTIONS_RUNTIME_TOKEN` | Actions 管線 API 的驗證令牌。 | `***` |
| `ACTIONS_RUNTIME_URL` | Gitea Actions 管線 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` |
## 使用者定義的變量
您可以建立使用者、組織和儲存庫級別的變量。變量的級別取決於建立它的位置。當建立變量時,變量的名稱會被
轉換為大寫,在yaml文件中引用時需要使用大寫。
### 命名規則
## 命名規則
以下規則適用於變量名:
@@ -100,11 +20,11 @@ sidebar_position: 25
- 變量名稱在建立它們的級別上必須是唯一的。
- 變量名稱不能為 `CI`。
### 使用
## 使用
建立設定變量後,它們將自動填充到 `vars` 上下文中。您可以在工作流中使用類似 `${{ vars.VARIABLE_NAME }}` 這樣的表達式來使用它們。
### 優先級
## 優先級
如果同名變量存在於多個級別,則級別最低的變量優先。
儲存庫級別的變量總是比組織或者使用者級別的變量優先被選中。
@@ -4,6 +4,6 @@
"link": {
"type": "generated-index",
"slug": "/usage/projects",
"description": "使用專案看板規劃與追蹤工作"
"description": "規劃、追蹤並自動化儲存庫專案"
}
}
@@ -2,81 +2,113 @@
date: "2025-11-25T18:58:22Z"
slug: "project-workflows"
sidebar_position: 1
description: "透過事件驅動的篩選條件與動作,讓專案看板自動化。"
description: "以事件、篩選條件與動作組合,替儲存庫專案自動化重複工作。"
---
# 專案工作流程
專案工作流程可讓專案看板自動化。當專案中的問題或合併請求觸發事件時,該事件的每個已啟用工作流程都會檢查篩選條件並執行動作。工作流程在 Gitea 中執行,不需要 runner。
專案工作流程會在儲存庫專案看板上依據議題或拉取請求觸發的事件自動執行操作。此功能完全在 Gitea 內部運行,不需要外部 Runner 或 Webhook。
## 編輯工作流程
有權管理專案工作流程的使用者可以建立、編輯、複製、啟用或停用工作流程,詳見[權限](#權限)。
1. 開啟專案並選取 **Workflows**。
2. 在側邊欄選取事件。
3. 設定篩選條件與動作,然後選取 **Save**。若要變更現有工作流程,請先選取 **Edit**。
## 開啟工作流程編輯器
一個事件可以有多個工作流程。**Clone** 會複製選取的工作流程,方便您調整後用於其他項目。**Disable** 會暫停工作流程並保留設定。**Remove** 會刪除工作流程。
1. 進入儲存庫並開啟想要自動化的 **Projects** 看板。
2. 在看板頂端的選單中選擇 **Workflows**。
3. 點擊左側欄中的事件以編輯其工作流程。
4. 選擇事件、加入篩選條件、依序配置需要的動作後儲存。
## 事件
每個工作流程只屬於當前專案。如需在另一個專案套用相同邏輯,請在該專案重新建立或複製工作流程。
| 事件 | 執行時機 | 篩選條件 | 動作 |
| --- | --- | --- | --- |
| Item added to project | 項目加入專案或在專案中建立時 | Apply to、標籤 | Move to column、標籤、問題狀態 |
| Item removed from project | 項目從專案移除時 | Apply to、標籤 | 標籤、問題狀態 |
| Item reopened | 項目重新開啟時 | Apply to、標籤 | Move to column、標籤 |
| Item closed | 項目關閉時 | Apply to、標籤 | Move to column、標籤 |
| Item column changed | 項目移至另一欄時 | Apply to、欄、標籤 | 標籤、問題狀態 |
| Code changes requested | 正式審查者要求修改合併請求時 | 標籤 | Move to column、標籤 |
| Code review approved | 正式審查者核准合併請求時 | 標籤 | Move to column、標籤 |
| Pull request merged | 合併請求合併時 | 標籤 | Move to column、標籤 |
## 基本概念
- **事件(Event)**:定義何時評估工作流程,例如議題加入專案或卡片在欄位間移動。
- **篩選條件(Filter)**:可選條件,需符合後才會執行動作,例如標籤或欄位變化。
- **動作(Action)**:當事件與篩選條件成立時 Gitea 要執行的操作,例如新增標籤或移動卡片。
## 支援的事件
| 事件 | 觸發時機 |
| --- | --- |
| 關閉議題/拉取請求 | 該議題或拉取請求被關閉。 |
| 重新開啟議題/拉取請求 | 已關閉的項目被重新開啟。 |
| 加入專案 | 議題或拉取請求被加入此專案,包括在此專案中建立時。 |
| 從專案移除 | 項目被自專案中移除。 |
| 欄位變更 | 卡片從某欄移到另一欄。 |
| 被要求修改 | 與專案關聯的拉取請求收到修改要求。 |
| 稽核通過 | 稽核者批准該拉取請求。 |
| 拉取請求已合併 | 該拉取請求被合併。 |
每種事件都可以配置多個工作流程,讓相同觸發條件可以在不同情境下執行不同的自動化步驟。
## 篩選條件
未設定篩選條件的工作流程會對所有項目執行。
篩選條件可進一步限制事件是否需要執行。若未設定任何條件,事件發生時工作流程一律會跑。
- **Apply to**:問題、合併請求或兩者。
- **When moved from column**、**When moved to column**:項目離開或進入的欄。
- **Only if it has labels**:項目必須具有所有選取的標籤。
- **適用對象(Apply to)**:限制僅處理 `issues only`、`pull requests only` 或同時處理。
- **標籤(Labels)**:只有卡片已包含所選標籤之一時才觸發。
- **來源欄位(Move from column)**:只有卡片原先位於指定欄位時才觸發,常與「欄位變更」事件搭配。
- **目標欄位(Move to column)**:只有卡片移入特定欄位時才觸發。
可以同時組合多個篩選條件,例如「帶有 `needs-review` 標籤的拉取請求移入 “Review” 欄位」。
## 動作
工作流程至少需要一個動作。動作依下列順序執行:
工作流程會先移動卡片,再變更標籤,最後變更議題狀態。可用的動作包含:
1. **Move to column**:將項目移至某一欄。
2. **Add labels**、**Remove labels**:變更項目的標籤。
3. **Issue state**:關閉或重新開啟項目。工作流程不會重新開啟合併請求。
- **新增標籤(Add labels)**:為議題或拉取請求加上多個標籤。
- **移除標籤(Remove labels)**:刪除不再需要的標籤。
- **移動到欄位(Move to column)**:把卡片移到同一專案看板中的其他欄位。
- **議題狀態(Issue state)**:關閉或重新開啟相關議題。拉取請求只能被關閉。
工作流程所做的變更會在時間軸中顯示為「Project workflow」加上事件名稱,且不會觸發其他工作流程。專案已關閉或項目位於已封存的儲存庫時,工作流程不會執行。
透過組合多個動作,可以在單一工作流程裡同時完成移動卡片與更新標籤等步驟。
## 管理工作流程
### 啟用或停用
每個工作流程都有獨立開關。停用後即使事件被觸發也會被忽略,適合暫停自動化又不想刪除設定時使用。已關閉專案的工作流程也不會執行。
### 複製事件工作流程
按下 **Clone** 可以複製目前的工作流程(事件、篩選條件與動作都會被保留)。當你需要針對相同事件建立不同變體時,複製後調整即可快速建立新流程。
## 權限
任何具有專案讀取權限的使用者都能檢視其工作流程。管理工作流程需要專案的寫入權限,以及:
權限在管理工作流程時檢查,而非在工作流程執行時檢查。
- 儲存庫專案:該儲存庫的問題與合併請求的寫入權限。
- 組織專案:組織擁有者或網站管理員身分。
- 使用者專案:專案擁有者身分。
僅限公開儲存庫的存取權杖無法管理組織或使用者專案的工作流程。無論誰觸發事件,工作流程都會執行其動作。
- **檢視**專案的工作流程需要該專案的讀取權限。
- **建立、編輯、啟用、停用與刪除**工作流程需要該專案的寫入權限,以及對該專案可容納之所有項目的權限:儲存庫專案需要對該儲存庫的議題與拉取請求都擁有寫入權限,組織專案需要是組織擁有者或網站管理員,使用者專案需要是該使用者本人。僅限公開儲存庫的權杖無法管理組織或使用者專案的工作流程。
- **工作流程會在**開放專案中的項目發生對應事件時執行,前提是項目所在儲存庫未封存且屬於該專案的儲存庫或擁有者,與誰觸發了事件無關。
- **其動作直接套用,不再進行權限檢查**,包括為拉取請求新增標籤與關閉拉取請求。工作流程不會重新開啟拉取請求。
- 工作流程所做的變更在時間軸中顯示為由「專案工作流程」完成,並歸屬於觸發該事件的使用者,與 CODEOWNERS 發起的審查請求相同。這些變更不會觸發其他工作流程。
- 只有能讀取項目的使用者才能將其加入專案或移動其卡片,因此工作流程不會替使用者操作其無法查看的項目。
## API
透過儲存庫(`/repos/{owner}/{repo}/projects/{id}`)、組織(`/orgs/{org}/projects/{id}`)或已驗證使用者(`/user/projects/{id}`)的專案路由管理工作流程:
也可以透過 REST API 管理工作流程,路徑位於儲存庫(`/repos/{owner}/{repo}/projects/{id}`)、組織(`/orgs/{org}/projects/{id}`)或目前使用者(`/user/projects/{id}`)的專案路由下:
| 方法 | 路徑 | 用途 |
| --- | --- | --- |
| `GET` | `.../workflows` | 列出工作流程 |
| `GET` | `.../workflows` | 列出專案的工作流程 |
| `GET` | `.../workflows/{workflow_id}` | 取得工作流程 |
| `POST` | `.../workflows` | 建立工作流程 |
| `PATCH` | `.../workflows/{workflow_id}` | 編輯工作流程,未提供的欄位保持不變 |
| `DELETE` | `.../workflows/{workflow_id}` | 刪除工作流程 |
工作流程包含 `event`(`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`)、`enabled` 旗標、`filters`(`issue_type`、`source_column_id`、`target_column_id`、`label_ids`)與 `actions`(`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`)。每個事件僅接受[事件](#事件)中列出的篩選條件與動作。
工作流程包含 `event`(`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`)、`enabled` 開關、`filters`(`issue_type`、`source_column_id`、`target_column_id`、`label_ids`)以及 `actions`(`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`)。權限規則與介面操作相同,詳見[權限](#權限)。
## 範例
## 範例:自動分流新的錯誤回報
若要將新的錯誤回報送往分類處理,請為 **Item added to project** 建立工作流程:
以下設定能讓錯誤議題自動落在待處理區:
- **Apply to**:Issues only
- **Only if it has labels**:`bug`
- **Move to column**:Triage
- **Add labels**:`needs-triage`
1. **事件:** 加入專案(Added to project)。
2. **篩選條件:** 僅適用 `issues only`;標籤包含 `bug`。
3. **動作:**
- 新增標籤 → `needs-triage`。
- 移動到欄位 → “Needs Triage”。
- 議題狀態 → 保持開啟(如有需要也能強制重新開啟以確保可見)。
設定完成後,每當有新的錯誤議題加入此專案,就會立即獲得正確標籤並顯示在指定欄位,維護者能第一時間掌握待分流的項目。
從簡單規則著手,在單一專案驗證成效,再依團隊的重複性工作逐步擴大自動化邏輯。
@@ -8,7 +8,7 @@ aliases:
# 資料庫準備
在使用 Gitea 前,您需要準備一個資料庫。Gitea 支援 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(內置) 和 MSSQL(>= 2012 SP4)這幾種資料庫。本頁將指導您準備資料庫。本文件涵蓋 PostgreSQL、MySQL 和 MSSQL。如果您計劃使用 SQLite,則可以忽略本章內容。
在使用 Gitea 前,您需要準備一個資料庫。Gitea 支援 PostgreSQL(>= 12)、MySQL(>= 8.0)、MariaDB(>= 10.4)、SQLite(內置) 和 MSSQL(>= 2012 SP4)這幾種資料庫。本頁將指導您準備資料庫。由於 PostgreSQL 和 MySQL 在生產環境中被廣泛使用,因此本文件將僅涵蓋這兩種資料庫。如果您計劃使用 SQLite,則可以忽略本章內容。
如果您使用不受支援的資料庫版本,請通過 [聯繫我們](/help/support) 以獲取有關我們的擴展支援的資訊。我們可以為舊資料庫提供測試和支援,並將這些修復整合到 Gitea 程式碼庫中。
@@ -168,28 +168,6 @@ aliases:
您應該會被提示輸入資料庫使用者的密碼,並連接到資料庫。
## MSSQL
1. 以管理員身份建立登入名稱、使用大小寫敏感排序規則的資料庫及其使用者。請將密碼 `'gitea'` 替換為安全的密碼:
```sql
CREATE LOGIN gitea WITH PASSWORD = 'gitea';
CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
GO
USE giteadb;
CREATE USER gitea FOR LOGIN gitea;
ALTER ROLE db_owner ADD MEMBER gitea;
GO
```
升級會更改資料庫結構,因此該使用者需要 `db_owner`,或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用後者時,還需以管理員身份執行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
2. 在您的 Gitea 伺服器上,測試與資料庫的連接:
```sh
sqlcmd -S 203.0.113.3 -U gitea -d giteadb
```
## 使用 TLS 進行資料庫連接
如果 Gitea 和您的資料庫實例之間的通信是通過私有網路進行的,或者如果 Gitea 和資料庫運行在同一臺伺服器上,那麼可以省略本節,因為 Gitea 和資料庫實例之間的安全性不會受到嚴重威脅。但是,如果資料庫實例位於公共網路上,請使用 TLS 對資料庫連接進行加密,以防止第三方攔截流量資料。
@@ -21,7 +21,15 @@ Gitea Actions 旨在與 GitHub Actions 相容,差異如下。
`uses:` 接受以下前綴:
- `self:` 參照您自己的 Gitea 實例,例如 `uses: self:owner/repo@v1` 或 `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
- `builtin:` 執行 Gitea Runner 內建的 Action,無需下載,也不依賴 Node.js,例如 `uses: builtin:checkout`
- `builtin:` 執行 Gitea Runner 內建的 Action,無需下載,Job 映像檔中也不需要 Node,例如 `uses: builtin:checkout`
`builtin:checkout` 支援 `actions/checkout` 的 `repository`、`ref`、`token`、`path` 和 `fetch-depth` 輸入,預設值相同,其他輸入會使步驟失敗。
<a id="workflow-relative-actions"></a>
### 相對於工作流的 Actions
`$/` 參照工作流(或外層複合 Action)所在的儲存庫與提交,例如 `uses: $/.gitea/actions/build`。
與 `./` 不同,它不需要事先簽出程式碼。
### 使用Go編寫Actions
@@ -87,7 +95,7 @@ Gitea Actions 旨在與 GitHub Actions 相容,差異如下。
未指定主機的 Actions,例如 `uses: actions/checkout@v4`,會從 `https://github.com` 下載,若 `[actions].DEFAULT_ACTIONS_URL` 為 `self`,則從您自己的實例下載。
請參閱[設定速查表](../../administration/config-cheat-sheet.md#actions-actions)。
其他來源請參閱 [Action URL絕對路徑](#absolute-action-urls)和[Action 前綴](#action-prefixes)。
其他來源請參閱 [Action URL絕對路徑](#absolute-action-urls)、[Action 前綴](#action-prefixes)和[相對於工作流的 Actions](#workflow-relative-actions)。
### 上下文可用性
+1 -1
View File
@@ -13,5 +13,5 @@
"engines": {
"node": ">=22"
},
"packageManager": "[email protected]7.0"
"packageManager": "[email protected]3.0"
}
+6 -46
View File
@@ -8,7 +8,7 @@
export type LocaleId = 'en-us' | 'zh-cn' | 'zh-tw';
export type ProductId = 'docs' | 'api' | 'runner' | 'cli' | 'enterprise';
export type ProductId = 'docs' | 'api' | 'runner' | 'enterprise';
/** Values substituted for `@name@` placeholders in the markdown sources. */
export interface VersionVariables {
@@ -89,11 +89,11 @@ const variables: Record<string, VersionVariables> = {
goVersion: '1.27',
minGoVersion: '1.27',
minNodeVersion: '22',
version: '28.3.0',
sourceVersion: 'v28.3.0',
version: '28.2.0',
sourceVersion: 'v28.2.0',
sourceBranch: 'release/v28',
dockerVersion: '28.3.0',
displayVersion: '28.3.0',
dockerVersion: '28.2.0',
displayVersion: '28.2.0',
},
'1.27': {
goVersion: '1.26',
@@ -246,40 +246,6 @@ const runnerProduct: ProductDef = {
],
};
/**
* gt, the Gitea CLI: laid out like the runner. Until the first series is listed
* here the develop docs are served at the product root, without the unreleased
* banner, since there is no release to point to. Listing a series moves them to
* `/cli/develop/`.
*/
const cliSeries: { id: string; latestRelease: string }[] = [];
const cliProduct: ProductDef = {
id: 'cli',
label: 'CLI',
base: 'cli',
locales: ['en-us'],
versions: [
{
id: 'develop',
label: 'develop',
sources: { 'en-us': 'cli-docs' },
...(cliSeries.length > 0
? { path: 'develop', banner: 'unreleased' as const }
: { path: '', latest: true }),
},
...cliSeries.map(
({ id, latestRelease }, index): VersionDef => ({
id,
label: latestRelease,
path: index === 0 ? '' : id,
latest: index === 0,
sources: { 'en-us': `cli-docs_versioned_docs/version-${id}` },
}),
),
],
};
/** API reference, rendered from the swagger documents by starlight-openapi. */
const apiProduct: ProductDef = {
id: 'api',
@@ -335,13 +301,7 @@ const enterpriseProduct: ProductDef = {
externalBaseUrl: 'https://docs.gitea.com/enterprise',
};
export const products: ProductDef[] = [
docsProduct,
apiProduct,
runnerProduct,
cliProduct,
enterpriseProduct,
];
export const products: ProductDef[] = [docsProduct, apiProduct, runnerProduct, enterpriseProduct];
export function getProduct(id: ProductId): ProductDef {
const product = products.find((candidate) => candidate.id === id);
+3 -3
View File
@@ -1,7 +1,7 @@
/**
* Builds one sidebar per (product, version, language) out of the loaded pages,
* deriving it from `_category_.json` and from the
* handwritten sidebar files of the runner and the cli docs.
* handwritten sidebar files of the runner docs.
*/
import { defaultLocale } from './products';
@@ -44,7 +44,7 @@ export interface SidebarGroup {
export type SidebarEntry = SidebarLink | SidebarGroup;
/** A hand written sidebar file, as used by the runner and the cli docs. */
/** A hand written sidebar file, as used by the runner docs. */
export type SidebarSourceItem =
| string
| { type: 'doc'; id: string; label?: string }
@@ -148,7 +148,7 @@ function treeOf(pages: SidebarPage[]): Tree {
return { build, label };
}
/** Sidebar described by a hand written sidebar file, used by the runner and the cli docs. */
/** Sidebar described by a hand written sidebar file, used by the runner docs. */
function fromSidebarSource(
items: SidebarSourceItem[],
pages: SidebarPage[],
+309 -638
View File
File diff suppressed because it is too large. Load diff
+1 -1
View File
@@ -31,7 +31,7 @@ The shell options of `run:` steps do not apply to hooks. Set `pipefail` and othe
## Environment and output
A hook receives the job's environment, including `runner.envs`, the workflow's `env:` and the `GITHUB_*` and `GITEA_*` variables. The runner includes hook output in the job log and masks secrets as it does for step output.
A hook receives the job's environment, including `runner.envs`, the workflow's `env:` and the `GITHUB_*` variables. The runner includes hook output in the job log and masks secrets as it does for step output.
Use `$GITHUB_ENV` and `$GITHUB_PATH` to pass environment variables and paths to later steps. Mask values with `::add-mask::`:
+1
View File
@@ -23,6 +23,7 @@ Jobs need these tools wherever steps run, in the job image or on the host:
- `bash` or `sh` for `run` steps, or `pwsh` or `powershell` on Windows.
- `node` for JavaScript actions and `hashFiles()`.
- `git` 2.34.1 or later for [`builtin:checkout`](jobs.md#built-in-checkout), plus `git-lfs` for its `lfs` input and `ssh` for its `ssh-key` input.
## Where jobs run
+11 -34
View File
@@ -84,16 +84,7 @@ For jobs in containers, give the `gitea-runner` user access to the Docker daemon
## launchd (macOS)
On macOS, run the runner in the login session of the user that jobs should run as. Jobs then have that user's login keychain and the GUI.
Register the runner as that user, with a [host label](../labels.md) so that jobs run on the Mac itself:
```bash
mkdir ~/gitea-runner && cd ~/gitea-runner
gitea-runner register --instance https://gitea.example.com --token <token> --labels macos-latest:host
```
Replace `/Users/gitea-runner` with the user's home directory, then save this file as `~/Library/LaunchAgents/com.gitea.runner.plist`:
Adjust the paths and user for your setup, then save this file as `/Library/LaunchDaemons/com.gitea.runner.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -106,16 +97,22 @@ Replace `/Users/gitea-runner` with the user's home directory, then save this fil
<array>
<string>/usr/local/bin/gitea-runner</string>
<string>daemon</string>
<string>--config</string>
<string>/etc/gitea-runner/config.yaml</string>
</array>
<key>UserName</key>
<string>_gitea-runner</string>
<key>WorkingDirectory</key>
<string>/Users/gitea-runner/gitea-runner</string>
<string>/var/lib/gitea-runner</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME</key>
<string>/var/lib/gitea-runner</string>
</dict>
<key>StandardErrorPath</key>
<string>/Users/gitea-runner/gitea-runner/runner.log</string>
<string>/var/lib/gitea-runner/runner.log</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
@@ -124,30 +121,10 @@ Replace `/Users/gitea-runner` with the user's home directory, then save this fil
</plist>
```
Start the runner. From now on, it also starts whenever the user logs in:
```bash
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.gitea.runner.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.gitea.runner.plist
```
Enable automatic login for the user in System Settings, so that the runner starts after a restart too. macOS does not offer automatic login while FileVault is on.
The runner does not get the environment of your shell. Set what jobs need, such as [proxy settings](../proxy.md), in `EnvironmentVariables`.
### Local network access
macOS blocks a runner that was started this way from other hosts on the Mac's own subnet, such as the Gitea instance or a shared cache server. The runner then logs `no route to host`. Commands run in Terminal or over SSH are not blocked, so registering works even when the running runner cannot connect. See [local network privacy](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy).
macOS asks on the Mac's screen whether to allow the access. To allow it without that prompt, exempt the subnet on macOS 15.5 or later and restart the Mac. On Wi-Fi, the key is `AllowedWiFiLocalNetworkAddresses`:
```bash
sudo defaults write com.apple.network.local-network AllowedEthernetLocalNetworkAddresses -array "192.168.1.0/24"
```
### Git credentials
Git on macOS saves credentials from remote URLs to the keychain, which can stop a job at a dialog that nobody answers. To turn that off, set `GIT_CONFIG_NOSYSTEM` to `1` in `EnvironmentVariables`.
## Windows
Run `gitea-runner daemon` with a service wrapper such as [WinSW](https://github.com/winsw/winsw). The runner has no service installer of its own.
+4
View File
@@ -68,6 +68,10 @@ Setup actions such as `actions/setup-go` install tools in `/opt/hostedtoolcache`
With `none`, include tools in the job image at `/opt/hostedtoolcache/<tool>/<version>/<arch>`. Place an empty `<arch>.complete` file next to the directory. The `-full` variant of the [runner images](https://gitea.com/gitea/runner-images) includes its tools this way.
## Built-in checkout
`uses: builtin:checkout` checks out the repository like `actions/checkout`. It does not download an action or require Node in the job image. It runs `git` in the job. See [Requirements](index.md#requirements) and the inputs listed in [builtin-actions.md](https://gitea.com/gitea/runner/src/branch/main/docs/builtin-actions.md).
## Secrets
The runner masks secrets and `::add-mask::` values in job logs, job summaries, and the names of containers it creates. The runner does not send job outputs that contain a secret. A `needs.<job>.outputs.<name>` expression that reads such an output is empty.
+9 -9
View File
@@ -20,13 +20,13 @@ Usage:
gitea-runner [command]
Available Commands:
bug-report Print information useful when filing a bug report
cache-server Start a cache server for the cache action
config Generate, read and edit config files
daemon Run as a runner daemon
exec Run workflow locally.
help Help about any command
register Register a runner to the server
bug-report Print information useful when filing a bug report
cache-server Start a cache server for the cache action
config Generate, read and edit config files
daemon Run as a runner daemon
exec Run workflow locally.
help Help about any command
register Register a runner to the server
Flags:
-c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
@@ -91,8 +91,8 @@ Usage:
Flags:
--artifact-server-addr string Defines the address where the artifact server listens
--artifact-server-path string Defines the path where the artifact server stores uploads and retrieves downloads from, outside the workspace that jobs copy. Defaults to a temporary directory removed on exit.
--artifact-server-port string Defines the port where the artifact server listens (default "34567")
--artifact-server-path string Defines the path where the artifact server stores uploads and retrieves downloads from. If not specified the artifact server will not start. (default ".")
--artifact-server-port string Defines the port where the artifact server listens (will only bind to localhost). (default "34567")
--container-architecture string Architecture which should be used to run containers, e.g.: linux/amd64. If not specified, will use host default architecture. Requires Docker server API Version 1.41+. Ignored on earlier Docker server platforms.
--container-cap-add stringArray kernel capabilities to add to the workflow containers (e.g. --container-cap-add SYS_PTRACE)
--container-cap-drop stringArray kernel capabilities to remove from the workflow containers (e.g. --container-cap-drop SYS_PTRACE)
Loaded 50 of 73 files, more files were not shown because too many files have changed in this diff. Show more