nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-05 17:45:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into docs-artifact-previews

Browse Source
This commit is contained in:
bircni committed 2026-09-26 23:28:32 +02:00
2 parents a90b007dd7 470f582e97
commit d4d211273a
81 files changed
+2146 -1982
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.gitea/workflows/test.yaml
+1 -1
View File
@@ -94,7 +94,7 @@ jobs:
body="$(printf '%s Preview: %s\n' "$marker" "$PREVIEW_URL")"
fi
jq -n --arg body "$body" '{body: $body}' > patch.json
printf '%s' "$body" | jq -Rs '{body: .}' > patch.json
curl --silent --show-error --fail --output /dev/null \
-X PATCH "$api" \
-H "Authorization: token $DEPLOY_TOKEN" \
docs/administration/audit-logging.md
+153
View File
@@ -0,0 +1,153 @@
---
date: "2026-09-12T00:00:00+00:00"
slug: "audit-logging"
sidebar_position: 41
aliases:
- /en-us/audit-logging
---
# Audit Logging
Gitea can record security-relevant events as structured audit records: each
event has an `action`, `actor`, `scope`, `origin`, `message` and a JSON
`metadata` blob. Recording is **off by default** and does not change request
behavior when it is disabled.
This is separate from the application, router and access logs described in
[Logging Configuration](logging-config.md). Those logs are for operations and
debugging. The audit log is a durable trail of who changed what.
## Enable recording
Set `[audit].RECORD_OUTPUT` to `database` in `app.ini` and restart Gitea:
```ini
[audit]
RECORD_OUTPUT = database
RETENTION_DAYS = 30
```
Invalid values of `RECORD_OUTPUT` fall back to `disabled`. See the
[configuration cheat sheet](config-cheat-sheet.md#audit-audit) for every option.
With Docker, the same settings can be applied as
`GITEA__audit__RECORD_OUTPUT=database` and `GITEA__audit__RETENTION_DAYS=30`
before Gitea writes them into `app.ini`.
## View events
The Audit Log pages are always available and still list any events that were
stored earlier. When recording is disabled, the site administration page also
shows a warning.
| Audience | Location | Events shown |
| --- | --- | --- |
| Site administrators | Site administration → Monitoring → Audit Log (`/-/admin/monitor/audit_logs`) | Every event |
| Signed-in users | User settings → Audit Log (`/user/settings/audit_logs`) | Events scoped to that user |
| Organization owners | Organization settings → Audit Log (`/<org>/settings/audit_logs`) | Events scoped to that organization |
| Repository administrators | Repository settings → Audit Log (`/<owner>/<repo>/settings/audit_logs`) | Events scoped to that repository |
Each listing can be filtered by actor (username), action and origin, and sorted
by timestamp. The actor filter does not match the
[system actors](#actors-and-origins). Action filters accept an exact action or
a family prefix such as `user:impersonation` or `repository:webhook`.
Site administrators can download the current filtered result as JSONL
(newline-delimited JSON) from **Export JSONL**. The file name is
`gitea-audit-log-<timestamp>.jsonl`.
## Event shape
A recorded event contains:
- **Action**: a stable, colon-separated identifier such as `repository:archive`
or `user:accesstoken:add`.
- **Actor**: the user who performed the action. Actions taken while impersonating
a user record both the impersonator and the impersonated user.
- **Actor credential**: when the request authenticated with a named credential,
the event stores its kind and id, never the secret. Typical values:
`access-token:<id>`, `oauth2-grant:<id>`, `gitea-actions:<task id>`,
`deploy-key:<key id>`.
- **Scope**: the affected unit — `user`, `organization`, `repository` or
`system` (instance-wide).
- **Origin**: how the action was initiated — `ui`, `api`, `cli` or `system`.
- **Message**: a human-readable sentence rendered from a per-action template.
- **Metadata**: extra fields that fill the message template (token name, new
visibility, and so on). Secrets and token values are not stored.
- **IP address**: the client address of the request, when one exists. Events
triggered by a git push record the SSH client address for SSH pushes and
`127.0.0.1` for HTTP pushes.
- **Timestamp**: when the event was recorded.
An exported JSONL line looks like:
```json
{"action":"repository:archive","actor":{"type":"user","id":1,"name":"alice"},"scope":{"type":"repository","id":42,"name":"org/repo"},"message":"Archived repository org/repo.","time":"2026-09-12T11:00:00Z","ip_address":"203.0.113.10","origin":"ui"}
```
The `system:startup` message is kept stable across Gitea versions so operators
can parse it: `System started [Gitea {version}]`.
## Actors and origins
Most web and API requests pick up the signed-in user automatically.
Other entry points record a system actor:
- `(gitea-cli)` for `gitea admin` commands and the `system:startup` and
`system:shutdown` events
- `(gitea-auth-source)` for authentication-source syncs and for users an
authentication source creates or updates at sign-in
- `gitea-actions` for Gitea Actions tasks
- `(deploy-key)` for pushes with a deploy key
- `(Cron)` for scheduled cron tasks
- `Unknown` when no actor can be resolved
Events of the `(gitea-cli)` actor use origin `cli`. Cron tasks, git hooks and
other background work use origin `system`.
## What is recorded
Events cover security-relevant changes, grouped by action family:
- **User**: create and delete, admin, restricted and active status, name,
password and password reset requests, visibility, emails, authentication
source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2
applications and grants, SSH/GPG/principal keys, secrets, webhooks,
impersonation, failed two-factor authentication
- **Organization**: create and delete, name, visibility, members, teams,
OAuth2 applications, secrets, webhooks
- **Repository**: create, fork, archive, delete, rename, visibility, transfer,
mirrors, signing verification, collaborators and teams, default branch,
branch and tag protection, deploy keys, webhooks, secrets
- **Issues and pull requests**: create, delete, comments and merges
- **Projects and wiki pages**: create, update and delete
- **Actions**: enable, disable and dispatch a workflow
- **System**: startup and shutdown, instance-wide webhooks, authentication
sources, instance-wide OAuth2 applications
Recording never fails the request that triggered it. A write error is logged
and the original operation continues.
## What is not recorded
- Read-only access such as browsing, clone, fetch or API GET requests
- Logins, successful or failed, other than failed two-factor authentication
(use the [access log](logging-config.md) and
[Fail2ban Setup](fail2ban-setup.md) for authentication traffic)
- Edits to issues and pull requests
- Token or secret values
- Which SSH key a real user pushed with (deploy keys are named; ordinary SSH
user pushes are not)
## Retention
`RETENTION_DAYS` (default **30**) is the age after which recorded events are
eligible for deletion. Set it to `0` to keep events forever.
Cleanup is performed by the `cron.delete_old_audit_events` task (`SCHEDULE`
defaults to `@every 24h`, `OLDER_THAN` defaults to `[audit].RETENTION_DAYS`).
The task is registered only while `RECORD_OUTPUT` records events **and**
`RETENTION_DAYS` is greater than `0`. Turning recording off therefore also
stops pruning; existing rows stay until you delete them or turn recording back
on.
docs/administration/config-cheat-sheet.md
+37 -28
View File
@@ -348,8 +348,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `PROXY_PROTOCOL_TLS_BRIDGING`: **false**: When protocol is https, expect PROXY protocol headers after TLS negotiation.
- `PROXY_PROTOCOL_HEADER_TIMEOUT`: **5s**: Timeout to wait for PROXY protocol header (set to 0 to have no timeout)
- `PROXY_PROTOCOL_ACCEPT_UNKNOWN`: **false**: Accept PROXY protocol headers with Unknown type.
- `DOMAIN`: **localhost**: Domain name of this server.
- `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
- `ROOT_URL`: **`{PROTOCOL}://localhost:{HTTP_PORT}/`**:
Overwrite the automatically generated public URL.
This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
- `PUBLIC_URL_DETECTION`: **`auto`**: Controls how to generate the public URL. Most instances should use the "auto" behavior,
@@ -656,6 +655,11 @@ And the following unique queues:
- CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
- Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
## Audit (`audit`)
- `RECORD_OUTPUT`: **disabled**: Where security-relevant events are recorded. `disabled` records nothing. `database` writes events to the `audit_event` table and shows them in the admin, organization, repository and user settings. Invalid values fall back to `disabled`. See [Audit Logging](audit-logging.md).
- `RETENTION_DAYS`: **30**: Days to keep recorded events. `0` keeps them forever. Pruning is done by `cron.delete_old_audit_events`. That task is only registered while `RECORD_OUTPUT` records events and `RETENTION_DAYS` is greater than `0`.
## Camo (`camo`)
- `ENABLED`: **false**: Enable media proxy, we support images only at the moment.
@@ -665,8 +669,8 @@ And the following unique queues:
## OpenID (`openid`)
- `ENABLE_OPENID_SIGNIN`: **true**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **false**: Allow registering via OpenID.
- `WHITELISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
OpenID URI's to permit.
- `BLACKLISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
@@ -1047,7 +1051,7 @@ Release attachment has its own config options in `[repository.release]` section.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1056,7 +1060,7 @@ Release attachment has its own config options in `[repository.release]` section.
- `ENABLED`: **true**: Enable running repository health check task periodically.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `RUN_AT_START`: **false**: Run repository health check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1065,12 +1069,13 @@ Release attachment has its own config options in `[repository.release]` section.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
- `ENABLED`: **true**: Enable running repository statistics check task periodically.
- `RUN_AT_START`: **true**: Run repository statistics check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
- `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1090,7 +1095,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
- `ENABLED`: **true**: Enable update migration poster id job.
- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
#### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1099,7 +1104,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable synchronize external user data job
- `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1107,12 +1112,14 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable cleanup expired actions assets job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Cron syntax for the job.
#### Cron - Delete Old Action Runs (`cron.cleanup_action_runs`)
- `ENABLED`: **true**: Enable the job deleting action runs older than `RUN_RETENTION_DAYS`. Deletes nothing while that is 0.
- `RUN_AT_START`: **false**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for the job.
#### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1198,11 +1205,21 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
#### Cron - Delete old audit events (`cron.delete_old_audit_events`)
Deletes audit events older than the retention period. The task is only registered when `[audit].RECORD_OUTPUT` records events and `[audit].RETENTION_DAYS` is greater than `0`. See [Audit Logging](audit-logging.md).
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **720h**: any audit event older than this expression will be deleted from the database. Defaults to `[audit].RETENTION_DAYS`.
#### Cron - Check for new Gitea versions (`cron.update_checker`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1210,7 +1227,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1218,6 +1235,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
@@ -1230,35 +1248,35 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@annually**: Cron syntax to set how often to rebuild
#### Cron - Stop running tasks which haven't been updated for a long time (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 5m**: Cron syntax to set how often tasks to run the check
#### Cron - Stop running tasks which have running status and continuous updates but don't end for a long time (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 30m**: Cron syntax to set how often to run the check.
#### Cron - Cancel jobs which haven't been picked up for a long time (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 6h**: Cron syntax to set how often to run the check.
#### Cron - Start cron based actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 1m**: Cron syntax to set how often to schedule tasks
## Git (`git`)
@@ -1685,18 +1703,9 @@ PROXY_HOSTS = *.github.com
- `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
- `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
`DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
And it can be changed to `self` to make it `root_url_of_your_gitea/actions/checkout@v4`.
Please note that using `self` is not recommended for most cases, as it could make names globally ambiguous.
Additionally, it requires you to mirror all the actions you need to your Gitea instance, which may not be worth it.
Therefore, please use `self` only if you understand what you are doing.
In earlier versions (`<= 1.19`), `DEFAULT_ACTIONS_URL` could be set to any custom URLs like `https://gitea.com` or `http://your-git-server,https://gitea.com`, and the default value was `https://gitea.com`.
However, later updates removed those options, and now the only options are `github` and `self`, with the default value being `github`.
However, if you want to use actions from other git server, you can use a complete URL in `uses` field, it's supported by Gitea (but not GitHub).
Like `uses: https://gitea.com/actions/checkout@v4` or `uses: http://your-git-server/actions/checkout@v4`.
`DEFAULT_ACTIONS_URL` sets where runners download actions without a host.
With `github`, `uses: actions/checkout@v4` resolves to `https://github.com/actions/checkout@v4`, with `self` to `<ROOT_URL>/actions/checkout@v4`.
`self` requires mirroring every action you use to your instance, so prefer naming the host per action instead: `uses: self:owner/repo@ref` for your instance, or a full URL like `uses: https://gitea.com/actions/checkout@v4` for any other host.
## Other (`other`)
docs/administration/email-setup.md
+15
View File
@@ -86,6 +86,21 @@ PROTOCOL = smtps
Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
account. You won't be able to use your Google account password directly.
An app password is the only option: Google
[turned off access for apps that sign in with a password alone](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html)
in 2024 and asks applications to use OAuth instead, which Gitea's mailer does
not implement — it authenticates with `CRAM-MD5`, `PLAIN` or `LOGIN`.
Two things to keep in mind:
- app passwords require 2-step verification on the account, and a Google
Workspace administrator can switch them off for the whole domain. If they are
not available, send through the
[Workspace SMTP relay service](https://support.google.com/a/answer/2956491)
or through another mail provider.
- port `587` works as well, with `SMTP_PORT = 587` and
`PROTOCOL = smtp+starttls`.
### ProtonMail
This feature is currently only available for select Proton for Business customers and those with Visionary and Family plans with custom domain addresses. See [ProtonMail's SMTP documentation](https://proton.me/support/smtp-submission) for more information. This limitation can be circumvented by using the ProtonMail Bridge application.
docs/administration/git-lfs-support.md
+21
View File
@@ -41,3 +41,24 @@ client that causes SSH transfers to hang: https://github.com/git-lfs/git-lfs/pul
This can be worked around on all the client machines by setting the git config:
`git config --global lfs.ssh.automultiplex false`
:::
# Changing LFS files through the API
The [contents API](https://docs.gitea.com/api/operations/repo-change-files/)
works on LFS tracked files as well: send the file content as usual and Gitea
stores it as an LFS object and commits a pointer file, as long as the path is
matched by a `filter=lfs` rule in `.gitattributes`.
What is easy to get wrong is the `sha` of the file being changed, which
`PUT`/`DELETE /repos/{owner}/{repo}/contents/{filepath}` and
`POST /repos/{owner}/{repo}/contents` require for an existing file. Gitea
compares it with the ID of the blob the commit has at that path, and for an LFS
tracked file that blob is the **pointer file**, not the content:
- use the `sha` returned by
[`GET /repos/{owner}/{repo}/contents/{filepath}`](https://docs.gitea.com/api/operations/repo-get-contents/)
- do not use `lfs_oid` from the same response, which identifies the LFS object,
and do not use a checksum of the file itself
Sending anything else fails with `sha does not match`, even though the request
looks correct.
docs/administration/logging-config.md
+2
View File
@@ -16,6 +16,8 @@ The logging configuration of Gitea mainly consists of 3 types of components:
There is a fully functional log output by default, so it is not necessary to define one.
Security-relevant events (repository transfers, token changes, impersonation, and similar) are recorded separately. See [Audit Logging](audit-logging.md).
## Collecting Logs for Help
To collect logs for help and issue report, see [Support Options](help/support.md).
docs/index.md
+1 -1
View File
@@ -43,7 +43,7 @@ You can try it out using [the online demo](https://demo.gitea.com).
- **Security**
Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, and more to ensure the security of code and data.
Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, [audit logging](administration/audit-logging.md), and more to ensure the security of code and data.
- **Code Review**
docs/installation/comparison.md
+1
View File
@@ -34,6 +34,7 @@ _Symbols used in table:_
| Telemetry | **✘** | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Third-party render tool support | ✓ | ✘ | ✘ | ✘ | ✓ | ✘ | ✘ |
| WebAuthn (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ |
| Audit log | ✓ | ✓ | ⁄ | ✓ | ✓ | ? | ? |
| Extensive API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Built-in Package/Container Registry | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ |
| Sync commits to an external repo (push mirror) | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ |
docs/installation/with-docker-rootless.md
+1 -1
View File
@@ -66,7 +66,7 @@ server-1 | 2026-03-11T12:57:50.796198843Z /var/lib/gitea/git is not writable
server-1 | 2026-03-11T12:57:50.796235667Z docker setup failed
```
For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`)
For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:main-nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly-rootless`)
## Named volumes
docs/installation/with-docker.md
+1 -1
View File
@@ -30,7 +30,7 @@ image as a service. Since there is no database available, one can be initialized
Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
If you don't give the volume correct permissions, the container may not start.
For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`)
For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:main-nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly`)
```yaml
networks:
docs/installation/with-podman-quadlet.md
+166
View File
@@ -0,0 +1,166 @@
---
date: "2026-09-03T20:00:00+02:00"
slug: "install-with-podman-quadlet"
sidebar_position: 65
aliases:
- /en-us/install-with-podman-quadlet
---
# Installation with Podman Quadlet
Similarly to [Docker](with-docker.md), [Podman](https://podman.io/) can be used to deploy Gitea.
This reference setup guides users through the setup based on Podman Quadlet.
Podman Quadlet is the native integration of Podman through systemd.
To learn more about Podman Quadlet, see [systemd units using Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
This setup installs the quadlets in `~/.config/containers/systemd/`, the directory for rootless quadlets, and uses the rootless images.
If you install them in a rootful directory such as `/etc/containers/systemd/`, use the rootful images instead.
## Basics
Since Podman v6.0 a single `gitea.quadlets` file can hold multiple quadlets separated by the `---` delimiter.
Paste the following content into a file named `gitea.quadlets`
```ini
# FileName=gitea-data
[Volume]
VolumeName=gitea-data
---
# FileName=gitea-config
[Volume]
VolumeName=gitea-config
---
# FileName=gitea
[Container]
PublishPort=2222:2222
PublishPort=3000:3000
Image=docker.gitea.com/gitea:@dockerVersion@-rootless
ContainerName=gitea
Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
[Service]
Restart=always
[Install]
# Start with the user session
WantedBy=default.target
```
You can run the installation command
```sh
$ podman quadlet install ./gitea.quadlets --application=gitea
/home/user/.config/containers/systemd/gitea/gitea-data.volume
/home/user/.config/containers/systemd/gitea/gitea-config.volume
/home/user/.config/containers/systemd/gitea/gitea.container
```
The `--application=gitea` flag allows us to tell podman to group the quadlets together, this can help for managing and organizing the quadlets files.
You can validate the quadlets are properly installed by looking at the list command
```sh
$ podman quadlet list
NAME UNIT NAME PATH ON DISK STATUS APPLICATION POD
gitea-config.volume gitea-config-volume.service /home/user/.config/containers/systemd/gitea/gitea-config.volume active/exited gitea
gitea-data.volume gitea-data-volume.service /home/user/.config/containers/systemd/gitea/gitea-data.volume active/exited gitea
gitea.container gitea.service /home/user/.config/containers/systemd/gitea/gitea.container failed/failed gitea
```
You can start the application by running `systemctl --user start gitea` command.
`WantedBy=default.target` starts the service when the user session starts.
Rootless user services do not run without a session, so to start Gitea at boot, enable lingering for the user with `loginctl enable-linger $USER`.
## Databases
### PostgreSQL database
To start Gitea in combination with a PostgreSQL database, apply these changes to the
`gitea.quadlets` file created above.
To start Gitea with a database, we need to create a network, so the database and Gitea container can communicate.
```diff
# FileName=gitea-data
[Volume]
VolumeName=gitea-data
---
# FileName=gitea-config
[Volume]
VolumeName=gitea-config
---
+ # FileName=gitea-postgres-data
+ [Volume]
+ VolumeName=gitea-postgres-data
+ ---
+ # FileName=gitea
+ [Network]
+ NetworkName=gitea
+ ---
+ # FileName=gitea-postgres
+ [Container]
+ Image=docker.io/library/postgres:18
+ ContainerName=gitea-postgres
+ Network=gitea.network
+ Mount=type=volume,src=gitea-postgres-data.volume,destination=/var/lib/postgresql
+ Environment=POSTGRES_USER=gitea
+ Environment=POSTGRES_PASSWORD=gitea
+ Environment=POSTGRES_DB=gitea
+
+ [Service]
+ Restart=always
+
+ [Install]
+ # Start with the user session
+ WantedBy=default.target
+ ---
# FileName=gitea
+ [Unit]
+ Requires=gitea-postgres.service
+ After=gitea-postgres.service
+
[Container]
PublishPort=2222:2222
PublishPort=3000:3000
Image=docker.gitea.com/gitea:@dockerVersion@-rootless
ContainerName=gitea
Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
+ Network=gitea.network
+ Environment=GITEA__database__DB_TYPE=postgres
+ Environment=GITEA__database__HOST=gitea-postgres:5432
+ Environment=GITEA__database__NAME=gitea
+ Environment=GITEA__database__USER=gitea
+ Environment=GITEA__database__PASSWD=gitea
[Service]
Restart=always
[Install]
# Start with the user session
WantedBy=default.target
```
## Logs
As systemd manages the container we can use `journalctl` to access the logs
```sh
$ journalctl --user --follow --unit=gitea.service
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:263:runWeb() [I] Starting Gitea on PID: 2
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:115:showWebStartupMessage() [I] Gitea version: 1.27.3 built with go1.26.7-X:jsonv2 : bindata, timetzdata,
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:116:showWebStartupMessage() [I] * RunMode: prod
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:117:showWebStartupMessage() [I] * AppPath: /usr/local/bin/gitea
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:118:showWebStartupMessage() [I] * WorkPath: /var/lib/gitea
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:119:showWebStartupMessage() [I] * CustomPath: /var/lib/gitea/custom
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:120:showWebStartupMessage() [I] * ConfigFile: /etc/gitea/app.ini
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:121:showWebStartupMessage() [I] Prepare to run install page
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:329:listen() [I] Listen: http://0.0.0.0:3000
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:333:listen() [I] AppURL(ROOT_URL): http://localhost:3000/
gitea[5967]: 2026/09/03 14:50:42 modules/graceful/server.go:52:NewServer() [I] Starting new Web server: tcp:0.0.0.0:3000 on PID: 2
```
docs/usage/actions/comparison.md
+32 -42
View File
@@ -6,104 +6,94 @@ sidebar_position: 120
# Compared to GitHub Actions
Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them.
Gitea Actions is designed to be compatible with GitHub Actions, with the differences below.
## Additional features
### Absolute action URLs
Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository.
Like `uses: https://github.com/actions/checkout@v4` or `uses: http://your_gitea.com/owner/repo@branch`.
`uses:` accepts an absolute URL to any git host, e.g. `uses: https://gitea.com/actions/checkout@v4`.
### Action prefixes
`uses:` accepts these prefixes:
- `self:` references your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
- `builtin:` runs an action built into Gitea Runner, which needs no download and no Node in the job image, e.g. `uses: builtin:checkout`
`builtin:checkout` accepts the `repository`, `ref`, `token`, `path` and `fetch-depth` inputs of `actions/checkout` with the same defaults, and fails on any other input.
### Workflow-relative actions
`$/` references the repository and commit of the workflow, or of the enclosing composite action, e.g. `uses: $/.gitea/actions/build`.
Unlike `./`, it needs no checkout first.
### Actions written in Go
Gitea Actions supports writing actions in Go.
See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/).
### Support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly on schedule
Github Actions doesn't support that. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
`schedule` also accepts `@yearly`, `@monthly`, `@weekly`, `@daily` and `@hourly`, which [GitHub does not](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
## Unsupported workflows syntax
### `jobs.<job_id>.environment`
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment).
It's ignored by Gitea Actions now.
[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.
### Complex `runs-on`
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) supports:
Gitea Actions supports:
- Static strings: `runs-on: self-hosted`
- Arrays of labels: `runs-on: [linux, self-hosted]`
- String expressions: `runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
- Arrays containing expressions: `runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
## Missing features
### Package repository authorization
The `GITEA_TOKEN` for a job running within a repository should be able to publish to the associated package repository (i.e. to upload OCI images). See the "packages" scope for the "default access" in [Automatic token authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
This is not implemented in Gitea Actions now. A workaround for Gitea Actions is to use a Personal Access Token (PAT). See this [github issue and comment](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692) for tracking this feature.
`GITEA_TOKEN` cannot publish to the package registry of its repository, e.g. to push OCI images.
Use a personal access token instead, see [this issue](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692).
### Problem Matchers
Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md).
It's ignored by Gitea Actions now.
[Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.
### Create an error annotation
See [Creating an annotation for an error](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)
It's ignored by Gitea Actions now.
[Error annotations](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) are ignored.
### Expressions
For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), Gitea Actions supports standard GitHub functions (e.g. `success()`, `failure()`, `always()`, `cancelled()`, `format()`, `toJSON()`) and context variables (like `github`, `matrix`, `vars`, `env`).
[Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions) support the standard GitHub functions and contexts.
## Missing UI features
### Pre and Post steps
Pre and Post steps don't have their own section in the job log user interface.
Pre and post steps have no section of their own in the job log.
### Services steps
Services steps don't have their own section in the job log user interface.
Service steps have no section of their own in the job log.
## Different behavior
### Job token permissions (`permissions`)
Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
`permissions` and `jobs.<job_id>.permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access.
GitHub-only scopes like `statuses`, `checks`, `deployments`, `id-token`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`.
See [Actions job token permissions](token-permissions.md).
### Downloading actions
Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
We have since restricted this option to only allow two values (`github` and `self`).
When set to `github`, the new default, Gitea will download non-fully-qualified actions from `https://github.com`.
For example, if you use `uses: actions/checkout@v4`, it will download the checkout repository from `https://github.com/actions/checkout.git`.
If you want to download an action from another git hoster, you can use an absolute URL, e.g. `uses: https://gitea.com/actions/checkout@v4`.
If your Gitea instance is in an intranet or a restricted area, you can set the URL to `self` to only download actions from your own instance by default.
Of course, you can still use absolute URLs in workflows.
More details about the `[actions].DEFAULT_ACTIONS_URL` configuration can be found in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions)。
Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`.
See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).
### Context availability
Context availability is not checked, so you can use the env context on more places.
See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability).
[Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability) is not checked, so contexts like `env` work in more places.
docs/usage/actions/design.md
+4 -4
View File
@@ -19,7 +19,7 @@ Additionally, the runner will introduce itself to Gitea and declare what kind of
Earlier, we mentioned that `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label.
But how does the runner know to run `ubuntu-latest`? The answer lies in mapping the label to an environment.
That's why when you add custom labels during registration, you will need to input some complex content like `my_custom_label:docker://centos:7`.
That's why each label of a runner names an environment, like `my_custom_label:docker://centos:7`.
This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`.
Docker isn't the only option, though.
@@ -34,7 +34,6 @@ So,
- `my_custom_label:docker://node:18`: Run jobs labeled with `my_custom_label` using the `node:18` Docker image.
- `my_custom_label:host`: Run jobs labeled with `my_custom_label` directly on the host.
- `my_custom_label`: Same as `my_custom_label:host`.
- `my_custom_label:vm:ubuntu-latest`: (Example only, not implemented) Run jobs labeled with `my_custom_label` using a virtual machine with the `ubuntu-latest` ISO.
## Communication protocol
@@ -43,7 +42,7 @@ However, we did not think it was a good idea to have Gitea listen on a new port.
Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP.
We chose to use gRPC over HTTP.
We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up.
The protocol is defined in [actions-proto-def](https://gitea.com/gitea/actions-proto-def), its Go code lives in [actionslib](https://gitea.com/gitea/actionslib).
More information about gRPC can be found on [its website](https://grpc.io/).
## Network architecture
@@ -71,7 +70,8 @@ However, if a job container tries to fetch code from localhost, it will fail bec
### Connection 3, runner to internet
When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
By default, it downloads from [github.com](http://github.com/), so it requires access to the internet. If you configure the `DEFAULT_ACTIONS_URL` to `self`, then it will download from your Gitea instance by default. Then it will not connect to internet when downloading the action itself.
By default, it downloads them from [github.com](https://github.com/), which requires internet access.
With `DEFAULT_ACTIONS_URL` set to `self`, or with `uses: self:owner/repo@ref`, it downloads them from your Gitea instance instead.
It also downloads some docker images from Docker Hub by default, which also requires internet access.
However, internet access is not strictly necessary.
docs/usage/actions/faq.md
+17 -69
View File
@@ -27,50 +27,24 @@ Still, this is completely optional since both options have the same effect at th
## Where will the runner download scripts when using actions such as `actions/checkout@v4`?
There are tens of thousands of [actions scripts](https://github.com/marketplace?type=actions) in GitHub, and when you write `uses: actions/checkout@v4`, it downloads the scripts from [github.com/actions/checkout](http://github.com/actions/checkout) by default.
But what if you want to use actions from other places such as gitea.com instead of GitHub?
From `https://github.com` by default, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`, see the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
The good news is that you can specify the URL prefix to use actions from anywhere.
This is an extra syntax in Gitea Actions.
For example:
To use an action from elsewhere, name its host:
- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: https://github.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/xxx@xxx`
Be careful, the `https://` or `http://` prefix is necessary!
This is one of the differences from GitHub Actions which supports actions scripts only from GitHub.
But it should allow users much more flexibility in how they run Actions.
Alternatively, if you want your runners to download actions from your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`.
See [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
- `uses: https://gitea.com/owner/repo@ref`
- `uses: http://your_gitea_instance.com/owner/repo@ref`
- `uses: self:owner/repo@ref` for your own Gitea instance
## How to limit the permission of the runners?
Runners have no more permissions than simply connecting to your Gitea instance.
When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job.
If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](usage/actions/secrets.md) to it.
Refined permission control to Actions is a complicated job.
In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
Runners only connect to your Gitea instance.
For each job, a runner gets a `GITEA_TOKEN` limited to the job's repository, see [Actions job token permissions](token-permissions.md).
To give a job access to more private repositories or external systems, pass it [secrets](usage/actions/secrets.md).
## Which operating systems are supported by Gitea Runner?
We released official binaries for Linux, macOS, and Windows.
While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
```yaml
defaults:
run:
shell: powershell
```
Official binaries are released for Linux, macOS and Windows.
Other systems supported by Go and Docker work in theory.
## How to avoid being hacked?
@@ -99,42 +73,13 @@ It is exciting to be able to reuse them.
## What if it runs on multiple labels, such as `runs-on: [label_a, label_b]`?
This is valid syntax.
It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
Unfortunately, the runner does not work this way until v0.2.11.
As mentioned, we map labels to environments:
- `ubuntu` → `ubuntu:22.04`
- `centos` → `centos:8`
But we need to map label groups to environments instead, like so:
- `[ubuntu]` → `ubuntu:22.04`
- `[with-gpu]` → `linux:with-gpu`
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
We also need to re-design how tasks are assigned to runners.
A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`.
Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`.
This is not a technical problem, it was just overlooked in the early design.
See [runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
Currently, the runner attempts to match everyone in the labels and uses the first match it finds.
The job runs on a runner that has all of the labels, as on [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
The runner uses the environment of the first label it has.
## What is the difference between agent labels and custom labels for a runner?
![labels](/images/usage/actions/labels.png)
Agent labels are reported to the Gitea instance by the runner during registration.
Custom labels, on the other hand, are added manually by a Gitea administrator or owners of the organization or repository (depending on the level of the runner).
However, the design here needs improvement, as it currently has some rough edges.
You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`.
However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end.
This default may not match user expectations.
See [runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
In the meantime, we suggest that you re-register your runner if you want to change its labels.
Gitea no longer has custom labels.
A runner declares its labels every time it starts, from its `runner.labels` configuration or the labels given at registration, so change them there and restart the runner.
## Will there be more implementations for Gitea Actions runner?
@@ -177,3 +122,6 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.
To share within the same user or organization, add the private repositories under its **Settings** > **Actions** > **General** > **Cross-Repository Access** instead.
See [Cross-repository access](token-permissions.md#cross-repository-access).
docs/usage/actions/scoped-workflows.md
+2 -2
View File
@@ -102,8 +102,8 @@ Only a workflow that runs on an event that posts a commit status (`push`, `pull_
Scoped workflows can call reusable workflows:
- A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
- A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
- A **local** reference (`uses: ./...` or `uses: $/...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
- A **cross-repository** reference (`uses: owner/repo/...@ref` or `uses: self:owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
docs/usage/actions/variables.md
+1
View File
@@ -15,6 +15,7 @@ These environment variables are set automatically in every workflow run and can
| `CI` | Always set to `true`. | `true` |
| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` |
| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md
+10 -19
View File
@@ -1074,7 +1074,7 @@ In-Reply-To =
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 设置为 false 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于安排任务，例如 `@every 168h`。
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用于检查新版本的端点。
@@ -1082,7 +1082,7 @@ In-Reply-To =
- `ENABLED`: **false**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
- `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。
@@ -1102,35 +1102,35 @@ In-Reply-To =
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@annually**: Cron 语法，用于设置重建索引的频率。
#### Cron - 停止长时间未更新的运行中任务 (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 5m**: Cron 语法，用于设置检查的频率。
#### Cron - 停止持续更新但长时间未结束的运行中任务 (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 30m**: Cron 语法，用于设置检查的频率。
#### Cron - 取消长时间未被领取的任务 (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 6h**: Cron 语法，用于设置检查的频率。
#### Cron - 启动基于定时的 Actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 1m**: Cron 语法，用于设置调度任务的频率。
## Git (`git`)
@@ -1541,18 +1541,9 @@ PROXY_HOSTS = *.github.com
- `SCOPED_WORKFLOW_DIRS`：**.gitea/scoped_workflows**：以逗号分隔的目录列表，用于存放[作用域工作流](usage/actions/scoped-workflows.md)（在一个中心源仓库中定义、并在其他仓库上运行的工作流）。不得与 `WORKFLOW_DIRS` 重叠。留空则不会扫描任何目录来查找作用域工作流，因此不会找到或运行任何作用域工作流。
- `MAX_RERUN_ATTEMPTS`：**50**：单个工作流运行最多可以有的尝试次数（初始运行 + 重新运行）。默认 50。可根据需要设置为任何正整数。
`DEFAULT_ACTIONS_URL` 指示 Gitea 操作运行程序应该在哪里找到带有相对路径的操作。
例如，`uses: actions/checkout@v4` 表示 `https://github.com/actions/checkout@v4`，因为 `DEFAULT_ACTIONS_URL` 的值为 `github`。
它可以更改为 `self`，以使其成为 `root_url_of_your_gitea/actions/checkout@v4`。
请注意，对于大多数情况，不建议使用 `self`，因为它可能使名称在全局范围内产生歧义。
此外，它要求您将所有所需的操作镜像到您的 Gitea 实例，这可能不值得。
因此，请仅在您了解自己在做什么的情况下使用 `self`。
在早期版本（`<= 1.19`）中，`DEFAULT_ACTIONS_URL` 可以设置为任何自定义 URL，例如 `https://gitea.com` 或 `http://your-git-server,https://gitea.com`，默认值为 `https://gitea.com`。
然而，后来的更新删除了这些选项，现在唯一的选项是 `github` 和 `self`，默认值为 `github`。
但是，如果您想要使用其他 Git 服务器中的操作，您可以在 `uses` 字段中使用完整的 URL，Gitea 支持此功能（GitHub 不支持）。
例如 `uses: https://gitea.com/actions/checkout@v4` 或 `uses: http://your-git-server/actions/checkout@v4`。
`DEFAULT_ACTIONS_URL` 设置 runner 从何处下载未指定主机的操作。
值为 `github` 时，`uses: actions/checkout@v4` 解析为 `https://github.com/actions/checkout@v4`，值为 `self` 时解析为 `<ROOT_URL>/actions/checkout@v4`。
`self` 要求您将用到的所有操作镜像到您的实例，因此更推荐为每个操作单独指明主机：使用 `uses: self:owner/repo@ref` 指向您的实例，或使用完整 URL（如 `uses: https://gitea.com/actions/checkout@v4`）指向任何其他主机。
## 其他 (`other`)
i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/reverse-proxies.md
+81 -18
View File
@@ -14,6 +14,8 @@ aliases:
2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea，使 Gitea 可以看到正在访问的真实 URL。
5. 确保 Web 服务器有完整的证书（包括所有中间证书和根证书），以便 `git clone` 和 `git pull` 正常工作。
6. Gitea 会在 `/-/ws` 使用 WebSocket 连接，用于通知计数等实时更新。请确保反向代理使用 HTTP/1.1，并转发 `Upgrade` 和 `Connection` 头，参见下面的示例。否则 Gitea 会回退为定期轮询。
## 使用子路径
@@ -39,6 +41,7 @@ server {
location / {
client_max_body_size 512M;
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
@@ -61,8 +64,9 @@ server {
# 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
rewrite ^ $request_uri;
rewrite ^(/gitea)?(/.*) $2 break;
rewrite ^/(gitea($|/))?(.*) /$3 break;
proxy_pass http://127.0.0.1:3000$uri;
proxy_http_version 1.1;
# 其他的常规 HTTP 表头，见上面“使用 Nginx 作为反向代理服务”小节的配置
proxy_set_header Connection $http_connection;
@@ -107,6 +111,7 @@ server {
}
location / {
# 其他指令见上面「使用 Nginx 作为反向代理服务」小节
proxy_pass http://localhost:3000;
}
}
@@ -123,6 +128,7 @@ server {
server_name git.example.com;
location / {
# 其他指令见上面「使用 Nginx 作为反向代理服务」小节
proxy_pass http://localhost:3000;
}
}
@@ -144,6 +150,20 @@ server {
}
```
## Nginx Proxy Manager
如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理，配置与原生 Nginx 略有不同。
它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复（尤其是 `proxy_set_header Host $host`）出现 `400 bad request`。
创建 `/` 自定义 location 时，只需在其配置中加入：
```nginx
client_max_body_size 512M;
```
在代理主机上启用 `Websockets Support`，Nginx Proxy Manager 会自行加入 WebSocket 相关指令。再额外添加 `proxy_http_version` 会导致 Nginx 拒绝启动。
## 使用 Apache HTTPD 作为反向代理服务
如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
@@ -154,30 +174,23 @@ server {
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
:::note
必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。
`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更旧的版本**必须**去掉它，否则 Apache HTTPD 将无法启动。
:::
如果希望用 Let's Encrypt 的 webroot 验证，请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把这些请求代理到 Gitea。
## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
```
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass /git http://localhost:3000 nocanon
</VirtualHost>
```
```apacheconf
<VirtualHost *:80>
...
@@ -187,7 +200,7 @@ server {
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass /git http://localhost:3000 nocanon
ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
@@ -195,7 +208,55 @@ server {
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
:::note
必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
:::
## 使用 Apache HTTPD 直接提供静态资源
我们可以通过将资源分为静态和动态两种类型来调节性能。
CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
Apache HTTPD 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
（为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
### 单服务器节点，单域名
将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory /path/to/gitea/public/>
Options FollowSymlinks
AllowOverride None
Require all granted
</Directory>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
:::
## 使用 Caddy 作为反向代理服务
@@ -231,11 +292,13 @@ git.example.com {
- 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安装 Application Request Routing（简称 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下载这个插件。
- 一但这个模块被安装到 IIS 上，你将会在 IIS 管理控制台看到一个叫做 URL Rewrite 的新图标。
- 安装 Windows 功能 `WebSocket Protocol`，否则 ARR 无法代理 Gitea 的 WebSocket 端点。
- 打开 IIS 管理控制台，在左边的列表中点击 `Gitea Proxy` 网页。在中间选中并且双击 URL Rewrite 的图标来加载 URL 重写的面板。
- 在管理控制台的右边选择 `Add Rule` 操作，并且在 `Inbound and Outbound Rules` 分类中选择 `Reverse Proxy Rule`。
- 在 Inbound Rules 中， 将 server name 设置为 Gitea 正在运行的主机以及对应端口。例如，如果你在 localhost 的 3000 端口上运行 Gitea，则设置为 `127.0.0.1:3000`。
- 启用 SSL Offloading
- 在 Outbound Rules 中，确保设置了 `Rewrite the domain names of the links in HTTP response`，并且将 `From:` 设置为上面的 server name，将 `To:` 设置为你的外部访问名称，例如：`git.example.com`
- 关闭 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理器中选择服务器节点，打开 `Application Request Routing Cache`，再打开右侧的 `Server Proxy Settings`）。若保持开启，ARR 会把 `Location` 头里的主机改回内部地址，导致登录或表单提交后的重定向把浏览器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
- 现在，根据下面的内容为您的网页编辑 `web.config`（将 `127.0.0.1:3000` 和 `git.example.com` 改为适当的值）
```xml
i18n/zh-cn/docusaurus-plugin-content-docs/current/development/api-usage.md
+1
View File
@@ -12,6 +12,7 @@ aliases:
通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
<a id="authentication"></a>
## 通过 API 认证
Gitea 支持以下几种 API 认证方式：
i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/with-docker-rootless.md
+1 -1
View File
@@ -53,7 +53,7 @@ sudo chown 1000:1000 config/ data/
> 如果未为卷设置正确的权限，容器可能无法启动。
对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:dev-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-dev-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.16-dev-rootless`）。
对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:main-nightly-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly-rootless`）。
## 自定义端口
i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/with-docker.md
+1 -1
View File
@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始
## 基本
最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。
最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。
```yaml
version: "3"
i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/comparison.md
+46 -69
View File
@@ -6,120 +6,97 @@ sidebar_position: 15
# 与GitHub Actions的对比
尽管Gitea Actions旨在与GitHub Actions兼容，但它们之间存在一些差异。
Gitea Actions旨在与GitHub Actions兼容，差异如下。
## 额外功能
<a id="absolute-action-urls"></a>
### Action URL绝对路径
Gitea Actions支持通过URL绝对路径定义actions，这意味着您可以使用来自任何Git存储库的Actions。
例如，`uses: https://github.com/actions/checkout@v4`或`uses: http://your_gitea.com/owner/repo@branch`。
`uses:`支持指向任意Git托管平台的绝对URL，例如`uses: https://gitea.com/actions/checkout@v4`。
<a id="action-prefixes"></a>
### Action前缀
`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
Gitea Actions支持使用Go编写Actions。
请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
Github Actions 不支持这些语法，详见： https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
`schedule`还支持`@yearly`、`@monthly`、`@weekly`、`@daily`和`@hourly`，而[GitHub不支持](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
## 不支持的工作流语法
### `concurrency`
这是用于一次运行一个Job。
请参阅[使用并发](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。
Gitea Actions目前不支持此功能。
### `run-name`
这是工作流生成的工作流运行的名称。
请参阅[GitHub Actions 的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
Gitea Actions目前不支持此功能。
### `permissions`和`jobs.<job_id>.permissions`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
Gitea Actions目前不支持此功能。
### `jobs.<job_id>.timeout-minutes`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。
Gitea Actions目前不支持此功能。
### `jobs.<job_id>.continue-on-error`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
Gitea Actions目前不支持此功能。
### `jobs.<job_id>.environment`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
Gitea Actions 目前不支持此功能。
[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)会被忽略。
### 复杂的`runs-on`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)支持：
Gitea Actions目前只支持`runs-on: xyz`或`runs-on: [xyz]`。
### `hashFiles`表达式
请参阅[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。
Gitea Actions目前不支持此功能，如果使用它，结果将始终为空字符串。
作为解决方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。
- 静态字符串：`runs-on: self-hosted`
- 标签数组：`runs-on: [linux, self-hosted]`
- 字符串表达式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
- 包含表达式的数组：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
## 缺失的功能
### 软件包仓库授权
`GITEA_TOKEN`无法发布到其所属仓库的软件包注册表，例如无法推送OCI镜像。
请改用个人访问令牌，参见[此问题](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
### 问题匹配器
问题匹配器是一种扫描Actions输出以查找指定正则表达式模式并在用户界面中突出显示该信息的方法。
请参阅[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
Gitea Actions目前不支持此功能。
[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)会被忽略。
### 为错误创建注释
请参阅[为错误创建注释](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。
Gitea Actions目前不支持此功能。
[错误注释](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)会被忽略。
### 表达式
对于 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions), 当前仅 [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) 被支持。
[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions)支持GitHub的标准函数和上下文。
## 缺失的UI功能
### 预处理和后处理步骤
预处理和后处理步骤在Job日志用户界面中没有自己的用户界面。
预处理和后处理步骤在Job日志中没有单独的区块。
### 服务步骤
服务步骤在Job日志用户界面中没有自己的用户界面。
服务步骤在Job日志中没有单独的区块。
## 不一样的行为
### `permissions`和`jobs.<job_id>.permissions`
`permissions`和`jobs.<job_id>.permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。
不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。
请参阅[Actions Job令牌权限](token-permissions.md)。
### 下载Actions
当 `[actions].DEFAULT_ACTIONS_URL` 保持默认值为 `github` 时，Gitea将会从 https://github.com 下载相对路径的actions。比如：
如果你使用 `uses: actions/checkout@v4`，Gitea将会从 https://github.com/actions/checkout.git 下载这个 actions 项目。
如果你想要从另外一个 Git服务下载actions，你只需要使用绝对URL `uses: https://gitea.com/actions/checkout@v4` 来下载。
如果你的 Gitea 实例是部署在一个互联网限制的网络中，也可以使用绝对地址来下载 actions。你也可以将配置项修改为 `[actions].DEFAULT_ACTIONS_URL = self`。这样所有的相对路径的actions引用，将不再会从 github.com 去下载，而会从这个 Gitea 实例自己的仓库中去下载。例如： `uses: actions/checkout@v4` 将会从 `[server].ROOT_URL`/actions/checkout.git 这个地址去下载 actions。
设置`[actions].DEFAULT_ACTIONS_URL`进行配置。请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-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)和[相对于工作流的Actions](#workflow-relative-actions)。
### 上下文可用性
不检查上下文可用性，因此您可以在更多地方使用env上下文。
请参阅[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
不检查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此`env`等上下文可以在更多地方使用。
i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/design.md
+4 -5
View File
@@ -19,7 +19,7 @@ Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支
之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。
但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。
这就是为什么在注册过程中添加自定义标签时，需要输入一些复杂内容，比如`my_custom_label:docker://centos:7`。
这就是为什么Runner的每个标签都会指定一个环境，比如`my_custom_label:docker://centos:7`。
这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
然而，Docker不是唯一的选择。
@@ -35,7 +35,6 @@ Runner 也支持直接在主机上运行Job。
- `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。
- `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。
- `my_custom_label`：等同于`my_custom_label:host`。
- `my_custom_label:vm:ubuntu-latest`：（仅为示例，未实现）使用带有`ubuntu-latest` ISO的虚拟机运行带有`my_custom_label`标签的Job。
## 通信协议
@@ -44,7 +43,7 @@ Runner 也支持直接在主机上运行Job。
相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
因此，我们选择使用基于HTTP的gRPC。
我们使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 进行连接。
该协议定义在[actions-proto-def](https://gitea.com/gitea/actions-proto-def)中，其Go代码位于[actionslib](https://gitea.com/gitea/actionslib)。
有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。
## 网络架构
@@ -72,8 +71,8 @@ Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
### 连接 3，runner 到互联网
当您使用诸如 `actions/checkout@v4` 的一些Actions时， runner下载的是脚本，而不是Job容器。
默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
默认情况下，它从[github.com](https://github.com/)下载这些脚本，这需要访问互联网。
如果将`DEFAULT_ACTIONS_URL`设置为`self`，或使用`uses: self:owner/repo@ref`，它会改为从您的Gitea实例下载。
它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
然而，互联网访问并不是绝对必需的。
i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/faq.md
+22 -69
View File
@@ -27,34 +27,19 @@ DEFAULT_REPO_UNITS = ...,repo.actions
## 使用`actions/checkout@v4`等Actions时，Job容器会从何处下载脚本？
GitHub 上有成千上万个 [Actions 脚本](https://github.com/marketplace?type=actions)。
当您编写 `uses: actions/checkout@v4` 时，它默认会从 [github.com/actions/checkout](https://github.com/actions/checkout) 下载脚本。
那如果您想使用一些托管在其它平台上的脚本呢，比如在 gitea.com 上的？
默认从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载，参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
好消息是，您可以指定要从任何位置使用Actions的URL前缀。
这是Gitea Actions中的额外语法。
例如：
要使用其他位置的Action，请指明其主机：
- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: https://github.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/xxx@xxx`
注意，`https://`或`http://`前缀是必需的！
这是与 GitHub Actions 的一个区别，GitHub Actions 只允许使用托管在 GitHub 上的 actions 脚本。
但用户理应拥有权利去灵活决定如何运行 Actions。
另外，如果您希望您的 Runner 默认从您自己的 Gitea 实例下载 Actions，可以通过设置 `[actions].DEFAULT_ACTIONS_URL`进行配置。
参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
- `uses: https://gitea.com/owner/repo@ref`
- `uses: http://your_gitea_instance.com/owner/repo@ref`
- `uses: self:owner/repo@ref`，用于您自己的Gitea实例
## 如何限制Runner的权限？
Runner仅具有连接到您的Gitea实例的权限。
当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。
如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](usage/actions/secrets.md)。
对于 Actions 的细粒度权限控制是一项复杂的工作。
在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。
Runner仅连接到您的Gitea实例。
对于每个Job，Runner会获得一个仅限于该Job所属仓库的`GITEA_TOKEN`，参见[Actions Job令牌权限](token-permissions.md)。
如需让Job访问更多私有仓库或外部系统，请向其传递[密钥](usage/actions/secrets.md)。
## 如何避免被黑客攻击？
@@ -75,19 +60,8 @@ Runner仅具有连接到您的Gitea实例的权限。
## Runner 支持哪些操作系统？
它在Linux、macOS和Windows上运行良好。
虽然理论上支持其他操作系统，但需要进一步测试。
需要注意的一点是，如果选择直接在主机上运行Job而不是在Job容器中运行，操作系统之间的环境差异可能会导致意外的失败。
例如，在大多数情况下，Windows上没有可用的bash，而act尝试默认使用bash运行脚本。
因此，您需要在工作流文件中将默认shell指定为`powershell`，参考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。
```yaml
defaults:
run:
shell: powershell
```
官方发布了Linux、macOS和Windows的二进制文件。
理论上，Go和Docker支持的其他系统也可以运行。
## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？
@@ -99,42 +73,13 @@ defaults:
## 如果它在多个标签上运行，例如 `runs-on: [label_a, label_b]`，会发生什么？
这是有效的语法。
它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
不幸的是，runner 并不支持这种方式。
如上所述，我们将标签映射到环境：
- `ubuntu` → `ubuntu:22.04`
- `centos` → `centos:8`
但我们需要将标签组映射到环境，例如：
- `[ubuntu]` → `ubuntu:22.04`
- `[with-gpu]` → `linux:with-gpu`
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
我们还需要重新设计任务分配给Runner的方式。
具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
这不是一个技术问题，只是在早期设计中被忽视了。
参见[runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
目前，runner 尝试匹配标签中的每一个，并使用找到的第一个匹配项。
该Job会在拥有所有这些标签的Runner上运行，与[GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)一致。
Runner会使用这些标签中它所拥有的第一个标签对应的环境。
## 代理标签和自定义标签对于Runner有什么区别？
![labels](/images/usage/actions/labels.png)
代理标签是由 Runner 在注册过程中向 Gitea 实例报告的。
而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。
然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
这个默认值可能与用户的期望不符。
参见[runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。
Gitea已不再有自定义标签。
Runner每次启动时都会声明其标签，标签来自`runner.labels`配置或注册时指定的标签，因此请在那里修改并重启Runner。
## Gitea Actions runner会有更多的实现吗？
@@ -165,3 +110,11 @@ defaults:
> 对于 `pull_request` 事件，在 [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) 中 `ref` 是 `refs/pull/:prNumber/merge`，它指向这个拉取请求合并提交的一个预览。但是 Gitea 没有这种 reference。
> 因此，Gitea Actions 中 `ref` 是 `refs/pull/:prNumber/head`，它指向这个拉取请求的头分支而不是合并提交的预览。
## 如何共享私有仓库中的Actions和可复用工作流？
前往仓库的**设置** > **Actions** > **常规**页面并添加协作所有者。
协作所有者的私有仓库可以访问当前仓库中的Actions和工作流。
如需在同一用户或组织内共享，请改为在该用户或组织的**设置** > **Actions** > **常规** > **跨仓库访问**中添加这些私有仓库。
参见[跨仓库访问](token-permissions.md#cross-repository-access)。
i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/scoped-workflows.md
+2 -2
View File
@@ -102,8 +102,8 @@ SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
作用域工作流可以调用可复用工作流：
- **本地**引用（`uses: ./...`）会相对于**源**仓库解析：即调用方工作流内容的来源仓库，而非消费方仓库。
- **跨仓库**引用（`uses: owner/repo/...@ref`）会以**消费方仓库的**读取权限来解析。如果它指向一个私有仓库，请确保每个消费方仓库都能读取它，否则工作流会在那里失败。
- **本地**引用（`uses: ./...` 或 `uses: $/...`）会相对于**源**仓库解析：即调用方工作流内容的来源仓库，而非消费方仓库。
- **跨仓库**引用（`uses: owner/repo/...@ref` 或 `uses: self:owner/repo/...@ref`）会以**消费方仓库的**读取权限来解析。如果它指向一个私有仓库，请确保每个消费方仓库都能读取它，否则工作流会在那里失败。
可复用工作流可以放在源仓库的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。
i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/token-permissions.md
+126
View File
@@ -0,0 +1,126 @@
---
date: "2026-03-19T00:00:00+01:00"
slug: "token-permissions"
sidebar_position: 30
---
# Actions Job令牌权限（`GITEA_TOKEN`）
每个Actions Job都会获得一个内置令牌（`GITEA_TOKEN`），可用于访问Gitea（通过HTTP(S)访问Git、API请求等）。
本页面介绍Gitea如何决定该令牌可以执行哪些操作。
在工作流中，可以通过`${{ secrets.GITEA_TOKEN }}`使用该令牌。这些设置和`permissions:`仅影响`GITEA_TOKEN`（不影响个人访问令牌等其他密钥）。关于API调用，请参阅[API认证](../../development/api-usage.md#authentication)。
<a id="where-permissions-come-from"></a>
## 权限来源
Gitea按以下顺序确定Job令牌的权限：
1. Job级别的`permissions:`（`jobs.<job_id>.permissions`）
2. 工作流级别的`permissions:`（顶层）
3. 设置中的默认权限（所有者或仓库）
然后，该结果会受到所配置的最大令牌权限的**限制**（见下文）。
<a id="supported-workflow-syntax"></a>
## 支持的工作流语法
Gitea支持与GitHub Actions兼容的`permissions:`关键字。
<a id="scalar-values"></a>
### 标量值
```yaml
permissions: read-all # or: write-all
```
<a id="scoped-mapping"></a>
### 按权限范围映射
```yaml
permissions:
contents: read
issues: write
pull-requests: none
```
每个权限范围的有效访问模式值为`read`、`write`和`none`。
<a id="supported-scopes"></a>
### 支持的权限范围
- `contents`（适用于`code`和`releases`）
- `code`
- `releases`
- `issues`
- `pull-requests`
- `actions`
- `wiki`
- `projects`
- `packages`（如果目标功能支持）
如果同时指定了`contents`和更细粒度的权限范围（如`code`或`releases`），则该单元以更细粒度的权限范围为准。
<a id="compatibility-notes"></a>
### 兼容性说明
Gitea支持GitHub Actions权限范围的一个子集。
Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围。
Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不作为独立的权限范围存在：
- `code`
- `releases`
- `wiki`
- `projects`
<a id="default-permission-mode"></a>
## 默认权限模式
如果工作流和Job都没有定义`permissions:`，Gitea会使用所配置的默认模式：
- **宽松**：对Job所属仓库的大多数单元拥有读写权限（向后兼容的默认值）。
- **受限**：对Job所属仓库的`code`、`releases`和`packages`拥有只读权限，默认无权访问其他单元。
<a id="maximum-token-permissions-clamping"></a>
## 最大令牌权限（限制）
您可以为每个仓库单元配置最大权限。
Job的实际权限按以下方式计算：
`effective = min(requested, maximum)`
这意味着工作流可以降低Job的权限，但不能超过您配置的最大权限。
如果未配置最大权限，则所有权限范围的最大权限默认为`write`。
<a id="where-to-configure"></a>
## 配置位置
您可以在以下位置配置默认权限和最大权限：
- **用户/组织**：`Settings` → `Actions` → `General`
- **仓库**：`Settings` → `Actions` → `General`
- 对于组织中的仓库，可以遵循所有者级别的配置，也可以通过**覆盖所有者级别的配置**选择不遵循。
注意：仅在启用**仓库Actions**后，才会显示仓库级别的令牌权限设置。
<a id="fork-pull-requests"></a>
## Fork拉取请求
出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。
<a id="cross-repository-access"></a>
## 跨仓库访问
默认情况下，`GITEA_TOKEN`只能访问：
- Job所属仓库（依据计算出的权限）
- 公开仓库（只读）
默认拒绝访问其他私有仓库。
用户或组织可以通过**设置 → Actions → 常规 → 跨仓库访问**，允许以只读方式访问选定的私有仓库。
私有仓库也可以通过**设置 → Actions → 常规**允许选定的协作所有者。
这样，这些所有者的私有仓库便可读取当前私有仓库以供Actions使用，例如私有Actions和可复用工作流。
fork拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/administration/config-cheat-sheet.md
+1 -1
View File
@@ -969,7 +969,7 @@ Gitea 创建以下非唯一队列：
- `ENABLED`: **false**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
- `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.23/administration/config-cheat-sheet.md
+1 -1
View File
@@ -975,7 +975,7 @@ Gitea 创建以下非唯一队列：
- `ENABLED`: **false**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
- `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.24/administration/config-cheat-sheet.md
+1 -1
View File
@@ -990,7 +990,7 @@ Gitea 创建以下非唯一队列：
- `ENABLED`: **false**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
- `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.25/administration/config-cheat-sheet.md
+1 -1
View File
@@ -990,7 +990,7 @@ Gitea 创建以下非唯一队列：
- `ENABLED`: **false**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
- `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.26/administration/config-cheat-sheet.md
+7 -7
View File
@@ -1101,7 +1101,7 @@ In-Reply-To =
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 设置为 false 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于安排任务，例如 `@every 168h`。
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用于检查新版本的端点。
@@ -1109,7 +1109,7 @@ In-Reply-To =
- `ENABLED`: **false**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
- `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。
@@ -1129,35 +1129,35 @@ In-Reply-To =
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@annually**: Cron 语法，用于设置重建索引的频率。
#### Cron - 停止长时间未更新的运行中任务 (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 5m**: Cron 语法，用于设置检查的频率。
#### Cron - 停止持续更新但长时间未结束的运行中任务 (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 30m**: Cron 语法，用于设置检查的频率。
#### Cron - 取消长时间未被领取的任务 (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 6h**: Cron 语法，用于设置检查的频率。
#### Cron - 启动基于定时的 Actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 1m**: Cron 语法，用于设置调度任务的频率。
## Git (`git`)
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.27/administration/config-cheat-sheet.md
+7 -7
View File
@@ -1106,7 +1106,7 @@ In-Reply-To =
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 设置为 false 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于安排任务，例如 `@every 168h`。
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用于检查新版本的端点。
@@ -1114,7 +1114,7 @@ In-Reply-To =
- `ENABLED`: **false**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
- `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。
@@ -1134,35 +1134,35 @@ In-Reply-To =
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@annually**: Cron 语法，用于设置重建索引的频率。
#### Cron - 停止长时间未更新的运行中任务 (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 5m**: Cron 语法，用于设置检查的频率。
#### Cron - 停止持续更新但长时间未结束的运行中任务 (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 30m**: Cron 语法，用于设置检查的频率。
#### Cron - 取消长时间未被领取的任务 (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 6h**: Cron 语法，用于设置检查的频率。
#### Cron - 启动基于定时的 Actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: 启用服务。
- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
- `SCHEDULE`: **@every 1m**: Cron 语法，用于设置调度任务的频率。
## Git (`git`)
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.27/administration/reverse-proxies.md
+61 -15
View File
@@ -14,6 +14,7 @@ aliases:
2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea，使 Gitea 可以看到正在访问的真实 URL。
5. 确保 Web 服务器有完整的证书（包括所有中间证书和根证书），以便 `git clone` 和 `git pull` 正常工作。
## 使用子路径
@@ -61,7 +62,7 @@ server {
# 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
rewrite ^ $request_uri;
rewrite ^(/gitea)?(/.*) $2 break;
rewrite ^/(gitea($|/))?(.*) /$3 break;
proxy_pass http://127.0.0.1:3000$uri;
# 其他的常规 HTTP 表头，见上面“使用 Nginx 作为反向代理服务”小节的配置
@@ -75,7 +76,7 @@ server {
}
```
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/gitea/` 的配置项。
## 使用 Nginx 直接提供静态资源
@@ -144,6 +145,20 @@ server {
}
```
## Nginx Proxy Manager
如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理，配置与原生 Nginx 略有不同。
它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复（尤其是 `proxy_set_header Host $host`）出现 `400 bad request`。
创建 `/` 自定义 location 时，只需在其配置中加入：
```nginx
client_max_body_size 512M;
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
```
## 使用 Apache HTTPD 作为反向代理服务
如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
@@ -161,23 +176,12 @@ server {
注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
如果希望用 Let's Encrypt 的 webroot 验证，请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把这些请求代理到 Gitea。
## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
```
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass /git http://localhost:3000 nocanon
</VirtualHost>
```
```apacheconf
<VirtualHost *:80>
...
@@ -197,6 +201,48 @@ server {
注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
## 使用 Apache HTTPD 直接提供静态资源
我们可以通过将资源分为静态和动态两种类型来调节性能。
CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
Apache HTTPD 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
（为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
### 单服务器节点，单域名
将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory /path/to/gitea/public/>
Options FollowSymlinks
AllowOverride None
Require all granted
</Directory>
AllowEncodedSlashes NoDecode
# 注意: 路径和 URL 后面都不要写路径符号 '/'
ProxyPass / http://localhost:3000/ nocanon
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
## 使用 Caddy 作为反向代理服务
如果您想使用 Caddy 作为 Gitea 的反向代理服务，您可以在 `Caddyfile` 中添加如下配置：
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.27/installation/with-docker-rootless.md
+1 -1
View File
@@ -53,7 +53,7 @@ sudo chown 1000:1000 config/ data/
> 如果未为卷设置正确的权限，容器可能无法启动。
对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:dev-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-dev-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.16-dev-rootless`）。
对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:main-nightly-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly-rootless`）。
## 自定义端口
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.27/installation/with-docker.md
+1 -1
View File
@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始
## 基本
最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。
最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。
```yaml
version: "3"
i18n/zh-tw/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md
+10 -19
View File
@@ -1079,7 +1079,7 @@ In-Reply-To =
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 設定為 false 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於安排任務，例如 `@every 168h`。
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用於檢查新版本的端點。
@@ -1087,7 +1087,7 @@ In-Reply-To =
- `ENABLED`: **false**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於設定多長時間進行檢查。
- `OLDER_THAN`: **8760h**: 早於此表達式的任何系統通知都將從資料庫中刪除。
@@ -1108,35 +1108,35 @@ In-Reply-To =
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@annually**: Cron 語法，用於設定重建索引的頻率。
#### Cron - 停止長時間未更新的運行中任務 (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 5m**: Cron 語法，用於設定檢查的頻率。
#### Cron - 停止持續更新但長時間未結束的運行中任務 (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 30m**: Cron 語法，用於設定檢查的頻率。
#### Cron - 取消長時間未被領取的任務 (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 6h**: Cron 語法，用於設定檢查的頻率。
#### Cron - 啟動基於定時的 Actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 1m**: Cron 語法，用於設定調度任務的頻率。
## Git (`git`)
@@ -1548,18 +1548,9 @@ PROXY_HOSTS = *.github.com
- `SCOPED_WORKFLOW_DIRS`：**.gitea/scoped_workflows**：以逗號分隔的目錄列表，用於存放[作用域工作流程](usage/actions/scoped-workflows.md)（在一個中心來源儲存庫中定義、並在其他儲存庫上執行的工作流程）。不得與 `WORKFLOW_DIRS` 重疊。留空則不會掃描任何目錄來尋找作用域工作流程，也就不會找到或執行任何作用域工作流程。
- `MAX_RERUN_ATTEMPTS`：**50**：單個工作流執行最多可以有的嘗試次數（初始執行 + 重新執行）。預設 50。可根據需要設定為任何正整數。
`DEFAULT_ACTIONS_URL` 指示 Gitea 操作運行程式應該在哪裡找到帶有相對路徑的操作。
例如，`uses: actions/checkout@v4` 表示 `https://github.com/actions/checkout@v4`，因為 `DEFAULT_ACTIONS_URL` 的值為 `github`。
它可以更改為 `self`，以使其成為 `root_url_of_your_gitea/actions/checkout@v4`。
請注意，對於大多數情況，不建議使用 `self`，因為它可能使名稱在全域範圍內產生歧義。
此外，它要求您將所有所需的操作鏡像到您的 Gitea 實例，這可能不值得。
因此，請僅在您瞭解自己在做什麼的情況下使用 `self`。
在早期版本（`<= 1.19`）中，`DEFAULT_ACTIONS_URL` 可以設定為任何自訂 URL，例如 `https://gitea.com` 或 `http://your-git-server,https://gitea.com`，預設值為 `https://gitea.com`。
然而，後來的更新刪除了這些選項，現在唯一的選項是 `github` 和 `self`，預設值為 `github`。
但是，如果您想要使用其他 Git 伺服器中的操作，您可以在 `uses` 欄位中使用完整的 URL，Gitea 支援此功能（GitHub 不支援）。
例如 `uses: https://gitea.com/actions/checkout@v4` 或 `uses: http://your-git-server/actions/checkout@v4`。
`DEFAULT_ACTIONS_URL` 設定 Runner 從何處下載未指定主機的 Actions。
設為 `github` 時，`uses: actions/checkout@v4` 解析為 `https://github.com/actions/checkout@v4`，設為 `self` 時則解析為 `<ROOT_URL>/actions/checkout@v4`。
`self` 要求您將用到的每個 Action 都鏡像到您的實例，因此建議改為逐一為 Action 指定主機：您的實例使用 `uses: self:owner/repo@ref`，其他主機則使用完整 URL，例如 `uses: https://gitea.com/actions/checkout@v4`。
## 其他 (`other`)
i18n/zh-tw/docusaurus-plugin-content-docs/current/administration/reverse-proxies.md
+81 -18
View File
@@ -14,6 +14,8 @@ aliases:
2. 將 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
3. 確保反向代理不會解碼 URI。`https://git.example.com/a%2Fb`的請求應該被傳遞給 `http://gitea:3000/a%2Fb`。
4. 確保 `Host` 和 `X-Forwarded-Proto` 頭被正確的傳遞給 Gitea，使 Gitea 可以看到正在訪問的真實 URL。
5. 確保 Web 伺服器有完整的憑證（包括所有中間憑證和根憑證），以便 `git clone` 和 `git pull` 正常工作。
6. Gitea 會在 `/-/ws` 使用 WebSocket 連線，用於通知計數等即時更新。請確保反向代理使用 HTTP/1.1，並轉發 `Upgrade` 和 `Connection` 頭，參見下面的示例。否則 Gitea 會改為定期輪詢。
## 使用子路徑
@@ -39,6 +41,7 @@ server {
location / {
client_max_body_size 512M;
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
@@ -61,8 +64,9 @@ server {
# 確保 nginx 使用未轉義 URI， 按原樣保持 "%2F"。 確保 nginx 去除 "/gitea" 子路徑前綴， 按原樣傳遞 "/v2"。
rewrite ^ $request_uri;
rewrite ^(/gitea)?(/.*) $2 break;
rewrite ^/(gitea($|/))?(.*) /$3 break;
proxy_pass http://127.0.0.1:3000$uri;
proxy_http_version 1.1;
# 其他的常規 HTTP 表頭，見上面“使用 Nginx 作為反向代理服務”小節的配置
proxy_set_header Connection $http_connection;
@@ -107,6 +111,7 @@ server {
}
location / {
# 其他指令見上面「使用 Nginx 作為反向代理服務」小節
proxy_pass http://localhost:3000;
}
}
@@ -123,6 +128,7 @@ server {
server_name git.example.com;
location / {
# 其他指令見上面「使用 Nginx 作為反向代理服務」小節
proxy_pass http://localhost:3000;
}
}
@@ -144,6 +150,20 @@ server {
}
```
## Nginx Proxy Manager
如果使用 Nginx Proxy Manager 作為 Gitea 的反向代理，設定與原生 Nginx 略有不同。
它會[預設給自訂 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 設定裡對應的指令不要再寫一遍。否則會因為指令重複（尤其是 `proxy_set_header Host $host`）出現 `400 bad request`。
建立 `/` 自訂 location 時，只需在其設定中加入：
```nginx
client_max_body_size 512M;
```
在代理主機上啟用 `Websockets Support`，Nginx Proxy Manager 會自行加入 WebSocket 相關指令。再額外添加 `proxy_http_version` 會導致 Nginx 拒絕啟動。
## 使用 Apache HTTPD 作為反向代理服務
如果您想使用 Apache HTTPD 作為 Gitea 的反向代理服務，您可以為您的 Apache HTTPD 作如下設定（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：
@@ -154,30 +174,23 @@ server {
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
注：必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`
:::note
必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。
`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更舊的版本**必須**去掉它，否則 Apache HTTPD 將無法啟動。
:::
如果希望用 Let's Encrypt 的 webroot 驗證，請在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把這些請求代理到 Gitea。
## 使用 Apache HTTPD 作為反向代理服務並將 Gitea 路由至一個子路徑
如果您已經有一個域名並且想與 Gitea 共享該域名，您可以增加以下設定為 Gitea 添加路由規則（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：
```
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
ProxyPass /git http://localhost:3000 nocanon
</VirtualHost>
```
```apacheconf
<VirtualHost *:80>
...
@@ -187,7 +200,7 @@ server {
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
ProxyPass /git http://localhost:3000 nocanon
ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
@@ -195,7 +208,55 @@ server {
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://git.example.com/git/` 的設定項。
注：必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`
:::note
必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更舊的版本請去掉它。
:::
## 使用 Apache HTTPD 直接提供靜態資源
我們可以通過將資源分為靜態和動態兩種類型來調節性能。
CSS 文件、JavaScript 文件、圖片和字體是靜態內容。首頁、倉庫視圖和工單列表是動態內容。
Apache HTTPD 可以直接提供靜態資源，並且只代理動態資源請求給 Gitea。
將 Gitea 源代碼倉庫的一個快照下載到 `/path/to/gitea/`。
在此之後，在本地倉庫目錄運行 `make frontend` 來生成靜態資源。在這個情況下，我們只對 `public/` 目錄感興趣，您可以刪除剩下的其他目錄。
（為了生成靜態資源，您需要安裝一個[帶 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取決於您的用戶量的大小，您可以將流量分離到兩個不同的服務器，或者為靜態資源設定一個 cdn。
### 單伺服器節點，單域名
將 `[server] STATIC_URL_PREFIX = /_/static` 寫入您的 Gitea 設定文件：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory /path/to/gitea/public/>
Options FollowSymlinks
AllowOverride None
Require all granted
</Directory>
AllowEncodedSlashes NoDecode
# 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更舊的版本請去掉它。
:::
## 使用 Caddy 作為反向代理服務
@@ -231,11 +292,13 @@ git.example.com {
- 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安裝 Application Request Routing（簡稱 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下載這個外掛。
- 一但這個模組被安裝到 IIS 上，你將會在 IIS 管理控制檯看到一個叫做 URL Rewrite 的新圖標。
- 安裝 Windows 功能 `WebSocket Protocol`，否則 ARR 無法代理 Gitea 的 WebSocket 端點。
- 打開 IIS 管理控制檯，在左邊的列表中點擊 `Gitea Proxy` 網頁。在中間選中並且雙擊 URL Rewrite 的圖標來加載 URL 重寫的面板。
- 在管理控制檯的右邊選擇 `Add Rule` 操作，並且在 `Inbound and Outbound Rules` 分類中選擇 `Reverse Proxy Rule`。
- 在 Inbound Rules 中， 將 server name 設定為 Gitea 正在運行的主機以及對應端口。例如，如果你在 localhost 的 3000 端口上運行 Gitea，則設定為 `127.0.0.1:3000`。
- 啟用 SSL Offloading
- 在 Outbound Rules 中，確保設定了 `Rewrite the domain names of the links in HTTP response`，並且將 `From:` 設定為上面的 server name，將 `To:` 設定為你的外部訪問名稱，例如：`git.example.com`
- 關閉 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理員中選擇伺服器節點，打開 `Application Request Routing Cache`，再開啟右側的 `Server Proxy Settings`）。若保持開啟，ARR 會把 `Location` 頭裡的主機改回內部位址，導致登入或表單提交後的重新導向把瀏覽器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
- 現在，根據下面的內容為您的網頁編輯 `web.config`（將 `127.0.0.1:3000` 和 `git.example.com` 改為適當的值）
```xml
i18n/zh-tw/docusaurus-plugin-content-docs/current/installation/with-docker-rootless.md
+1 -1
View File
@@ -53,7 +53,7 @@ sudo chown 1000:1000 config/ data/
> 如果未為卷設定正確的權限，容器可能無法啟動。
對於穩定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的開發版本，則可以使用 `:dev-rootless` 標籤。如果您想運行發佈分支的最新提交，可以使用 `:1.x-dev-rootless` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.16-dev-rootless`）。
對於穩定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的開發版本，則可以使用 `:main-nightly-rootless` 標籤。如果您想運行發佈分支的最新提交，可以使用 `:1.x-nightly-rootless` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.27-nightly-rootless`）。
## 自訂端口
i18n/zh-tw/docusaurus-plugin-content-docs/current/installation/with-docker.md
+1 -1
View File
@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 組織內提供自動更新的 Docker 鏡像。可以始
## 基本
最簡單的設定只是建立一個卷和一個網路，然後將 `docker.gitea.com/gitea:latest` 鏡像作為服務啟動。由於沒有可用的資料庫，因此可以使用 SQLite3 初始化資料庫。建立一個類似 `gitea` 的目錄，並將以下內容粘貼到名為 `docker-compose.yml` 的文件中。請注意，該卷應由設定文件中指定的 UID/GID 的使用者/組擁有。如果您不授予卷正確的權限，則容器可能無法啟動。另請注意，標籤 `:latest` 將安裝當前的開發版本。對於穩定的發行版，您可以使用 `:1` 或指定某個發行版，例如 `@dockerVersion@`。
最簡單的設定只是建立一個卷和一個網路，然後將 `docker.gitea.com/gitea:latest` 鏡像作為服務啟動。由於沒有可用的資料庫，因此可以使用 SQLite3 初始化資料庫。建立一個類似 `gitea` 的目錄，並將以下內容粘貼到名為 `docker-compose.yml` 的文件中。請注意，該卷應由設定文件中指定的 UID/GID 的使用者/組擁有。如果您不授予卷正確的權限，則容器可能無法啟動。另請注意，標籤 `:latest` 安裝的是最新的穩定版本。對於穩定的發行版，您也可以使用 `:1` 或指定某個發行版，例如 `@dockerVersion@`。如果您想使用最新的開發版本，則可以使用 `:main-nightly` 標籤；如果您想運行發佈分支的最新提交，可以使用 `:1.x-nightly` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.27-nightly`）。
```yaml
version: "3"
i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/actions/comparison.md
+47 -70
View File
@@ -6,120 +6,97 @@ sidebar_position: 15
# 與GitHub Actions的對比
儘管Gitea Actions旨在與GitHub Actions相容，但它們之間存在一些差異。
Gitea Actions 旨在與 GitHub Actions 相容，差異如下。
## 額外功能
<a id="absolute-action-urls"></a>
### Action URL絕對路徑
Gitea Actions支援通過URL絕對路徑定義actions，這意味著您可以使用來自任何Git儲存庫的Actions。
例如，`uses: https://github.com/actions/checkout@v4`或`uses: http://your_gitea.com/owner/repo@branch`。
`uses:` 接受指向任意 Git 主機的絕對 URL，例如 `uses: https://gitea.com/actions/checkout@v4`。
<a id="action-prefixes"></a>
### Action 前綴
`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
Gitea Actions支援使用Go編寫Actions。
請參閱[建立Go Actions](https://blog.gitea.com/creating-go-actions/)。
請參閱[建立 Go Actions](https://blog.gitea.com/creating-go-actions/)。
### 支援非標準的調度語法 @yearly, @monthly, @weekly, @daily, @hourly
Github Actions 不支援這些語法，詳見： https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
`schedule` 也接受 `@yearly`、`@monthly`、`@weekly`、`@daily` 和 `@hourly`，[GitHub 則不支援](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
## 不支援的工作流語法
### `concurrency`
這是用於一次運行一個Job。
請參閱[使用併發](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。
Gitea Actions目前不支援此功能。
### `run-name`
這是工作流生成的工作流運行的名稱。
請參閱[GitHub Actions 的工作流語法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
Gitea Actions目前不支援此功能。
### `permissions`和`jobs.<job_id>.permissions`
請參閱[GitHub Actions的工作流語法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
Gitea Actions目前不支援此功能。
### `jobs.<job_id>.timeout-minutes`
請參閱[GitHub Actions的工作流語法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。
Gitea Actions目前不支援此功能。
### `jobs.<job_id>.continue-on-error`
請參閱[GitHub Actions的工作流語法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
Gitea Actions目前不支援此功能。
### `jobs.<job_id>.environment`
請參閱[GitHub Actions的工作流語法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
Gitea Actions 目前不支援此功能。
[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) 會被忽略。
### 複雜的`runs-on`
請參閱[GitHub Actions的工作流語法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) 支援：
Gitea Actions目前只支援`runs-on: xyz`或`runs-on: [xyz]`。
### `hashFiles`表達式
請參閱[表達式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。
Gitea Actions目前不支援此功能，如果使用它，結果將始終為空字符串。
作為解決方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。
- 靜態字串：`runs-on: self-hosted`
- 標籤陣列：`runs-on: [linux, self-hosted]`
- 字串表達式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
- 包含表達式的陣列：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
## 缺失的功能
### 套件儲存庫授權
`GITEA_TOKEN` 無法發佈到其所屬儲存庫的套件註冊表，例如無法推送 OCI 鏡像。
請改用個人存取權杖，參見[這個工單](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
### 問題匹配器
問題匹配器是一種掃描Actions輸出以查找指定正則表達式模式並在使用者介面中突出顯示該資訊的方法。
請參閱[問題匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
Gitea Actions目前不支援此功能。
[問題匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)會被忽略。
### 為錯誤建立註釋
請參閱[為錯誤建立註釋](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。
Gitea Actions目前不支援此功能。
[錯誤註釋](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)會被忽略。
### 表達式
對於 [表達式](https://docs.github.com/en/actions/learn-github-actions/expressions), 當前僅 [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) 被支援。
[表達式](https://docs.github.com/en/actions/learn-github-actions/expressions)支援 GitHub 的標準函式與上下文。
## 缺失的UI功能
### 預處理和後處理步驟
預處理和後處理步驟在Job日誌使用者介面中沒有自己的使用者介面。
預處理和後處理步驟在 Job 日誌中沒有各自獨立的區塊。
### 服務步驟
服務步驟在Job日誌使用者介面中沒有自己的使用者介面。
服務步驟在 Job 日誌中沒有各自獨立的區塊。
## 不一樣的行為
### `permissions`和`jobs.<job_id>.permissions`
`permissions` 和 `jobs.<job_id>.permissions` 控制 `GITEA_TOKEN` 的權限，其權限受儲存庫與所有者設定的限制，對於來自 fork 的拉取請求和跨儲存庫存取還會進一步受限。
不支援 `statuses`、`checks`、`deployments`、`id-token`、`security-events` 和 `pages` 等 GitHub 專屬範圍，而 Gitea 另外提供 `code`、`releases`、`wiki` 和 `projects`。
請參閱 [Actions Job 令牌權限](token-permissions.md)。
### 下載Actions
當 `[actions].DEFAULT_ACTIONS_URL` 保持預設值為 `github` 時，Gitea將會從 https://github.com 下載相對路徑的actions。比如：
如果你使用 `uses: actions/checkout@v4`，Gitea將會從 https://github.com/actions/checkout.git 下載這個 actions 專案。
如果你想要從另外一個 Git服務下載actions，你只需要使用絕對URL `uses: https://gitea.com/actions/checkout@v4` 來下載。
如果你的 Gitea 實例是部署在一個互聯網限制的網路中，也可以使用絕對地址來下載 actions。你也可以將設定項修改為 `[actions].DEFAULT_ACTIONS_URL = self`。這樣所有的相對路徑的actions引用，將不再會從 github.com 去下載，而會從這個 Gitea 實例自己的儲存庫中去下載。例如： `uses: actions/checkout@v4` 將會從 `[server].ROOT_URL`/actions/checkout.git 這個地址去下載 actions。
設定`[actions].DEFAULT_ACTIONS_URL`進行設定。請參閱[設定備忘單](../../administration/config-cheat-sheet.md#actions-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)和[相對於工作流的 Actions](#workflow-relative-actions)。
### 上下文可用性
不檢查上下文可用性，因此您可以在更多地方使用env上下文。
請參閱[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
不檢查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此 `env` 等上下文可以在更多地方使用。
i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/actions/design.md
+4 -5
View File
@@ -19,7 +19,7 @@ Gitea Runner部分基於[nektos/act](https://github.com/nektos/act)的硬分支
之前，我們提到工作流文件中的 `runs-on: ubuntu-latest` 表示該Job將在具有`ubuntu-latest`標籤的Runner上運行。
但是，Runner如何知道要運行 `ubuntu-latest`？答案在於將標籤映射到環境。
這就是為什麼在註冊過程中添加自訂標籤時，需要輸入一些複雜內容，比如`my_custom_label:docker://centos:7`。
這就是為什麼Runner的每個標籤都指定了一個環境，比如`my_custom_label:docker://centos:7`。
這意味著Runner可以接受需要在`my_custom_label`上運行的Job，並通過使用`centos:7`鏡像的Docker容器來運行它。
然而，Docker不是唯一的選擇。
@@ -35,7 +35,6 @@ Runner 也支援直接在主機上運行Job。
- `my_custom_label:docker://node:18`：使用`node:18 Docker`鏡像運行帶有`my_custom_label`標籤的Job。
- `my_custom_label:host`：在主機上直接運行帶有`my_custom_label`標籤的Job。
- `my_custom_label`：等同於`my_custom_label:host`。
- `my_custom_label:vm:ubuntu-latest`：（僅為範例，未實現）使用帶有`ubuntu-latest` ISO的虛擬機運行帶有`my_custom_label`標籤的Job。
## 通信協議
@@ -44,7 +43,7 @@ Runner 也支援直接在主機上運行Job。
相反，我們希望重用HTTP端口，這意味著我們需要一個與HTTP相容的協議。
因此，我們選擇使用基於HTTP的gRPC。
我們使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 進行連接。
協議定義於[actions-proto-def](https://gitea.com/gitea/actions-proto-def)，其Go程式碼位於[actionslib](https://gitea.com/gitea/actionslib)。
有關 gRPC 的更多資訊，請前往[其官方網站](https://grpc.io/)。
## 網路架構
@@ -72,8 +71,8 @@ Runner 必須能夠連接到Gitea以接收任務併發送執行結果回來。
### 連接 3，runner到互聯網
當您使用諸如 `actions/checkout@v4` 的一些Actions時，runner 下載的是腳本，而不是Job容器。
預設情況下，它從[github.com](http://github.com/)下載，因此需要訪問互聯網。如果您設定的是 self，
那麼預設將從您的當前Gitea實例下載，那麼此步驟不需要連接到互聯網。
預設情況下，它從[github.com](https://github.com/)下載，因此需要訪問互聯網。
若將`DEFAULT_ACTIONS_URL`設定為`self`，或使用`uses: self:owner/repo@ref`，則改從您的Gitea實例下載。
它還預設從Docker Hub下載一些Docker鏡像，這也需要互聯網訪問。
然而，互聯網訪問並不是絕對必需的。
i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/actions/faq.md
+22 -69
View File
@@ -27,34 +27,19 @@ DEFAULT_REPO_UNITS = ...,repo.actions
## 使用`actions/checkout@v4`等Actions時，Job容器會從何處下載腳本？
GitHub 上有成千上萬個 [Actions 腳本](https://github.com/marketplace?type=actions)。
當您編寫 `uses: actions/checkout@v4` 時，它預設會從 [github.com/actions/checkout](https://github.com/actions/checkout) 下載腳本。
那如果您想使用一些託管在其它平台上的腳本呢，比如在 gitea.com 上的？
預設從 `https://github.com` 下載，若 `[actions].DEFAULT_ACTIONS_URL` 為 `self`，則從您自己的實例下載，參見[設定速查表](../../administration/config-cheat-sheet.md#actions-actions)。
好消息是，您可以指定要從任何位置使用Actions的URL前綴。
這是Gitea Actions中的額外語法。
例如：
若要使用其他來源的 Action，請指定其主機：
- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: https://github.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/xxx@xxx`
注意，`https://`或`http://`前綴是必需的！
這是與 GitHub Actions 的一個區別，GitHub Actions 只允許使用託管在 GitHub 上的 actions 腳本。
但使用者理應擁有權利去靈活決定如何運行 Actions。
另外，如果您希望您的 Runner 預設從您自己的 Gitea 實例下載 Actions，可以透過設定 `[actions].DEFAULT_ACTIONS_URL`進行設定。
參見[設定速查表](../../administration/config-cheat-sheet.md#actions-actions)。
- `uses: https://gitea.com/owner/repo@ref`
- `uses: http://your_gitea_instance.com/owner/repo@ref`
- `uses: self:owner/repo@ref`，用於您自己的 Gitea 實例
## 如何限制Runner的權限？
Runner僅具有連接到您的Gitea實例的權限。
當任何Runner接收到要運行的Job時，它將臨時獲得與Job關聯的儲存庫的有限權限。
如果您想為Runner提供更多權限，允許它訪問更多私有儲存庫或外部系統，您可以向其傳遞[密鑰](usage/actions/secrets.md)。
對於 Actions 的細粒度權限控制是一項複雜的工作。
在未來，我們將添加更多選項以使Gitea更可設定，例如允許對儲存庫進行更多寫訪問或對同一組織中的所有儲存庫進行讀訪問。
Runner 只會連接到您的 Gitea 實例。
對於每個 Job，Runner 會取得一個僅限於該 Job 所屬儲存庫的 `GITEA_TOKEN`，參見 [Actions Job 令牌權限](token-permissions.md)。
若要讓 Job 存取更多私有儲存庫或外部系統，請向其傳遞[密鑰](usage/actions/secrets.md)。
## 如何避免被黑客攻擊？
@@ -75,19 +60,8 @@ Runner僅具有連接到您的Gitea實例的權限。
## runner支援哪些操作系統？
它在Linux、macOS和Windows上運行良好。
雖然理論上支援其他操作系統，但需要進一步測試。
需要注意的一點是，如果選擇直接在主機上運行Job而不是在Job容器中運行，操作系統之間的環境差異可能會導致意外的失敗。
例如，在大多數情況下，Windows上沒有可用的bash，而act嘗試預設使用bash運行腳本。
因此，您需要在工作流文件中將預設shell指定為`powershell`，參考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。
```yaml
defaults:
run:
shell: powershell
```
官方發佈了 Linux、macOS 和 Windows 的二進制檔案。
理論上，Go 和 Docker 支援的其他系統也能運作。
## 為什麼選擇GitHub Actions？為什麼不選擇與GitLab CI/CD相容的工具？
@@ -99,42 +73,13 @@ defaults:
## 如果它在多個標籤上運行，例如 `runs-on: [label_a, label_b]`，會發生什麼？
這是有效的語法。
它意味著它應該在具有`label_a` **和** `label_b`標籤的Runner上運行，參考[GitHub Actions的工作流語法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
不幸的是，runner 並不支援這種方式。
如上所述，我們將標籤映射到環境：
- `ubuntu` → `ubuntu:22.04`
- `centos` → `centos:8`
但我們需要將標籤組映射到環境，例如：
- `[ubuntu]` → `ubuntu:22.04`
- `[with-gpu]` → `linux:with-gpu`
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
我們還需要重新設計任務分配給Runner的方式。
具有`ubuntu`、`centos`或`with-gpu`的Runner並不一定表示它可以接受`[centos, with-gpu]`的Job。
因此，Runner應該通知Gitea實例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
這不是一個技術問題，只是在早期設計中被忽視了。
參見[runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
目前， runner嘗試匹配標籤中的每一個，並使用找到的第一個匹配項。
Job 會在具有所有這些標籤的 Runner 上運行，與 [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) 相同。
Runner 會使用它所具有的第一個標籤對應的環境。
## 代理標籤和自訂標籤對於Runner有什麼區別？
![labels](/images/usage/actions/labels.png)
代理標籤是由Runner在註冊過程中向Gitea實例報告的。
而自訂標籤則是由Gitea的管理員或組織或儲存庫的所有者手動添加的（取決於Runner所屬的級別）。
然而，目前這方面的設計還有待改進，因為它目前存在一些不完善之處。
您可以向已註冊的Runner添加自訂標籤，比如 `centos`，這意味著該Runner將接收具有`runs-on: centos`的Job。
然而，Runner可能不知道要使用哪個環境來執行該標籤，導致它使用預設鏡像或導致邏輯死衚衕。
這個預設值可能與使用者的期望不符。
參見[runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
與此同時，如果您想更改Runner的標籤，我們建議您重新註冊Runner。
Gitea 已不再有自訂標籤。
Runner 每次啟動時都會宣告其標籤，標籤來自 `runner.labels` 設定或註冊時指定的標籤，因此請在那裡修改並重新啟動 Runner。
## Gitea Actions runner會有更多的實現嗎？
@@ -165,3 +110,11 @@ defaults:
> 對於 `pull_request` 事件，在 [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) 中 `ref` 是 `refs/pull/:prNumber/merge`，它指向這個拉取請求合併提交的一個預覽。但是 Gitea 沒有這種 reference。
> 因此，Gitea Actions 中 `ref` 是 `refs/pull/:prNumber/head`，它指向這個拉取請求的頭分支而不是合併提交的預覽。
## 如何共享私有儲存庫中的 Actions 和可重複使用的工作流？
前往儲存庫的**設定** > **Actions** > **General** 頁面，添加協作所有者。
協作所有者的私有儲存庫可以存取目前儲存庫中的 Actions 和工作流。
若要在同一使用者或組織內共享，請改為在該使用者或組織的**設定** > **Actions** > **General** > **Cross-Repository Access** 中添加這些私有儲存庫。
參見[跨儲存庫存取](token-permissions.md#cross-repository-access)。
i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/actions/scoped-workflows.md
+2 -2
View File
@@ -102,8 +102,8 @@ SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
作用域工作流程可以呼叫可重複使用的工作流程：
- **本機**參照（`uses: ./...`）會相對於**來源**儲存庫解析：即呼叫方工作流程內容的來源儲存庫，而非消費方儲存庫。
- **跨儲存庫**參照（`uses: owner/repo/...@ref`）會以**消費方儲存庫的**讀取權限來解析。如果它指向一個私有儲存庫，請確保每個消費方儲存庫都能讀取它，否則工作流程會在那裡失敗。
- **本機**參照（`uses: ./...` 或 `uses: $/...`）會相對於**來源**儲存庫解析：即呼叫方工作流程內容的來源儲存庫，而非消費方儲存庫。
- **跨儲存庫**參照（`uses: owner/repo/...@ref` 或 `uses: self:owner/repo/...@ref`）會以**消費方儲存庫的**讀取權限來解析。如果它指向一個私有儲存庫，請確保每個消費方儲存庫都能讀取它，否則工作流程會在那裡失敗。
可重複使用的工作流程可以放在來源儲存庫的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。
i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/actions/token-permissions.md
+126
View File
@@ -0,0 +1,126 @@
---
date: "2026-03-19T00:00:00+01:00"
slug: "token-permissions"
sidebar_position: 30
---
# Actions Job 令牌權限（`GITEA_TOKEN`）
每個 Actions Job 都會取得一個內建令牌（`GITEA_TOKEN`），可用於存取 Gitea（透過 HTTP(S) 使用 Git、API 請求等）。
本頁說明 Gitea 如何決定該令牌可以執行哪些操作。
在工作流中，可以透過 `${{ secrets.GITEA_TOKEN }}` 使用它。這些設定和 `permissions:` 只影響 `GITEA_TOKEN`（不影響個人存取權杖等其他密鑰）。API 呼叫請參閱 [API 認證](../../development/api-usage.md#authentication)。
<a id="where-permissions-come-from"></a>
## 權限的來源
Gitea 依以下順序決定 Job 令牌權限：
1. Job 層級的 `permissions:`（`jobs.<job_id>.permissions`）
2. 工作流層級的 `permissions:`（頂層）
3. 設定中的預設權限（所有者或儲存庫）
接著，結果會再受到所設定的最大令牌權限**限縮**（見下文）。
<a id="supported-workflow-syntax"></a>
## 支援的工作流語法
Gitea 支援與 GitHub Actions 相容的 `permissions:` 關鍵字。
<a id="scalar-values"></a>
### 純量值
```yaml
permissions: read-all # or: write-all
```
<a id="scoped-mapping"></a>
### 依範圍對應
```yaml
permissions:
contents: read
issues: write
pull-requests: none
```
每個範圍的有效存取模式值為 `read`、`write` 和 `none`。
<a id="supported-scopes"></a>
### 支援的範圍
- `contents`（適用於 `code` 和 `releases`）
- `code`
- `releases`
- `issues`
- `pull-requests`
- `actions`
- `wiki`
- `projects`
- `packages`（若目標功能支援）
如果同時指定 `contents` 和更細的範圍（例如 `code` 或 `releases`），該單元以更細的範圍為準。
<a id="compatibility-notes"></a>
### 相容性說明
Gitea 支援 GitHub Actions 權限範圍的一個子集。
Gitea Actions 目前不支援 `statuses`、`checks`、`deployments`、`id-token`、`security-events` 和 `pages` 等 GitHub 專屬範圍。
Gitea 另外提供一些儲存庫單元範圍，它們在 GitHub Actions 中並不是獨立的範圍：
- `code`
- `releases`
- `wiki`
- `projects`
<a id="default-permission-mode"></a>
## 預設權限模式
如果工作流和 Job 都沒有定義 `permissions:`，Gitea 會使用所設定的預設模式：
- **Permissive**（寬鬆）：對 Job 所屬儲存庫的大多數單元具有讀取和寫入權限（向下相容的預設值）。
- **受限**（Restricted）：對 Job 所屬儲存庫的 `code`、`releases` 和 `packages` 具有唯讀權限，預設無法存取其他單元。
<a id="maximum-token-permissions-clamping"></a>
## 最大令牌權限（限縮）
您可以為每個儲存庫單元設定最大權限。
Job 的實際權限計算方式如下：
`effective = min(requested, maximum)`
也就是說，工作流可以降低 Job 的權限，但不能超過您所設定的最大值。
如果未設定最大值，所有範圍的最大值預設為 `write`。
<a id="where-to-configure"></a>
## 設定位置
您可以在以下位置設定預設值和最大值：
- **使用者 / 組織**：`Settings` → `Actions` → `General`
- **儲存庫**：`Settings` → `Actions` → `General`
- 對於組織內的儲存庫，儲存庫可以沿用所有者層級的設定，或透過 **Override owner-level configuration** 選擇退出。
注意：只有在啟用**儲存庫 Actions** 後，才會顯示儲存庫層級的令牌權限設定。
<a id="fork-pull-requests"></a>
## 來自 fork 的拉取請求
基於安全考量，由來自 fork 的拉取請求觸發的工作流，對儲存庫內容一律只有唯讀權限，不受工作流 `permissions:` 或設定影響。
<a id="cross-repository-access"></a>
## 跨儲存庫存取
預設情況下，`GITEA_TOKEN` 只能存取：
- Job 所屬的儲存庫（依計算出的權限）
- 公開儲存庫（唯讀）
預設會拒絕存取其他私有儲存庫。
使用者或組織可以在**設定** > **Actions** > **General** > **Cross-Repository Access** 中，允許唯讀存取選定的私有儲存庫。
私有儲存庫也可以在**設定** > **Actions** > **General** 中允許選定的協作所有者。
這樣，這些所有者的私有儲存庫就能為了 Actions 用途讀取目前的私有儲存庫，例如私有 Actions 和可重複使用的工作流。
由來自 fork 的拉取請求觸發的工作流，永遠無法取得對私有儲存庫的跨儲存庫存取權，即使這些儲存庫已列入清單也一樣。
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.22/administration/config-cheat-sheet.md
+1 -1
View File
@@ -974,7 +974,7 @@ Gitea 建立以下非唯一隊列：
- `ENABLED`: **false**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於設定多長時間進行檢查。
- `OLDER_THAN`: **8760h**: 早於此表達式的任何系統通知都將從資料庫中刪除。
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.24/administration/config-cheat-sheet.md
+1 -1
View File
@@ -990,7 +990,7 @@ Gitea 建立以下非唯一隊列：
- `ENABLED`: **false**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於設定多長時間進行檢查。
- `OLDER_THAN`: **8760h**: 早於此表達式的任何系統通知都將從資料庫中刪除。
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.25/administration/config-cheat-sheet.md
+1 -1
View File
@@ -991,7 +991,7 @@ Gitea 建立以下非唯一隊列：
- `ENABLED`: **false**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於設定多長時間進行檢查。
- `OLDER_THAN`: **8760h**: 早於此表達式的任何系統通知都將從資料庫中刪除。
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.26/administration/config-cheat-sheet.md
+7 -7
View File
@@ -1106,7 +1106,7 @@ In-Reply-To =
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 設定為 false 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於安排任務，例如 `@every 168h`。
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用於檢查新版本的端點。
@@ -1114,7 +1114,7 @@ In-Reply-To =
- `ENABLED`: **false**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於設定多長時間進行檢查。
- `OLDER_THAN`: **8760h**: 早於此表達式的任何系統通知都將從資料庫中刪除。
@@ -1135,35 +1135,35 @@ In-Reply-To =
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@annually**: Cron 語法，用於設定重建索引的頻率。
#### Cron - 停止長時間未更新的運行中任務 (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 5m**: Cron 語法，用於設定檢查的頻率。
#### Cron - 停止持續更新但長時間未結束的運行中任務 (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 30m**: Cron 語法，用於設定檢查的頻率。
#### Cron - 取消長時間未被領取的任務 (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 6h**: Cron 語法，用於設定檢查的頻率。
#### Cron - 啟動基於定時的 Actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 1m**: Cron 語法，用於設定調度任務的頻率。
## Git (`git`)
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.27/administration/config-cheat-sheet.md
+7 -7
View File
@@ -1111,7 +1111,7 @@ In-Reply-To =
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 設定為 false 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於安排任務，例如 `@every 168h`。
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用於檢查新版本的端點。
@@ -1119,7 +1119,7 @@ In-Reply-To =
- `ENABLED`: **false**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 168h**: Cron 語法，用於設定多長時間進行檢查。
- `OLDER_THAN`: **8760h**: 早於此表達式的任何系統通知都將從資料庫中刪除。
@@ -1140,35 +1140,35 @@ In-Reply-To =
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@annually**: Cron 語法，用於設定重建索引的頻率。
#### Cron - 停止長時間未更新的運行中任務 (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 5m**: Cron 語法，用於設定檢查的頻率。
#### Cron - 停止持續更新但長時間未結束的運行中任務 (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **true**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 30m**: Cron 語法，用於設定檢查的頻率。
#### Cron - 取消長時間未被領取的任務 (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 6h**: Cron 語法，用於設定檢查的頻率。
#### Cron - 啟動基於定時的 Actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: 啟用服務。
- `RUN_AT_START`: **false**: 在啟動時運行任務（如果啟用）。
- `NO_SUCCESS_NOTICE`: **false**: 設定為 true 以關閉成功通知。
- `NOTICE_ON_SUCCESS`: **false**: 設定為 true 以打開成功通知。
- `SCHEDULE`: **@every 1m**: Cron 語法，用於設定調度任務的頻率。
## Git (`git`)
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.27/administration/reverse-proxies.md
+61 -15
View File
@@ -14,6 +14,7 @@ aliases:
2. 將 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
3. 確保反向代理不會解碼 URI。`https://git.example.com/a%2Fb`的請求應該被傳遞給 `http://gitea:3000/a%2Fb`。
4. 確保 `Host` 和 `X-Forwarded-Proto` 頭被正確的傳遞給 Gitea，使 Gitea 可以看到正在訪問的真實 URL。
5. 確保 Web 伺服器有完整的憑證（包括所有中間憑證和根憑證），以便 `git clone` 和 `git pull` 正常工作。
## 使用子路徑
@@ -61,7 +62,7 @@ server {
# 確保 nginx 使用未轉義 URI， 按原樣保持 "%2F"。 確保 nginx 去除 "/gitea" 子路徑前綴， 按原樣傳遞 "/v2"。
rewrite ^ $request_uri;
rewrite ^(/gitea)?(/.*) $2 break;
rewrite ^/(gitea($|/))?(.*) /$3 break;
proxy_pass http://127.0.0.1:3000$uri;
# 其他的常規 HTTP 表頭，見上面“使用 Nginx 作為反向代理服務”小節的配置
@@ -75,7 +76,7 @@ server {
}
```
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://git.example.com/git/` 的設定項。
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://git.example.com/gitea/` 的設定項。
## 使用 Nginx 直接提供靜態資源
@@ -144,6 +145,20 @@ server {
}
```
## Nginx Proxy Manager
如果使用 Nginx Proxy Manager 作為 Gitea 的反向代理，設定與原生 Nginx 略有不同。
它會[預設給自訂 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 設定裡對應的指令不要再寫一遍。否則會因為指令重複（尤其是 `proxy_set_header Host $host`）出現 `400 bad request`。
建立 `/` 自訂 location 時，只需在其設定中加入：
```nginx
client_max_body_size 512M;
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
```
## 使用 Apache HTTPD 作為反向代理服務
如果您想使用 Apache HTTPD 作為 Gitea 的反向代理服務，您可以為您的 Apache HTTPD 作如下設定（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：
@@ -161,23 +176,12 @@ server {
注：必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`
如果希望用 Let's Encrypt 的 webroot 驗證，請在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把這些請求代理到 Gitea。
## 使用 Apache HTTPD 作為反向代理服務並將 Gitea 路由至一個子路徑
如果您已經有一個域名並且想與 Gitea 共享該域名，您可以增加以下設定為 Gitea 添加路由規則（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：
```
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
ProxyPass /git http://localhost:3000 nocanon
</VirtualHost>
```
```apacheconf
<VirtualHost *:80>
...
@@ -197,6 +201,48 @@ server {
注：必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`
## 使用 Apache HTTPD 直接提供靜態資源
我們可以通過將資源分為靜態和動態兩種類型來調節性能。
CSS 文件、JavaScript 文件、圖片和字體是靜態內容。首頁、倉庫視圖和工單列表是動態內容。
Apache HTTPD 可以直接提供靜態資源，並且只代理動態資源請求給 Gitea。
將 Gitea 源代碼倉庫的一個快照下載到 `/path/to/gitea/`。
在此之後，在本地倉庫目錄運行 `make frontend` 來生成靜態資源。在這個情況下，我們只對 `public/` 目錄感興趣，您可以刪除剩下的其他目錄。
（為了生成靜態資源，您需要安裝一個[帶 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取決於您的用戶量的大小，您可以將流量分離到兩個不同的服務器，或者為靜態資源設定一個 cdn。
### 單伺服器節點，單域名
將 `[server] STATIC_URL_PREFIX = /_/static` 寫入您的 Gitea 設定文件：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory /path/to/gitea/public/>
Options FollowSymlinks
AllowOverride None
Require all granted
</Directory>
AllowEncodedSlashes NoDecode
# 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
ProxyPass / http://localhost:3000/ nocanon
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
## 使用 Caddy 作為反向代理服務
如果您想使用 Caddy 作為 Gitea 的反向代理服務，您可以在 `Caddyfile` 中添加如下設定：
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.27/installation/with-docker-rootless.md
+1 -1
View File
@@ -53,7 +53,7 @@ sudo chown 1000:1000 config/ data/
> 如果未為卷設定正確的權限，容器可能無法啟動。
對於穩定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的開發版本，則可以使用 `:dev-rootless` 標籤。如果您想運行發佈分支的最新提交，可以使用 `:1.x-dev-rootless` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.16-dev-rootless`）。
對於穩定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的開發版本，則可以使用 `:main-nightly-rootless` 標籤。如果您想運行發佈分支的最新提交，可以使用 `:1.x-nightly-rootless` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.27-nightly-rootless`）。
## 自訂端口
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.27/installation/with-docker.md
+1 -1
View File
@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 組織內提供自動更新的 Docker 鏡像。可以始
## 基本
最簡單的設定只是建立一個卷和一個網路，然後將 `docker.gitea.com/gitea:latest` 鏡像作為服務啟動。由於沒有可用的資料庫，因此可以使用 SQLite3 初始化資料庫。建立一個類似 `gitea` 的目錄，並將以下內容粘貼到名為 `docker-compose.yml` 的文件中。請注意，該卷應由設定文件中指定的 UID/GID 的使用者/組擁有。如果您不授予卷正確的權限，則容器可能無法啟動。另請注意，標籤 `:latest` 將安裝當前的開發版本。對於穩定的發行版，您可以使用 `:1` 或指定某個發行版，例如 `@dockerVersion@`。
最簡單的設定只是建立一個卷和一個網路，然後將 `docker.gitea.com/gitea:latest` 鏡像作為服務啟動。由於沒有可用的資料庫，因此可以使用 SQLite3 初始化資料庫。建立一個類似 `gitea` 的目錄，並將以下內容粘貼到名為 `docker-compose.yml` 的文件中。請注意，該卷應由設定文件中指定的 UID/GID 的使用者/組擁有。如果您不授予卷正確的權限，則容器可能無法啟動。另請注意，標籤 `:latest` 安裝的是最新的穩定版本。對於穩定的發行版，您也可以使用 `:1` 或指定某個發行版，例如 `@dockerVersion@`。如果您想使用最新的開發版本，則可以使用 `:main-nightly` 標籤；如果您想運行發佈分支的最新提交，可以使用 `:1.x-nightly` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.27-nightly`）。
```yaml
version: "3"
package.json
+1 -1
View File
@@ -13,5 +13,5 @@
"engines": {
"node": ">=22"
},
"packageManager": "pnpm@11.22.0"
"packageManager": "pnpm@12.4.2"
}
packages/content-loader/package.json
+1 -1
View File
@@ -11,7 +11,7 @@
},
"dependencies": {
"tinyglobby": "0.2.17",
"yaml": "2.9.0"
"yaml": "2.9.1"
},
"peerDependencies": {
"astro": "^7.0.2"
packages/content-loader/src/products.ts
+1 -1
View File
@@ -82,7 +82,7 @@ const variables: Record<string, VersionVariables> = {
version: 'main-nightly',
sourceVersion: 'main',
sourceBranch: 'main',
dockerVersion: 'nightly',
dockerVersion: 'main-nightly',
displayVersion: '1.28-dev',
},
'1.27': {
pnpm-lock.yaml
Generated
+573 -1256
View File
File diff suppressed because it is too large. Load diff
pnpm-workspace.yaml
-1
View File
@@ -7,5 +7,4 @@ dedupePeerDependents: false
updateNotifier: false
ignoreScripts: true
minimumReleaseAge: 0
confirmModulesPurge: false
verifyDepsBeforeRun: false
runner-docs/configuration.md
+1 -1
View File
@@ -106,7 +106,7 @@ Applies to jobs that run in containers.
| `force_rebuild` | `false` | rebuild local action images even when present. |
| `require_docker` | `false` | always require a reachable daemon, even for host-only labels. |
| `docker_timeout` | `0s` | how long to wait for the daemon to become reachable. |
| `bind_workdir` | `false` | bind-mount the workspace from the host instead of using a docker volume. Needed for jobs that use `docker compose` with bind mounts under Docker-in-Docker. The parent directory must then be mounted into the runner container and listed in `valid_volumes`. |
| `bind_workdir` | `false` | bind-mount the workspace from the host instead of using a docker volume, so jobs can bind-mount it by its own path into containers they start (`.:/app` in `docker compose`). Not needed when workflows use `GITEA_DOCKER_WORKSPACE`. The parent directory must then be mounted into the runner container. |
:::note Privileged mode and workflow container options
A workflow's own `jobs.<job_id>.container.options` are untrusted input. While `container.privileged` is disabled, the options that would break out of the container are stripped with a warning in the job log: `--pid`, `--ipc`, `--uts`, `--cgroupns`, `--userns`, `--cap-add`, `--security-opt`, `--device`, `--device-cgroup-rule`, `--gpus`, `--volumes-from`, `--runtime`, `--cgroup-parent` and `--sysctl`. They are honoured once privileged mode is enabled, because the operator has then opted into host access.
runner-docs/monitoring.md
+10
View File
@@ -40,6 +40,16 @@ All series are prefixed with `gitea_runner_`, among them:
Useful things to alert on: `gitea_runner_poll_fetch_total{result="error"}` rising (the instance is unreachable or the runner was deleted), a `capacity_utilization_ratio` pinned at `1` (the pool is too small), and a growing `report_log_buffer_rows` (log delivery is falling behind).
## OpenTelemetry tracing
Setting `OTEL_EXPORTER_OTLP_ENDPOINT` in the runner's environment sends a trace of every job, with a span per step, to an OTLP collector over `http/protobuf`:
```sh
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
```
Jobs receive `TRACEPARENT`, so instrumented tools in them join the job's trace. See [docs/telemetry.md](https://gitea.com/gitea/runner/src/branch/main/docs/telemetry.md) for headers, sampling and the security notes.
## Local health checks
Health checks let a runner take itself out of rotation when the machine it runs on is not fit for work — most commonly when the disk is full.
runner-docs/reference/cli.md
+3 -1
View File
@@ -103,13 +103,15 @@ Flags:
--detect-event Use first event type from workflow as event that triggered the workflow
-C, --directory string working directory (default ".")
-n, --dryrun dryrun mode
--env stringArray env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv)
--env stringArray env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv; override env-file)
--env-file string environment file to read and use as env in the containers (default ".env")
-E, --event string run a event name
-e, --eventpath string path to a JSON event payload file exposed as the event that triggered the workflow
--gitea-instance string Gitea instance to use.
-h, --help help for exec
-i, --image string Docker image to use. Use "-self-hosted" to run directly on the host. (default "docker.gitea.com/runner-images:ubuntu-latest")
--input stringArray set an input the workflow declares under its workflow_dispatch or workflow_call trigger, others stay invisible to the inputs context (e.g. --input name=bar; can be specified multiple times with highest precedence)
--input-file string path to an .env-format file containing key=value pairs as baseline workflow inputs (override event inputs)
--insecure-secrets NOT RECOMMENDED! Doesn't hide secrets while printing logs.
-j, --job string run a specific job ID; when several workflow files define that job, also pass --workflows/-W to select the file
--json Output logs in json format
runner-docs/reference/config-example.md
+20 -15
View File
@@ -68,11 +68,12 @@ runner:
# scratch directories (left behind when a host cleanup delete stalls) older than
# this duration. Setting either workdir_cleanup_age or idle_cleanup_interval to 0
# (or any non-positive value) disables stale-directory cleanup entirely, along with
# the docker network cleanup below.
# the docker network and volume cleanup below.
#workdir_cleanup_age: 24h
# Cadence for the idle cleanup pass. Besides the directories above, on runners that use
# docker it removes the per-job networks of jobs this runner did not live to tear down,
# which would otherwise hold a subnet of the daemon address pool until the host is rebuilt.
# docker it removes the per-job networks and volumes of jobs this runner did not live to
# tear down, which would otherwise hold a subnet of the daemon address pool and the job's
# workspace contents until the host is rebuilt.
#idle_cleanup_interval: 10m
# The base interval for periodic log flush to the Gitea instance.
# Logs may be sent earlier if the buffer reaches log_report_batch_size
@@ -86,7 +87,7 @@ runner:
# This ensures bursty output (e.g., npm install) is delivered promptly.
#log_report_batch_size: 100
# The interval for reporting task state (step status, timing) to the Gitea instance.
# State is also reported immediately on step transitions (start/stop).
# State is also reported on step transitions (start/stop) and after each log flush.
#state_report_interval: 5s
# Per-attempt deadline for flushing the final logs and task state when a job
# finishes, on a detached context so a server cancel can't block the acknowledgement.
@@ -154,7 +155,8 @@ runner:
# job_completed: ''
cache:
# Enable the built-in cache server (used by actions/cache and similar actions).
# Enable caching (used by actions/cache and similar actions). Off means no built-in server is
# started and no job is registered with an external_server either.
#enabled: true
# Directory where cache blobs are stored on disk. Default: $HOME/.cache/actcache
# Ignored when external_server is set.
@@ -190,10 +192,11 @@ cache:
# A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit
# until its cache entry expires or is manually removed.
#offline_mode: false
# Serve the actions cache service v2 API. The actions that use it refuse any host they do not
# take for GitHub, so reaching it means editing that check out of their own bundle, undone
# whenever it is downloaded again. That edit is made either way, this only governs the API
# advertised. A bundle that does not match is left alone.
# Serve the actions cache service v2 API. The actions that use it fall back to v1 on any host
# they do not take for GitHub, so reaching it means editing that check out of their own bundle,
# put back after the copy into the job. That edit is made either way, this only governs the API
# advertised. A bundle that does not match is left alone. With v2, artifact uploads go via the
# cache server unless container jobs cannot reach its Docker network.
#v2: true
# How the cache server discards entries, ignored when external_server is set since that
# server applies its own. Leave a setting out for its default; 0s or 0 turns the three
@@ -234,6 +237,8 @@ container:
# A volume declared here replaces the one the runner would mount on the same container path, so the
# tool cache can be kept on the host. Its source must also be allowed by valid_volumes below:
# options: --volume /host/toolcache:/opt/hostedtoolcache
# With privileged disabled, options that could escape the container (--security-opt, --device,
# --cap-add, --pid, ...) are ignored in a workflow's container.options, but keep working here.
#options:
# The parent directory of a job's working directory.
# NOTE: There is no need to add the first '/' of the path as runner will add it automatically.
@@ -254,7 +259,7 @@ container:
#valid_volumes: []
# Overrides the docker client host with the specified one.
# If it's empty, runner will find an available docker host automatically.
# If it's "-", runner will find an available docker host automatically, but the docker host won't be mounted to the job containers and service containers.
# If it's "-", runner will find an available docker host automatically, but won't mount it into the job and action containers.
# If it's not empty or "-", the specified docker host will be used. An error will be returned if it doesn't work.
#docker_host: ""
# Pull docker image(s) even if already present.
@@ -269,11 +274,11 @@ container:
#require_docker: false
# Timeout to wait for the docker daemon to be reachable, if docker is required by require_docker or runner
#docker_timeout: 0s
# Bind the workspace to the host filesystem instead of using Docker volumes.
# This is required for Docker-in-Docker (DinD) setups when jobs use docker compose
# with bind mounts (e.g., ".:/app"), as volume-based workspaces are not accessible
# from the DinD daemon's filesystem. When enabled, ensure the workspace parent
# directory is also mounted into the runner container and listed in valid_volumes.
# Mount the workspace from a host directory instead of a Docker volume, so jobs
# can bind-mount it by its own path into sibling containers (".:/app" in docker
# compose). Not needed when jobs get the Docker proxy or workflows use the
# GITEA_DOCKER_WORKSPACE variable.
# The workspace parent directory must be mounted into the runner container.
#bind_workdir: false
# How long a job waits for a service container that declares a healthcheck to become
# healthy. A negative value (e.g. -1s) starts the steps without waiting.
runner-docs_versioned_docs/version-3/reference/cli.md
+3 -1
View File
@@ -103,13 +103,15 @@ Flags:
--detect-event Use first event type from workflow as event that triggered the workflow
-C, --directory string working directory (default ".")
-n, --dryrun dryrun mode
--env stringArray env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv)
--env stringArray env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv; override env-file)
--env-file string environment file to read and use as env in the containers (default ".env")
-E, --event string run a event name
-e, --eventpath string path to a JSON event payload file exposed as the event that triggered the workflow
--gitea-instance string Gitea instance to use.
-h, --help help for exec
-i, --image string Docker image to use. Use "-self-hosted" to run directly on the host. (default "docker.gitea.com/runner-images:ubuntu-latest")
--input stringArray set an input the workflow declares under its workflow_dispatch or workflow_call trigger, others stay invisible to the inputs context (e.g. --input name=bar; can be specified multiple times with highest precedence)
--input-file string path to an .env-format file containing key=value pairs as baseline workflow inputs (override event inputs)
--insecure-secrets NOT RECOMMENDED! Doesn't hide secrets while printing logs.
-j, --job string run a specific job ID; when several workflow files define that job, also pass --workflows/-W to select the file
--json Output logs in json format
runner-docs_versioned_docs/version-3/reference/config-example.md
+20 -15
View File
@@ -68,11 +68,12 @@ runner:
# scratch directories (left behind when a host cleanup delete stalls) older than
# this duration. Setting either workdir_cleanup_age or idle_cleanup_interval to 0
# (or any non-positive value) disables stale-directory cleanup entirely, along with
# the docker network cleanup below.
# the docker network and volume cleanup below.
#workdir_cleanup_age: 24h
# Cadence for the idle cleanup pass. Besides the directories above, on runners that use
# docker it removes the per-job networks of jobs this runner did not live to tear down,
# which would otherwise hold a subnet of the daemon address pool until the host is rebuilt.
# docker it removes the per-job networks and volumes of jobs this runner did not live to
# tear down, which would otherwise hold a subnet of the daemon address pool and the job's
# workspace contents until the host is rebuilt.
#idle_cleanup_interval: 10m
# The base interval for periodic log flush to the Gitea instance.
# Logs may be sent earlier if the buffer reaches log_report_batch_size
@@ -86,7 +87,7 @@ runner:
# This ensures bursty output (e.g., npm install) is delivered promptly.
#log_report_batch_size: 100
# The interval for reporting task state (step status, timing) to the Gitea instance.
# State is also reported immediately on step transitions (start/stop).
# State is also reported on step transitions (start/stop) and after each log flush.
#state_report_interval: 5s
# Per-attempt deadline for flushing the final logs and task state when a job
# finishes, on a detached context so a server cancel can't block the acknowledgement.
@@ -154,7 +155,8 @@ runner:
# job_completed: ''
cache:
# Enable the built-in cache server (used by actions/cache and similar actions).
# Enable caching (used by actions/cache and similar actions). Off means no built-in server is
# started and no job is registered with an external_server either.
#enabled: true
# Directory where cache blobs are stored on disk. Default: $HOME/.cache/actcache
# Ignored when external_server is set.
@@ -190,10 +192,11 @@ cache:
# A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit
# until its cache entry expires or is manually removed.
#offline_mode: false
# Serve the actions cache service v2 API. The actions that use it refuse any host they do not
# take for GitHub, so reaching it means editing that check out of their own bundle, undone
# whenever it is downloaded again. That edit is made either way, this only governs the API
# advertised. A bundle that does not match is left alone.
# Serve the actions cache service v2 API. The actions that use it fall back to v1 on any host
# they do not take for GitHub, so reaching it means editing that check out of their own bundle,
# put back after the copy into the job. That edit is made either way, this only governs the API
# advertised. A bundle that does not match is left alone. With v2, artifact uploads go via the
# cache server unless container jobs cannot reach its Docker network.
#v2: true
# How the cache server discards entries, ignored when external_server is set since that
# server applies its own. Leave a setting out for its default; 0s or 0 turns the three
@@ -234,6 +237,8 @@ container:
# A volume declared here replaces the one the runner would mount on the same container path, so the
# tool cache can be kept on the host. Its source must also be allowed by valid_volumes below:
# options: --volume /host/toolcache:/opt/hostedtoolcache
# With privileged disabled, options that could escape the container (--security-opt, --device,
# --cap-add, --pid, ...) are ignored in a workflow's container.options, but keep working here.
#options:
# The parent directory of a job's working directory.
# NOTE: There is no need to add the first '/' of the path as runner will add it automatically.
@@ -254,7 +259,7 @@ container:
#valid_volumes: []
# Overrides the docker client host with the specified one.
# If it's empty, runner will find an available docker host automatically.
# If it's "-", runner will find an available docker host automatically, but the docker host won't be mounted to the job containers and service containers.
# If it's "-", runner will find an available docker host automatically, but won't mount it into the job and action containers.
# If it's not empty or "-", the specified docker host will be used. An error will be returned if it doesn't work.
#docker_host: ""
# Pull docker image(s) even if already present.
@@ -269,11 +274,11 @@ container:
#require_docker: false
# Timeout to wait for the docker daemon to be reachable, if docker is required by require_docker or runner
#docker_timeout: 0s
# Bind the workspace to the host filesystem instead of using Docker volumes.
# This is required for Docker-in-Docker (DinD) setups when jobs use docker compose
# with bind mounts (e.g., ".:/app"), as volume-based workspaces are not accessible
# from the DinD daemon's filesystem. When enabled, ensure the workspace parent
# directory is also mounted into the runner container and listed in valid_volumes.
# Mount the workspace from a host directory instead of a Docker volume, so jobs
# can bind-mount it by its own path into sibling containers (".:/app" in docker
# compose). Not needed when jobs get the Docker proxy or workflows use the
# GITEA_DOCKER_WORKSPACE variable.
# The workspace parent directory must be mounted into the runner container.
#bind_workdir: false
# How long a job waits for a service container that declares a healthcheck to become
# healthy. A negative value (e.g. -1s) starts the steps without waiting.
sites/docs/astro.config.mjs
+2 -1
View File
@@ -61,7 +61,7 @@ export default defineConfig({
if (
!useDocSearch &&
source === '@pagefind/default-ui' &&
importer?.includes('starlight/components/Search.astro')
importer?.includes('starlight/dist/components/Search.astro')
) {
pagefindUiRedirected = true;
return path.join(repoRoot, 'sites/docs/src/lib/pagefind-ui.ts');
@@ -126,6 +126,7 @@ export default defineConfig({
Header: './src/components/Header.astro',
LanguageSelect: './src/components/LanguageSelect.astro',
MarkdownContent: './src/components/MarkdownContent.astro',
Sidebar: './src/components/Sidebar.astro',
SiteTitle: './src/components/SiteTitle.astro',
PageFrame: './src/components/PageFrame.astro',
},
sites/docs/package.json
+5 -5
View File
@@ -11,13 +11,13 @@
"check": "astro check"
},
"dependencies": {
"@astrojs/starlight": "0.41.7",
"@astrojs/starlight-docsearch": "0.7.0",
"@astrojs/starlight": "0.42.1",
"@astrojs/starlight-docsearch": "0.8.0",
"@gitea-docs/content-loader": "workspace:*",
"@pagefind/default-ui": "1.5.2",
"astro": "7.2.3",
"sharp": "0.35.3",
"starlight-openapi": "0.26.1"
"astro": "7.3.2",
"sharp": "0.35.4",
"starlight-openapi": "0.26.2"
},
"devDependencies": {
"@astrojs/check": "0.9.10",
sites/docs/src/components/ProductNav.astro
+78
View File
@@ -0,0 +1,78 @@
---
import { t } from '../config/strings';
import { productNav } from '../lib/versions';
interface Props {
variant: 'header' | 'sidebar';
}
const meta = Astro.locals.starlightRoute.entry.data.gitea;
const strings = t(meta?.locale ?? 'en-us');
const products = productNav(meta);
const { variant } = Astro.props;
---
<nav class:list={['gitea-product-nav', `gitea-product-nav-${variant}`]} aria-label="Products">
{
products.map((product) => (
<a href={product.href} aria-current={product.current ? 'page' : undefined}>
{strings.products[product.id] ?? product.label}
</a>
))
}
</nav>
<style>
.gitea-product-nav a {
color: var(--sl-color-gray-2);
text-decoration: none;
white-space: nowrap;
}
.gitea-product-nav a:hover {
color: var(--sl-color-white);
}
.gitea-product-nav-header {
display: none;
gap: 0.75rem;
font-size: var(--sl-text-sm);
}
.gitea-product-nav-header a[aria-current='page'] {
color: var(--sl-color-white);
font-weight: 600;
}
.gitea-product-nav-sidebar {
display: flex;
flex-direction: column;
gap: 0.5rem;
padding-bottom: 1rem;
border-bottom: 1px solid var(--sl-color-hairline-light);
}
.gitea-product-nav-sidebar a {
display: block;
border-radius: 0.25rem;
padding: 0.3em 0.5rem;
font-size: var(--sl-text-sm);
line-height: 1.4;
}
.gitea-product-nav-sidebar a[aria-current='page'] {
color: var(--sl-color-text-invert);
background-color: var(--sl-color-text-accent);
font-weight: 600;
}
@media (min-width: 72rem) {
.gitea-product-nav-header {
display: flex;
}
.gitea-product-nav-sidebar {
display: none;
}
}
</style>
sites/docs/src/components/Sidebar.astro
+13
View File
@@ -0,0 +1,13 @@
---
import Default from '@astrojs/starlight/components/Sidebar.astro';
import ProductNav from './ProductNav.astro';
/**
* The product navigation is hidden from the header until the 72rem layout
* breakpoint, so it is rendered at the top of the sidebar for the layouts in
* between (and for the mobile menu below 50rem).
*/
---
<ProductNav variant="sidebar" />
<Default />
sites/docs/src/components/SiteTitle.astro
+2 -36
View File
@@ -1,29 +1,17 @@
---
import Default from '@astrojs/starlight/components/SiteTitle.astro';
import { t } from '../config/strings';
import { productNav } from '../lib/versions';
import ProductNav from './ProductNav.astro';
/**
* The starlight header has no navigation links, the gitea site needs the four
* products next to the logo. Rendered next to the site title so the rest of the
* header (search, theme, pickers) keeps working untouched.
*/
const meta = Astro.locals.starlightRoute.entry.data.gitea;
const strings = t(meta?.locale ?? 'en-us');
const products = productNav(meta);
---
<div class="gitea-site-title">
<Default><slot /></Default>
<nav class="gitea-nav" aria-label="Products">
{
products.map((product) => (
<a href={product.href} class:list={[{ current: product.current }]}>
{strings.products[product.id] ?? product.label}
</a>
))
}
</nav>
<ProductNav variant="header" />
</div>
<style>
@@ -33,26 +21,4 @@ const products = productNav(meta);
gap: 1rem;
overflow: hidden;
}
.gitea-nav {
display: none;
gap: 0.75rem;
font-size: var(--sl-text-sm);
}
.gitea-nav a {
color: var(--sl-color-gray-2);
text-decoration: none;
white-space: nowrap;
}
.gitea-nav a:hover,
.gitea-nav a.current {
color: var(--sl-color-white);
}
.gitea-nav a.current {
font-weight: 600;
}
@media (min-width: 72rem) {
.gitea-nav {
display: flex;
}
}
</style>
sites/docs/src/config/api.ts
+33
View File
@@ -27,6 +27,11 @@ interface Operation {
operationId?: string;
}
interface Schema {
title?: string;
description?: string;
}
interface SwaggerDocument {
openapi?: string;
basePath?: string;
@@ -34,6 +39,7 @@ interface SwaggerDocument {
schemes?: string[];
tags?: { name: string; description?: string }[];
paths?: Record<string, Record<string, Operation | unknown>>;
components?: { schemas?: Record<string, Schema> };
}
const httpMethods = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'];
@@ -95,6 +101,7 @@ function normalizeSchema(source: string, name: string): string {
hyphenateOperationIds(document);
describeTags(document);
nameSchemas(document);
mkdirSync(cacheDir, { recursive: true });
const target = path.join(cacheDir, name);
@@ -123,6 +130,32 @@ function describeTags(document: SwaggerDocument): void {
document.tags = [...described.values()];
}
/**
* Titles the named schemas of an openapi 3.0 document with their own name.
*
* starlight-openapi dereferences every `$ref`, so a field of type
* `ReviewStateType` is rendered as the bare string enum it points at and the
* name of the type is nowhere on the page: searching the reference for a type
* name found in an sdk or in an error message turns up nothing (gitea/docs#258).
* The plugin renders `title` next to the type of a field, so setting it brings
* the name back, next to the allowed values.
*
* Swagger 2.0 documents are left alone, they are rendered with the name of the
* definition already.
*/
function nameSchemas(document: SwaggerDocument): void {
for (const [name, schema] of Object.entries(document.components?.schemas ?? {})) {
if (!schema || typeof schema !== 'object') continue;
if (!schema.title) schema.title = name;
// the go doc comments start with the name of the type, which would read
// "ChangeFilesOptions — ChangeFilesOptions options for ..." once the title
// is rendered in front of the description
if (schema.description?.startsWith(`${name} `)) {
schema.description = schema.description.slice(name.length + 1);
}
}
}
/**
* One starlight-openapi schema per documented api version, each mounted at the
* route of its version: `/api/` for the latest release, `/api/1.26/` and
sites/docs/src/styles/custom.css
+1 -1
View File
@@ -51,7 +51,7 @@
/* Centre the mobile menu button on the navigation row instead of on the whole
header bar, which the announcement strip made taller. */
starlight-menu-button button {
.sl-menu-button {
top: calc(
var(--gitea-announcement-height) + (var(--gitea-nav-row-height) - var(--sl-menu-button-size)) / 2
);
static/openapi3-latest.json
+50 -2
View File
@@ -6311,6 +6311,14 @@
"type": "integer",
"x-go-name": "SourceID"
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/UserTypeString"
}
],
"description": "The user type"
},
"visibility": {
"allOf": [
{
@@ -10722,6 +10730,14 @@
"type": "integer",
"x-go-name": "StarredRepos"
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/UserTypeString"
}
],
"description": "the user type"
},
"visibility": {
"allOf": [
{
@@ -10878,6 +10894,14 @@
"type": "object",
"x-go-package": "gitea.dev/modules/structs"
},
"UserTypeString": {
"enum": [
"User",
"Organization",
"Bot"
],
"type": "string"
},
"VisibilityString": {
"enum": [
"public",
@@ -11813,9 +11837,9 @@
}
},
{
"description": "pattern of repositories to search for",
"description": "glob pattern of repositories to search for, in the form owner or owner/repo",
"in": "query",
"name": "pattern",
"name": "query",
"schema": {
"type": "string"
}
@@ -12058,6 +12082,9 @@
"403": {
"$ref": "#/components/responses/forbidden"
},
"409": {
"$ref": "#/components/responses/error"
},
"422": {
"$ref": "#/components/responses/validationError"
}
@@ -12142,6 +12169,9 @@
"403": {
"$ref": "#/components/responses/forbidden"
},
"409": {
"$ref": "#/components/responses/error"
},
"422": {
"$ref": "#/components/responses/validationError"
}
@@ -27149,6 +27179,9 @@
},
"404": {
"$ref": "#/components/responses/notFound"
},
"409": {
"$ref": "#/components/responses/error"
}
},
"summary": "Merge a branch from upstream",
@@ -32751,6 +32784,9 @@
},
"422": {
"$ref": "#/components/responses/invalidTopicsError"
},
"423": {
"$ref": "#/components/responses/repoArchivedError"
}
},
"summary": "Replace list of topics for a repository",
@@ -32800,6 +32836,9 @@
},
"422": {
"$ref": "#/components/responses/invalidTopicsError"
},
"423": {
"$ref": "#/components/responses/repoArchivedError"
}
},
"summary": "Delete a topic from a repository",
@@ -32847,6 +32886,9 @@
},
"422": {
"$ref": "#/components/responses/invalidTopicsError"
},
"423": {
"$ref": "#/components/responses/repoArchivedError"
}
},
"summary": "Add a topic to a repository",
@@ -34990,6 +35032,12 @@
"201": {
"$ref": "#/components/responses/EmailList"
},
"400": {
"$ref": "#/components/responses/error"
},
"409": {
"$ref": "#/components/responses/error"
},
"422": {
"$ref": "#/components/responses/validationError"
}
static/swagger-latest.json
+48 -2
View File
@@ -723,8 +723,8 @@
},
{
"type": "string",
"description": "pattern of repositories to search for",
"name": "pattern",
"description": "glob pattern of repositories to search for, in the form owner or owner/repo",
"name": "query",
"in": "query"
}
],
@@ -945,6 +945,9 @@
"403": {
"$ref": "#/responses/forbidden"
},
"409": {
"$ref": "#/responses/error"
},
"422": {
"$ref": "#/responses/validationError"
}
@@ -1029,6 +1032,9 @@
"403": {
"$ref": "#/responses/forbidden"
},
"409": {
"$ref": "#/responses/error"
},
"422": {
"$ref": "#/responses/validationError"
}
@@ -14991,6 +14997,9 @@
},
"404": {
"$ref": "#/responses/notFound"
},
"409": {
"$ref": "#/responses/error"
}
}
}
@@ -20099,6 +20108,9 @@
},
"422": {
"$ref": "#/responses/invalidTopicsError"
},
"423": {
"$ref": "#/responses/repoArchivedError"
}
}
}
@@ -20145,6 +20157,9 @@
},
"422": {
"$ref": "#/responses/invalidTopicsError"
},
"423": {
"$ref": "#/responses/repoArchivedError"
}
}
},
@@ -20189,6 +20204,9 @@
},
"422": {
"$ref": "#/responses/invalidTopicsError"
},
"423": {
"$ref": "#/responses/repoArchivedError"
}
}
}
@@ -22264,6 +22282,12 @@
"201": {
"$ref": "#/responses/EmailList"
},
"400": {
"$ref": "#/responses/error"
},
"409": {
"$ref": "#/responses/error"
},
"422": {
"$ref": "#/responses/validationError"
}
@@ -29368,6 +29392,17 @@
"format": "int64",
"x-go-name": "SourceID"
},
"type": {
"description": "The user type",
"type": "string",
"enum": [
"User",
"Organization",
"Bot"
],
"x-go-enum-desc": "User UserTypeStringUser\nOrganization UserTypeStringOrganization\nBot UserTypeStringBot",
"x-go-name": "Type"
},
"visibility": {
"description": "User visibility level: public, limited, or private",
"type": "string",
@@ -33730,6 +33765,17 @@
"format": "int64",
"x-go-name": "StarredRepos"
},
"type": {
"description": "the user type",
"type": "string",
"enum": [
"User",
"Organization",
"Bot"
],
"x-go-enum-desc": "User UserTypeStringUser\nOrganization UserTypeStringOrganization\nBot UserTypeStringBot",
"x-go-name": "Type"
},
"visibility": {
"description": "User visibility level option: public, limited, private",
"type": "string",
versioned_docs/version-1.22/administration/config-cheat-sheet.md
+10 -7
View File
@@ -942,7 +942,7 @@ Default templates for project boards:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -951,7 +951,7 @@ Default templates for project boards:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -960,12 +960,13 @@ Default templates for project boards:
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `RUN_AT_START`: **true**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
- `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -985,7 +986,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
- `ENABLED`: **true**: Enable update migration poster id job.
- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
#### Cron - Sync External Users (`cron.sync_external_users`)
@@ -994,7 +995,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable synchronize external user data job
- `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1002,6 +1003,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable cleanup expired actions assets job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Cron syntax for the job.
#### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1070,7 +1072,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1078,7 +1080,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1086,6 +1088,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
versioned_docs/version-1.23/administration/config-cheat-sheet.md
+9 -7
View File
@@ -992,7 +992,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1001,7 +1001,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1010,12 +1010,13 @@ Default templates for project board view:
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `RUN_AT_START`: **true**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
- `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1035,7 +1036,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
- `ENABLED`: **true**: Enable update migration poster id job.
- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
#### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1044,7 +1045,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable synchronize external user data job
- `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1113,7 +1114,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1121,7 +1122,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1129,6 +1130,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
versioned_docs/version-1.24/administration/config-cheat-sheet.md
+10 -7
View File
@@ -1024,7 +1024,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1033,7 +1033,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1042,12 +1042,13 @@ Default templates for project board view:
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `RUN_AT_START`: **true**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
- `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1067,7 +1068,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
- `ENABLED`: **true**: Enable update migration poster id job.
- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
#### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1076,7 +1077,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable synchronize external user data job
- `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1084,6 +1085,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable cleanup expired actions assets job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Cron syntax for the job.
#### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1159,7 +1161,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1167,7 +1169,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1175,6 +1177,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
versioned_docs/version-1.25/administration/config-cheat-sheet.md
+10 -7
View File
@@ -1026,7 +1026,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1035,7 +1035,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1044,12 +1044,13 @@ Default templates for project board view:
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `RUN_AT_START`: **true**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
- `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1069,7 +1070,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
- `ENABLED`: **true**: Enable update migration poster id job.
- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
#### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1078,7 +1079,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable synchronize external user data job
- `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1086,6 +1087,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable cleanup expired actions assets job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Cron syntax for the job.
#### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1161,7 +1163,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1169,7 +1171,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1177,6 +1179,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
versioned_docs/version-1.26/administration/config-cheat-sheet.md
+15 -12
View File
@@ -1056,7 +1056,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1065,7 +1065,7 @@ Default templates for project board view:
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1074,12 +1074,13 @@ Default templates for project board view:
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `RUN_AT_START`: **true**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
- `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1099,7 +1100,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
- `ENABLED`: **true**: Enable update migration poster id job.
- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
#### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1108,7 +1109,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable synchronize external user data job
- `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1116,6 +1117,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable cleanup expired actions assets job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Cron syntax for the job.
#### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1205,7 +1207,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1213,7 +1215,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1221,6 +1223,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
@@ -1233,35 +1236,35 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@annually**: Cron syntax to set how often to rebuild
#### Cron - Stop running tasks which haven't been updated for a long time (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 5m**: Cron syntax to set how often tasks to run the check
#### Cron - Stop running tasks which have running status and continuous updates but don't end for a long time (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 30m**: Cron syntax to set how often to run the check.
#### Cron - Cancel jobs which haven't been picked up for a long time (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 6h**: Cron syntax to set how often to run the check.
#### Cron - Start cron based actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 1m**: Cron syntax to set how often to schedule tasks
## Git (`git`)
versioned_docs/version-1.27/administration/config-cheat-sheet.md
+15 -12
View File
@@ -1069,7 +1069,7 @@ Release attachment has its own config options in `[repository.release]` section.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1078,7 +1078,7 @@ Release attachment has its own config options in `[repository.release]` section.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1087,12 +1087,13 @@ Release attachment has its own config options in `[repository.release]` section.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
- `ENABLED`: **true**: Enable running Update mirrors task periodically.
- `RUN_AT_START`: **true**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
- `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1112,7 +1113,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
- `ENABLED`: **true**: Enable update migration poster id job.
- `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
#### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1121,7 +1122,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable synchronize external user data job
- `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1129,6 +1130,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable cleanup expired actions assets job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@midnight** : Cron syntax for the job.
#### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1218,7 +1220,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1226,7 +1228,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1234,6 +1236,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
@@ -1246,35 +1249,35 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@annually**: Cron syntax to set how often to rebuild
#### Cron - Stop running tasks which haven't been updated for a long time (`cron.stop_zombie_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 5m**: Cron syntax to set how often tasks to run the check
#### Cron - Stop running tasks which have running status and continuous updates but don't end for a long time (`cron.stop_endless_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 30m**: Cron syntax to set how often to run the check.
#### Cron - Cancel jobs which haven't been picked up for a long time (`cron.cancel_abandoned_jobs`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 6h**: Cron syntax to set how often to run the check.
#### Cron - Start cron based actions (`cron.start_schedule_tasks`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 1m**: Cron syntax to set how often to schedule tasks
## Git (`git`)
versioned_docs/version-1.27/installation/with-docker-rootless.md
+1 -1
View File
@@ -66,7 +66,7 @@ server-1 | 2026-03-11T12:57:50.796198843Z /var/lib/gitea/git is not writable
server-1 | 2026-03-11T12:57:50.796235667Z docker setup failed
```
For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`)
For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:main-nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly-rootless`)
## Named volumes
versioned_docs/version-1.27/installation/with-docker.md
+1 -1
View File
@@ -30,7 +30,7 @@ image as a service. Since there is no database available, one can be initialized
Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
If you don't give the volume correct permissions, the container may not start.
For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`)
For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:main-nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly`)
```yaml
networks:
versioned_docs/version-1.27/usage/issues-prs/linked-references.md
+6 -1
View File
@@ -51,6 +51,11 @@ Example:
> This bug was introduced in [e59ff077](#)
Commits in other repositories can be referred to as well
using the form `owner/repository@e59ff077`:
> This bug was introduced in [mike/compiler@e59ff077](#)
## Issues and Pull Requests
A reference to another issue or pull request can be created using the simple
@@ -177,7 +182,7 @@ In the examples, `User1/Repo1` refers to the repository where the reference is u
| `UserZ/RepoZ!1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
| `UserZ/RepoZ#1234` | - | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 for `UserZ/RepoZ` |
| **Alphanumeric issue IDs:** | - | - | - |
| **Alphanumeric issue IDs:** | - | - | - |
| `AAA-1234` | yes | - | A link to _external issue_ `AAA-1234` for `User1/Repo1` |
| `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |
| `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |