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

Add 1.27 rc0 documentation (#453)

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

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

@@ -0,0 +1,9 @@
{
"label": "Access Control",
"position": 100,
"link": {
"type": "generated-index",
"slug": "/usage/access-control",
"description": "Permissions, security, and access control features"
}
}

47
versioned_docs/version-1.27/usage/access-control/blocking-users.md Normal file
View File

@@ -0,0 +1,47 @@
---
date: "2024-01-31T00:00:00+00:00"
slug: "blocking-user"
sidebar_position: 25
aliases:
- /blocking-user
---
# Blocking a user
Gitea supports blocking of users to restrict how they can interact with you and your content.
You can block a user in your account settings, from the user's profile or from comments created by the user.
The user is not directly notified about the block, but they can notice they are blocked when they attempt to interact with you.
Organization owners can block anyone who is not a member of the organization too.
If a blocked user has admin permissions, they can still perform all actions even if blocked.
### When you block a user
- the user stops following you
- you stop following the user
- the user's stars are removed from your repositories
- your stars are removed from their repositories
- the user stops watching your repositories
- you stop watching their repositories
- the user's issue assignments are removed from your repositories
- your issue assignments are removed from their repositories
- the user is removed as a collaborator on your repositories
- you are removed as a collaborator on their repositories
- any pending repository transfers to or from the blocked user are canceled
### When you block a user, the user cannot
- follow you
- watch your repositories
- star your repositories
- fork your repositories
- transfer repositories to you
- open issues or pull requests on your repositories
- comment on issues or pull requests you've created
- comment on issues or pull requests on your repositories
- react to your comments on issues or pull requests
- react to comments on issues or pull requests on your repositories
- assign you to issues or pull requests
- add you as a collaborator on their repositories
- send you notifications by @mentioning your username
- be added as team member (if blocked by an organization)

78
versioned_docs/version-1.27/usage/access-control/permissions.md Normal file
View File

@@ -0,0 +1,78 @@
---
date: "2021-12-13:10:10+08:00"
slug: "permissions"
sidebar_position: 14
aliases:
- /en-us/permissions
- /permissions
---
# Permissions
Gitea supports permissions for repository so that you can give different access for different people. At first, we need to know about `Unit`.
## Unit
In Gitea, we call a sub module of a repository `Unit`. Now we have following possible units.
| Name | Description | Permissions |
| --------------- | ---------------------------------------------------- | ----------- |
| Code | Access source code, files, commits and branches. | Read Write |
| Issues | Organize bug reports, tasks and milestones. | Read Write |
| PullRequests | Enable pull requests and code reviews. | Read Write |
| Releases | Track project versions and downloads. | Read Write |
| Wiki | Write and share documentation with collaborators. | Read Write |
| ExternalWiki | Link to an external wiki | Read |
| ExternalTracker | Link to an external issue tracker | Read |
| Projects | The URL to the template repository | Read Write |
| Packages | Packages which linked to this repository | Read Write |
| Actions | Review actions logs or restart/cacnel pipelines | Read Write |
| Settings | Manage the repository | Admin |
With different permissions, people could do different things with these units.
| Name | Read | Write | Admin |
| --------------- | ------------------------------------------------- | ---------------------------- | ------------------------- |
| Code | View code trees, files, commits, branches and etc. | Push codes. | - |
| Issues | View issues and create new issues. | Add labels, assign, close | - |
| PullRequests | View pull requests and create new pull requests. | Add labels, assign, close | - |
| Releases | View releases and download files. | Create/Edit releases | - |
| Wiki | View wiki pages. Clone the wiki repository. | Create/Edit wiki pages, push | - |
| ExternalWiki | Link to an external wiki | - | - |
| ExternalTracker | Link to an external issue tracker | - | - |
| Projects | View the columns of projects | Change issues across columns | - |
| Packages | View the packages | Upload/Delete packages | - |
| Actions | View the Actions logs | Approve / Cancel / Restart | - |
| Settings | - | - | Manage the repository |
And there are some differences for permissions between individual repositories and organization repositories.
## Individual Repository
For individual repositories, the creators are the only owners of repositories and have no limit to change anything of this
repository or delete it. Repositories owners could add collaborators to help maintain the repositories. Collaborators could have `Read`, `Write` and `Admin` permissions.
For a private repository, the experience is similar to visiting an anonymous public repository. You have access to all the available content within the repository, including the ability to clone the code, create issues, respond to issue comments, submit pull requests, and more. If you have 'Write' permission, you can push code to specific branches of the repository, provided it's permitted by the branch protection rules. Additionally, you can make changes to the wiki pages. With 'Admin' permission, you have the ability to modify the repository's settings.
But you cannot delete or transfer this repository if you are not that repository's owner.
## Organization Repository
For individual repositories, the owner is the user who created it. For organization repositories, the owners are the members of the owner team on this organization. All the permissions depends on the team permission settings.
### Owner Team
The owner team will be created when the organization is created, and the creator will become the first member of the owner team. The owner team cannot be deleted and there is at least one member.
### Admin Team
When creating teams, there are two types of teams. One is the admin team, another is the general team. An admin team can be created to manage some of the repositories, whose members can do anything with these repositories. Only members of the owner or admin team can create a new team.
### General Team
A general team in an organization has unit permissions settings. It can have members and repositories scope.
- A team could access all the repositories in this organization or special repositories.
- A team could also be allowed to create new repositories or not.
The General team can be created to do the operations allowed by their permissions. One member could join multiple teams.

90
versioned_docs/version-1.27/usage/access-control/protected-branches.md Normal file
View File

@@ -0,0 +1,90 @@
---
date: "2025-11-20T00:00:00-07:00"
slug: "protected-branches"
sidebar_position: 44
aliases:
- /en-us/protected-branches
- /en-us/protected-branch
- /protected-branches
---
# Protected branches
Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
## Creating or editing a rule
1. Open the repository and select **Settings → Branches** (repository admin permission required).
2. Select **Add new rule** or **Edit** next to an existing rule.
3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below.
4. Select **Save rule**.
The rule immediately applies to all matching branches, even if the branches are created in the future.
## Rule matching and priorities
- The **Protected branch name pattern** accepts [glob](https://github.com/gobwas/glob) expressions and matches the entire branch name. Patterns are case-sensitive. Using a simple name such as `main` without glob special characters always matches that specific branch (case-insensitive).
- If multiple rules match the same branch, only the first rule is used. Reorder the list on the **Branches** page by dragging the grab handle. The first entry (priority 1) has the highest priority, so place patterns such as `main` or `release/*` before generic fallbacks such as `*`.
Example patterns:
| Pattern | Matches |
| -------------- | ------------------------------- |
| `main` | The `main` branch only |
| `release/*` | `release/v1.0`, `release/april` |
| `hotfix/**` | Nested branches such as `hotfix/security/CVE` |
| `*` | Every branch (use as a fallback) |
### File-level pattern controls
- **Protected file patterns** block changes to sensitive files (for example `.drone.yml` or `/docs/**/*.txt`). Patterns are case-insensitive and separated by semicolons. Commits and merge attempts that touch one of the files are rejected.
- **Unprotected file patterns** do the opposite: if pushes are blocked, users with write access can still push commits that modify only the listed files. This is useful for letting contributors update documentation while still requiring pull requests for code.
Both fields use the same `glob` syntax and match paths relative to the repository root.
## Controlling direct pushes
The **Push** section controls direct pushes (including the web editor and API).
- **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
- **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted.
When a push is blocked, the server-side hook rejects the update with an explanation.
### Force pushes
Force pushes have their own set of options:
- **Disable force push** completely forbids rewriting history on the branch.
- **Enable force push** allows anyone who can push to also force push.
- **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access.
## Pull request merges and approvals
- **Merge allowlist**: keep the default to let anyone with write access merge pull requests, or enable the allowlist to restrict merges to selected users/teams.
- **Required approvals**: specify how many approvals are needed before a merge is allowed. Reviews from users with write access count, unless the **Restrict approvals to allowlisted users or teams** option is enabled.
- **Dismiss stale approvals** removes existing approvals whenever new commits that change the pull request content are pushed.
- **Ignore stale approvals** keeps approvals but does not count reviews that were made on older commits. This option is disabled while dismissal of stale approvals is enabled.
- **Block merge on rejected reviews** prevents merging while any official reviewer has requested changes.
- **Block merge on official review requests** blocks merges while there are outstanding review requests (for example when CODEOWNERS requires a review).
- **Block merge if the pull request is outdated** makes sure the head branch is up to date with the base branch before it can be merged.
- **Administrators must follow branch protection rules** removes the ability for repository administrators to bypass the rules with the "Force merge" button.
Protected file patterns apply to pull requests as well. When a pull request changes one of the protected files, the pull request banner shows the affected paths and merging stays disabled.
## Status checks
Enable status checks to require one or more CI jobs to succeed before merging:
1. Check **Enable status check**.
2. Enter one pattern per line in **Status check patterns**. Each pattern is a `glob` expression that matches the context name reported by Actions, Drone, Woodpecker, or another Check API client (for example `actions/test-*`).
3. Pick contexts from the table of jobs that have reported results in the last week to verify their names.
When the option is active, Gitea requires at least one context that matches each pattern to report success on the pull request head commit. An empty list is not allowed; use `*` to require the latest commit to be successful regardless of the context name.
## Signed commits and other safeguards
- **Require signed commits** rejects pushes that contain unsigned or unverifiable commits. The check runs inside the server hook before the push is accepted.
- **Protected file patterns** (see above) prevent both pushes and merges that modify sensitive files.
- **Unprotected file patterns** allow limited pushes while keeping the branch protected.

47
versioned_docs/version-1.27/usage/access-control/protected-tags.md Normal file
View File

@@ -0,0 +1,47 @@
---
date: "2021-05-14T00:00:00-00:00"
slug: "protected-tags"
sidebar_position: 45
aliases:
- /en-us/protected-tags
- /protected-tags
---
# Protected tags
Protected tags allow control over who has permission to create or update Git tags. Each rule allows you to match either an individual tag name, or use an appropriate pattern to control multiple tags at once.
## Setting up protected tags
To protect a tag, you need to follow these steps:
1. Go to the repository’s **Settings** > **Tags** page.
1. Type a pattern to match a name. You can use a single name, a [glob pattern](https://pkg.go.dev/github.com/gobwas/glob#Compile) or a regular expression.
1. Choose the allowed users and/or teams. If you leave these fields empty no one is allowed to create or modify this tag.
1. Select **Save** to save the configuration.
## Pattern protected tags
The pattern uses [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) or regular expressions to match a tag name. For regular expressions you need to enclose the pattern in slashes.
Examples:
| Type | Pattern Protected Tag | Possible Matching Tags |
| ----- | ------------------------ | --------------------------------------- |
| Glob | `v*` | `v`, `v-1`, `version2` |
| Glob | `v[0-9]` | `v0`, `v1` up to `v9` |
| Glob | `*-release` | `2.1-release`, `final-release` |
| Glob | `gitea` | only `gitea` |
| Glob | `*gitea*` | `gitea`, `2.1-gitea`, `1_gitea-release` |
| Glob | `{v,rel}-*` | `v-`, `v-1`, `v-final`, `rel-`, `rel-x` |
| Glob | `*` | matches all possible tag names |
| Regex | `/\Av/` | `v`, `v-1`, `version2` |
| Regex | `/\Av[0-9]\z/` | `v0`, `v1` up to `v9` |
| Regex | `/\Av\d+\.\d+\.\d+\z/` | `v1.0.17`, `v2.1.0` |
| Regex | `/\Av\d+(\.\d+){0,2}\z/` | `v1`, `v2.1`, `v1.2.34` |
| Regex | `/-release\z/` | `2.1-release`, `final-release` |
| Regex | `/gitea/` | `gitea`, `2.1-gitea`, `1_gitea-release` |
| Regex | `/\Agitea\z/` | only `gitea` |
| Regex | `/^gitea$/` | only `gitea` |
| Regex | `/\A(v\|rel)-/` | `v-`, `v-1`, `v-final`, `rel-`, `rel-x` |
| Regex | `/.+/` | matches all possible tag names |