gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-03 01:18:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Move usage directories (#300)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/300
This commit is contained in:
Lunny Xiao
2025-11-20 19:49:24 +00:00
parent 00a36086b0
commit 9baa98ec3f
302 changed files with 24392 additions and 880 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
versioned_docs/version-1.23/usage/template-repositories.md
View File

@@ -1,86 +0,0 @@
---
date: "2019-11-28:00:00+02:00"
slug: "template-repositories"
sidebar_position: 14
aliases:
- /en-us/template-repositories
---
# Template Repositories
Since Gitea `1.11`, you can create template repositories.
When creating a repo based on a template, you can copy most of its content, and even auto-inject variables into it.
By default, variables will not be expanded in any file.
Only files contained in a pattern inside the `.gitea/template` file will be checked for if they contain variables.
When creating the template, all files are included except for this `.gitea/template` file.
Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax.
It closely resembles a traditional `.gitignore`, however there may be slight differences.
## Example `.gitea/template` file
All paths are relative to the base of the repository
```gitignore
# Expand all .go files, anywhere in the repository
**.go
# All text files in the text directory
text/*.txt
# A specific file
a/b/c/d.json
# Batch files in both upper or lower case can be matched
**.[bB][aA][tT]
```
## Variable Expansion
In any file matched by the above globs, the variables below will be expanded.
Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems.
You can use variables by prefixing them with `$` or surrounding them with `${}`, so both `$VAR` and `${VAR}` insert the value of `VAR` at this location.
To escape an expansion, use `$$`, such as `$$VAR` or `$${VAR}`.
These are the variables Gitea currently recognizes:
| Variable | Expands To | Transformable |
| -------------------- | --------------------------------------------------- | ------------- |
| YEAR | The year of generating the repository (i.e. `2024`) | ✘ |
| MONTH | The month of generating the repository (i.e. `03`) | ✘ |
| MONTH_ENGLISH | The month but in English (i.e. `March`) | ✓ |
| DAY | The day of generating the repository (i.e. `02`) | ✘ |
| REPO_NAME | The name of the generated repository | ✓ |
| TEMPLATE_NAME | The name of the template repository | ✓ |
| REPO_DESCRIPTION | The description of the generated repository | ✘ |
| TEMPLATE_DESCRIPTION | The description of the template repository | ✘ |
| REPO_OWNER | The owner of the generated repository | ✓ |
| TEMPLATE_OWNER | The owner of the template repository | ✓ |
| REPO_LINK | The URL to the generated repository | ✘ |
| TEMPLATE_LINK | The URL to the template repository | ✘ |
| REPO_HTTPS_URL | The HTTP(S) clone link for the generated repository | ✘ |
| TEMPLATE_HTTPS_URL | The HTTP(S) clone link for the template repository | ✘ |
| REPO_SSH_URL | The SSH clone link for the generated repository | ✘ |
| TEMPLATE_SSH_URL | The SSH clone link for the template repository | ✘ |
## Transformers :robot:
Since Gitea `1.12.0`, variables marked as transformable in the table above also have alternative versions where the given transformer has been applied.
Transformed variables can be called by appending the transformer name to the variable name.
For example, to get `REPO_NAME` in `PASCAL`-case, you should use the variable `${REPO_NAME_PASCAL}`.
The following transformers are available (assuming `go-sdk` is the input):
| Transformer | Effect |
| ----------- | ------ |
| SNAKE | go_sdk |
| KEBAB | go-sdk |
| CAMEL | goSdk |
| PASCAL | GoSdk |
| LOWER | go-sdk |
| UPPER | GO-SDK |
| TITLE | Go-Sdk |

9
versioned_docs/version-1.25/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"
}
}

0
versioned_docs/version-1.25/usage/blocking-users.md → versioned_docs/version-1.25/usage/access-control/blocking-users.md
View File

0
versioned_docs/version-1.25/usage/permissions.md → versioned_docs/version-1.25/usage/access-control/permissions.md
View File

0
versioned_docs/version-1.25/usage/protected-branches.md → versioned_docs/version-1.25/usage/access-control/protected-branches.md
View File

0
versioned_docs/version-1.25/usage/protected-tags.md → versioned_docs/version-1.25/usage/access-control/protected-tags.md
View File

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

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

48
versioned_docs/version-1.25/usage/agit.md
View File

@@ -1,48 +0,0 @@
---
date: " 2022-09-01T20:50:42+0000"
slug: "agit"
sidebar_position: 12
aliases:
- /en-us/agit-setup
- /agit-setup
---
# AGit
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
:::note
Git version 2.29 or higher is required on the server side for this to work.
:::
## Creating PRs with AGit
AGit allows to create PRs while pushing code to the remote repo.
This can be done by pushing to the branch followed by a specific refspec (a location identifier known to git).
The following example illustrates this:
```shell
git push origin HEAD:refs/for/main
```
The command has the following structure:
- `HEAD`: The target branch
- `origin`: The target repository (not a fork!)
- `HEAD`: The local branch containing the changes you are proposing
- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
- `for`: Create a normal PR with `<branch>` as the target branch
- `draft`/`for-review`: Currently ignored silently
- `<branch>/`: The branch you want your changes to be merged into
- `-o <topic|title|description>`: Options for the PR
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review. This is REQUIRED to trigger a pull request.
- `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
- `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
- `force-push=true`: Specifies whether to force-update the target branch.
- Note: omitting the value and using just `-o force-push` will also work.
Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
```shell
git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
```

29
versioned_docs/version-1.25/usage/blame.md
View File

@@ -1,29 +0,0 @@
---
date: "2023-08-14T00:00:00+00:00"
slug: "blame"
sidebar_position: 13
aliases:
- /en-us/blame
---
# Blame File View
Gitea supports viewing the line-by-line revision history for a file also known as blame view.
You can also use [`git blame`](https://git-scm.com/docs/git-blame) on the command line to view the revision history of lines within a file.
1. Navigate to and open the file whose line history you want to view.
1. Click the `Blame` button in the file header bar.
1. The new view shows the line-by-line revision history for a file with author and commit information on the left side.
1. To navigate to an older commit, click the ![versions](/octicon-versions.svg) icon.
## Ignore commits in the blame view
All revisions specified in the `.git-blame-ignore-revs` file are hidden from the blame view.
This is especially useful to hide reformatting changes and keep the benefits of `git blame`.
Lines that were changed or added by an ignored commit will be blamed on the previous commit that changed that line or nearby lines.
The `.git-blame-ignore-revs` file must be located in the root directory of the repository.
For more information like the file format, see [the `git blame --ignore-revs-file` documentation](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt).
### Bypassing `.git-blame-ignore-revs` in the blame view
If the blame view for a file shows a message about ignored revisions, you can see the normal blame view by appending the url parameter `?bypass-blame-ignore=true`.

328
versioned_docs/version-1.25/usage/issue-pull-request-templates.md
View File

@@ -1,328 +0,0 @@
---
date: "2018-05-10T16:00:00+02:00"
slug: "issue-pull-request-templates"
sidebar_position: 15
aliases:
- /en-us/issue-pull-request-templates
---
# Issue and Pull Request Templates
Some projects have a standard list of questions that users need to answer
when creating an issue or pull request. Gitea supports adding templates to the
**default branch of the repository** so that they can autopopulate the form when users are
creating issues and pull requests. This will cut down on the initial back and forth
of getting some clarifying details.
It is currently not possible to provide generic issue/pull-request templates globally.
Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
## File names
Possible file names for issue templates:
- `ISSUE_TEMPLATE.md`
- `ISSUE_TEMPLATE.yaml`
- `ISSUE_TEMPLATE.yml`
- `issue_template.md`
- `issue_template.yaml`
- `issue_template.yml`
- `.gitea/ISSUE_TEMPLATE.md`
- `.gitea/ISSUE_TEMPLATE.yaml`
- `.gitea/ISSUE_TEMPLATE.yml`
- `.gitea/issue_template.md`
- `.gitea/issue_template.yaml`
- `.gitea/issue_template.yml`
- `.github/ISSUE_TEMPLATE.md`
- `.github/ISSUE_TEMPLATE.yaml`
- `.github/ISSUE_TEMPLATE.yml`
- `.github/issue_template.md`
- `.github/issue_template.yaml`
- `.github/issue_template.yml`
Possible file names for issue config:
- `.gitea/ISSUE_TEMPLATE/config.yaml`
- `.gitea/ISSUE_TEMPLATE/config.yml`
- `.gitea/issue_template/config.yaml`
- `.gitea/issue_template/config.yml`
- `.github/ISSUE_TEMPLATE/config.yaml`
- `.github/ISSUE_TEMPLATE/config.yml`
- `.github/issue_template/config.yaml`
- `.github/issue_template/config.yml`
Possible file names for PR templates:
- `PULL_REQUEST_TEMPLATE.md`
- `PULL_REQUEST_TEMPLATE.yaml`
- `PULL_REQUEST_TEMPLATE.yml`
- `pull_request_template.md`
- `pull_request_template.yaml`
- `pull_request_template.yml`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
- `.gitea/PULL_REQUEST_TEMPLATE.yml`
- `.gitea/pull_request_template.md`
- `.gitea/pull_request_template.yaml`
- `.gitea/pull_request_template.yml`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/PULL_REQUEST_TEMPLATE.yaml`
- `.github/PULL_REQUEST_TEMPLATE.yml`
- `.github/pull_request_template.md`
- `.github/pull_request_template.yaml`
- `.github/pull_request_template.yml`
## Directory names
Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically
addresses their problem.
Possible directory names for issue templates:
- `ISSUE_TEMPLATE`
- `issue_template`
- `.gitea/ISSUE_TEMPLATE`
- `.gitea/issue_template`
- `.github/ISSUE_TEMPLATE`
- `.github/issue_template`
- `.gitlab/ISSUE_TEMPLATE`
- `.gitlab/issue_template`
Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) issue templates of the form.
## Syntax for markdown template
```md
---
name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
assignees: ["user1"]
labels:
- bug
- "help needed"
---
This is the template!
```
In the above example, when a user is presented with the list of issues they can submit, this would show as `Template Name` with the description
`This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with
`[TEST] ` while the issue body would be pre-populated with `This is the template!`.
The issue would be assigned to `user1`.
The issue would also be assigned two labels,
`bug` and `help needed`, and the issue will have a reference to `main`.
## Syntax for yaml template
This example YAML configuration file defines an issue form using several inputs to report a bug.
```yaml
name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
# some markdown that will only be visible once the issue has been created
- type: markdown
attributes:
value: |
This issue was created by an issue **template** :)
visible: [content]
- type: input
id: contact
attributes:
label: Contact Details
description: How can we get in touch with you if we need more info?
placeholder: ex. email@example.com
validations:
required: false
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
validations:
required: true
- type: dropdown
id: version
attributes:
label: Version
description: What version of our software are you running?
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: dropdown
id: browsers
attributes:
label: What browsers are you seeing the problem on?
multiple: true
options:
- Firefox
- Chrome
- Safari
- Microsoft Edge
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: shell
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
hide_label: true
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
options:
- label: I agree to follow this project's Code of Conduct
required: true
- label: I have also read the CONTRIBUTION.MD
required: true
visible: [form]
- label: This is a TODO only visible after issue creation
visible: [content]
```
### Markdown
You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted by default.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------|--------------------------------------------------------------|----------|--------|---------|--------------|
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
visible: Default is **[form]**
### Textarea
You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|--------------|---------------------------|
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the text area. | Optional | String | - | - |
| render | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | - | Languages known to Gitea. |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
visible: Default is **[form, content]**
### Input
You can use an `input` element to add a single-line text field to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|--------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the field. | Optional | String | - | - |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
| is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - |
| regex | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String | - | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
visible: Default is **[form, content]**
### Dropdown
You can use a `dropdown` element to add a dropdown menu in your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - |
| list | If true, display as a list. If false, print items on one line with commas. | Optional | Boolean | false | - |
| options | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | Required | String array | - | - |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
visible: Default is **[form, content]**
### Checkboxes
You can use the `checkboxes` element to add a set of checkboxes to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - |
| options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - |
For each value in the options array, you can set the following keys.
| Key | Description | Required | Type | Default | Options |
|--------------|------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------|---------|---------|
| label | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String | - | - |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
| visible | Whether a specific checkbox appears in the form only, in the created issue only, or both. Valid options are "form" and "content". | Optional | String array | false | - |
visible: Default is **[form, content]**
## Syntax for issue config
This is a example for a issue config file
```yaml
blank_issues_enabled: true
contact_links:
- name: Gitea
url: https://gitea.com
about: Visit the Gitea Website
```
### Possible Options
| Key | Description | Type | Default |
|----------------------|-------------------------------------------------------|--------------------|-------------|
| blank_issues_enabled | If set to false, the User is forced to use a Template | Boolean | true |
| contact_links | Custom Links to show in the Choose Box | Contact Link Array | Empty Array |
### Contact Link
| Key | Description | Type | Required |
|-------|----------------------------------|--------|----------|
| name | the name of your link | String | true |
| url | The URL of your Link | String | true |
| about | A short description of your Link | String | true |

9
versioned_docs/version-1.25/usage/issues-prs/_category_.json Normal file
View File

@@ -0,0 +1,9 @@
{
"label": "Issues & Pull Requests",
"position": 20,
"link": {
"type": "generated-index",
"slug": "/usage/issues-prs",
"description": "Issues and Pull Requests workflow, templates, and collaboration features"
}
}

0
versioned_docs/version-1.23/usage/agit.md → versioned_docs/version-1.25/usage/issues-prs/agit.md
View File

0
versioned_docs/version-1.23/usage/issue-pull-request-templates.md → versioned_docs/version-1.25/usage/issues-prs/issue-pull-request-templates.md
View File

0
versioned_docs/version-1.23/usage/labels.md → versioned_docs/version-1.25/usage/issues-prs/labels.md
View File

0
versioned_docs/version-1.23/usage/linked-references.md → versioned_docs/version-1.25/usage/issues-prs/linked-references.md
View File

0
versioned_docs/version-1.23/usage/merge-message-templates.md → versioned_docs/version-1.25/usage/issues-prs/merge-message-templates.md
View File

0
versioned_docs/version-1.20/usage/pull-request.md → versioned_docs/version-1.25/usage/issues-prs/pull-request.md
View File

33
versioned_docs/version-1.25/usage/labels.md
View File

@@ -1,33 +0,0 @@
---
date: "2023-03-04T19:00:00+00:00"
slug: "labels"
sidebar_position: 13
aliases:
- /en-us/labels
---
# Labels
You can use labels to classify issues and pull requests and to improve your overview over them.
## Creating Labels
For repositories, labels can be created by going to `Issues` and clicking on `Labels`.
For organizations, you can define organization-wide labels that are shared with all organization repositories, including both already-existing repositories as well as newly created ones. Organization-wide labels can be created in the organization `Settings`.
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
## Scoped Labels
Scoped labels are used to ensure at most a single label with the same scope is assigned to an issue or pull request. For example, if labels `kind/bug` and `kind/enhancement` have the Exclusive option set, an issue can only be classified as a bug or an enhancement.
A scoped label must contain `/` in its name (not at either end of the name). The scope of a label is determined based on the **last** `/`, so for example the scope of label `scope/subscope/item` is `scope/subscope`.
## Filtering by Label
Issue and pull request lists can be filtered by label. Selecting multiple labels shows issues and pull requests that have all selected labels assigned.
By holding alt to click the label, issues and pull requests with the chosen label are excluded from the list.

194
versioned_docs/version-1.25/usage/linked-references.md
View File

@@ -1,194 +0,0 @@
---
date: "2019-11-21T17:00:00-03:00"
slug: "automatically-linked-references"
sidebar_position: 15
aliases:
- /en-us/automatically-linked-references
---
# Automatically Linked References
When an issue, pull request or comment is posted, the text description is parsed
in search for references. These references will be shown as links in the Issue View
and, in some cases, produce certain _actions_.
Likewise, commit messages are parsed when they are listed, and _actions_
can be triggered when they are pushed to the main branch.
To prevent the creation of unintended references, there are certain rules
for them to be recognized. For example, they should not be included inside code
text. They should also be reasonably cleared from their surrounding text
(for example, using spaces).
## User, Team and Organization Mentions
When a text in the form `@username` is found and `username` matches the name
of an existing user, a _mention_ reference is created. This will be shown
by changing the text into a link to said user's profile, and possibly create
a notification for the mentioned user depending on whether they have
the necessary permission to access the contents.
Example:
> [@John](#), can you give this a look?
This is also valid for teams and organizations:
> [@Documenters](#), we need to plan for this.
> [@CoolCompanyInc](#), this issue concerns us all!
Teams will receive mail notifications when appropriate, but whole organizations won't.
Commit messages do not produce user notifications.
## Commits
Commits can be referenced using their SHA1 hash, or a portion of it of
at least seven characters. They will be shown as a link to the corresponding
commit.
Example:
> This bug was introduced in [e59ff077](#)
## Issues and Pull Requests
A reference to another issue or pull request can be created using the simple
notation `#1234`, where _1234_ is the number of an issue or pull request
in the same repository. These references will be shown as links to the
referenced content.
The effect of creating this type of reference is that a _notice_ will be
created in the referenced document, provided the creator of the reference
has reading permissions on it.
Example:
> This seems related to [#1234](#)
Issues and pull requests in other repositories can be referred to as well
using the form `owner/repository#1234`:
> This seems related to [mike/compiler#1234](#)
Alternatively, the `!1234` notation can be used as well. Even when in Gitea
a pull request is a form of issue, the `#1234` form will always link to
an issue; if the linked entry happens to be a pull request instead, Gitea
will redirect as appropriate. With the `!1234` notation, a pull request
link will be created, which will be redirected to an issue if required.
However, this distinction could be important if an external tracker is
used, where links to issues and pull requests are not interchangeable.
## Actionable References in Pull Requests and Commit Messages
Sometimes a commit or pull request may fix or bring back a problem documented
in a particular issue. Gitea supports closing and reopening the referenced
issues by preceding the reference with a particular _keyword_. Common keywords
include "closes", "fixes", "reopens", etc. This list can be
[customized](../administration/config-cheat-sheet.md) by the
site administrator.
Example:
> This PR _closes_ [#1234](#)
If the actionable reference is accepted, this will create a notice on the
referenced issue announcing that it will be closed when the referencing PR
is merged.
For an actionable reference to be accepted, _at least one_ of the following
conditions must be met:
- The commenter has permissions to close or reopen the issue at the moment
of creating the reference.
- The reference is inside a commit message.
- The reference is posted as part of the pull request description.
In the last case, the issue will be closed or reopened only if the merger
of the pull request has permissions to do so.
Additionally, only pull requests and commit messages can create an action,
and only issues can be closed or reopened this way.
The default _keywords_ are:
- **Closing**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
- **Reopening**: reopen, reopens, reopened
## Time tracking in Pull Requests and Commit Messages
When commit or merging of pull request results in automatic closing of issue
it is possible to also add spent time resolving this issue through commit message.
To specify spent time on resolving issue you need to specify time in format
`@<number><time-unit>` after issue number. In one commit message you can specify
multiple fixed issues and spent time for each of them.
Supported time units (`<time-unit>`):
- `m` - minutes
- `h` - hours
- `d` - days (equals to 8 hours)
- `w` - weeks (equals to 5 days)
- `mo` - months (equals to 4 weeks)
Numbers to specify time (`<number>`) can be also decimal numbers, ex. `@1.5h` would
result in one and half hours. Multiple time units can be combined, ex. `@1h10m` would
mean 1 hour and 10 minutes.
Example of commit message:
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
This would result in 1 hour added to issue #123 and 1 and half hours added to issue #124.
## External Trackers
Gitea supports the use of external issue trackers, and references to issues
hosted externally can be created in pull requests. However, if the external
tracker uses numbers to identify issues, they will be indistinguishable from
the pull requests hosted in Gitea. To address this, Gitea allows the use of
the `!` marker to identify pull requests. For example:
> This is issue [#1234](#), and links to the external tracker.
> This is pull request [!1234](#), and links to a pull request in Gitea.
The `!` and `#` can be used interchangeably for issues and pull request _except_
for this case, where a distinction is required. If the repository uses external
tracker, commit message for squash merge will use `!` as reference by default.
## Issues and Pull Requests References Summary
This table illustrates the different kinds of cross-reference for issues and pull requests.
In the examples, `User1/Repo1` refers to the repository where the reference is used, while
`UserZ/RepoZ` indicates a different repository.
| Reference in User1/Repo1 | Repo1 issues are external | RepoZ issues are external | Should render |
| --------------------------- | :-----------------------: | :-----------------------: | ------------------------------------------------------- |
| `#1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` |
| `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |
| `User1/Repo1#1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `User1/Repo1!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `User1/Repo1#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` |
| `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |
| `UserZ/RepoZ#1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
| `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:** | - | - | - |
| `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` |
| _Not supported_ | - | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 in `UserZ/RepoZ` |
_The last section is for repositories with external issue trackers that use alphanumeric format._
_**-**: not applicable._
:::note
Automatic references between repositories with different types of issues (external vs. internal) are not fully supported
and may render invalid links.
:::

46
versioned_docs/version-1.25/usage/merge-message-templates.md
View File

@@ -1,46 +0,0 @@
---
date: "2022-08-31T17:35:40+08:00"
slug: "merge-message-templates"
sidebar_position: 15
aliases:
- /en-us/merge-message-templates
---
# Merge Message templates
## File names
Possible file names for PR default merge message templates:
- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
## Variables
You can use the following variables enclosed in `${}` inside these templates which follow [os.Expand](https://pkg.go.dev/os#Expand) syntax:
- BaseRepoOwnerName: Base repository owner name of this pull request
- BaseRepoName: Base repository name of this pull request
- BaseBranch: Base repository target branch name of this pull request
- HeadRepoOwnerName: Head repository owner name of this pull request
- HeadRepoName: Head repository name of this pull request
- HeadBranch: Head repository branch name of this pull request
- PullRequestTitle: Pull request's title
- PullRequestDescription: Pull request's description
- PullRequestPosterName: Pull request's poster name
- PullRequestIndex: Pull request's index number
- PullRequestReference: Pull request's reference char with index number. i.e. #1, !2
- ClosingIssues: return a string contains all issues which will be closed by this pull request i.e. `close #1, close #2`
- ReviewedOn: Which pull request this commit belongs to. For example `Reviewed-on: https://gitea.com/foo/bar/pulls/1`
- ReviewedBy: Who approved the pull request before the merge. For example `Reviewed-by: Jane Doe <jane.doe@example.com>`
## Rebase
When rebasing without a merge commit, `REBASE_TEMPLATE.md` modifies the message of the last commit. The following additional variables are available in this template:
- CommitTitle: Commit's title
- CommitBody: Commits's body text

9
versioned_docs/version-1.25/usage/packages/_category_.json Normal file
View File

@@ -0,0 +1,9 @@
{
"label": "Packages",
"position": 40,
"link": {
"type": "generated-index",
"slug": "/usage/packages",
"description": "Managing packages and package registries"
}
}

16
versioned_docs/version-1.25/usage/profile-readme.md
View File

@@ -1,16 +0,0 @@
---
date: "2023-03-02T21:00:00+05:00"
slug: "profile-readme"
sidebar_position: 12
---
# Profile READMEs
To display a Markdown file in your Gitea user or organization profile page, create a repository named `.profile` and add a new file named `README.md` to it.
Gitea will automatically display the contents of the file on your profile, in a new "Overview" above your repositories.
Making the `.profile` repository private will hide the Profile README.
Example of user with `.profile/README.md`:
![profile readme screenshot](/images/usage/profile-readme.png)

60
versioned_docs/version-1.25/usage/pull-request.md
View File

@@ -1,60 +0,0 @@
---
date: "2018-06-01T19:00:00+02:00"
slug: "pull-request"
sidebar_position: 13
aliases:
- /en-us/pull-request
---
# Pull Request
A Pull Request (PR) is a way to propose changes to a repository.
It is a request to merge one branch into another, accompanied by a description of the changes that were made.
Pull Requests are commonly used as a way for contributors to propose changes and for maintainers to review and merge those changes.
## Creating a pull request
To create a PR, you'll need to follow these steps:
1. **Fork the repository** - If you don't have permission to make changes to the repository directly, you'll need to fork the repository to your own account.
This creates a copy of the repository that you can make changes to.
2. **Create a branch (optional)** - Create a new branch on your forked repository that contains the changes you want to propose.
Give the branch a descriptive name that indicates what the changes are for.
3. **Make your changes** - Make the changes you want, commit, and push them to your forked repository.
4. **Create the PR** - Go to the original repository and go to the "Pull Requests" tab. Click the "New Pull Request" button and select your new branch as the source branch.
Enter a descriptive title and description for your Pull Request and click "Create Pull Request".
## Reviewing a pull request
When a PR is created, it triggers a review process. The maintainers of the repository are notified of the PR and can review the changes that were made.
They can leave comments, request changes, or approve the changes.
If the maintainers request changes, you'll need to make those changes in your branch and push the changes to your forked repository.
The PR will be updated automatically with the new changes.
If the maintainers approve the changes, they can merge the PR into the repository.
## Closing a pull request
If you decide that you no longer want to merge a PR, you can close it.
To close a PR, go to the open PR and click the "Close Pull Request" button. This will close the PR without merging it.
## "Work In Progress" pull requests
Marking a pull request as being a work in progress will prevent that pull request from being accidentally merged.
To mark a pull request as being a work in progress, you must prefix its title by `WIP:` or `[WIP]` (case insensitive).
Those values are configurable in your `app.ini` file:
```ini
[repository.pull-request]
WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
```
The first value of the list will be used in helpers.
## Pull Request Templates
You can find more information about pull request templates at the page [Issue and Pull Request templates](usage/issue-pull-request-templates.md).

9
versioned_docs/version-1.25/usage/repository/_category_.json Normal file
View File

@@ -0,0 +1,9 @@
{
"label": "Repository",
"position": 10,
"link": {
"type": "generated-index",
"slug": "/usage/repository",
"description": "Repository management, Git operations, and content features"
}
}

0
versioned_docs/version-1.22/usage/blame.md → versioned_docs/version-1.25/usage/repository/blame.md
View File

0
versioned_docs/version-1.25/usage/clone-filter.md → versioned_docs/version-1.25/usage/repository/clone-filter.md
View File

0
versioned_docs/version-1.25/usage/code-owners.md → versioned_docs/version-1.25/usage/repository/code-owners.md
View File

2
versioned_docs/version-1.25/usage/incoming-email.md → versioned_docs/version-1.25/usage/repository/incoming-email.md
View File

@@ -1,7 +1,7 @@
---
date: "2022-12-01T00:00:00+00:00"
slug: "incoming-email"
sidebar_position: 13
sidebar_position: 130
aliases:
- /en-us/incoming-email
---

1
versioned_docs/version-1.25/usage/markdown.md → versioned_docs/version-1.25/usage/repository/markdown.md
View File

@@ -1,6 +1,7 @@
---
date: "2025-04-05T00:00:00+08:00"
slug: "markdown"
sidebar_position: 10
---
# Markdown

2
versioned_docs/version-1.25/usage/migration.md → versioned_docs/version-1.25/usage/repository/migration.md
View File

@@ -1,7 +1,7 @@
---
date: "2024-09-11T09:30:00+08:00"
slug: "migration"
sidebar_position: 45
sidebar_position: 40
---
# Migration

2
versioned_docs/version-1.22/usage/profile-readme.md → versioned_docs/version-1.25/usage/repository/profile-readme.md
View File

@@ -1,7 +1,7 @@
---
date: "2023-03-02T21:00:00+05:00"
slug: "profile-readme"
sidebar_position: 12
sidebar_position: 42
---
# Profile READMEs

0
versioned_docs/version-1.25/usage/push.md → versioned_docs/version-1.25/usage/repository/push.md
View File

2
versioned_docs/version-1.25/usage/repo-mirror.md → versioned_docs/version-1.25/usage/repository/repo-mirror.md
View File

@@ -6,7 +6,7 @@ aliases:
- /en-us/repo-mirror
---
# Repository Mirror
# Mirror Repository
Repository mirroring allows for the mirroring of repositories to and from external sources. You can use it to mirror branches, tags, and commits between repositories.

4
versioned_docs/version-1.25/usage/template-repositories.md → versioned_docs/version-1.25/usage/repository/template-repositories.md
View File

@@ -1,12 +1,12 @@
---
date: "2019-11-28:00:00+02:00"
slug: "template-repositories"
sidebar_position: 14
sidebar_position: 44
aliases:
- /en-us/template-repositories
---
# Template Repositories
# Template Repository
Since Gitea `1.11`, you can create template repositories.
When creating a repo based on a template, you can copy most of its content, and even auto-inject variables into it.

0
versioned_docs/version-1.22/usage/webhooks.md → versioned_docs/version-1.25/usage/repository/webhooks.md
View File

9
versioned_docs/version-1.25/usage/user-setting/_category_.json Normal file
View File

@@ -0,0 +1,9 @@
{
"label": "User Setting",
"position": 200,
"link": {
"type": "generated-index",
"slug": "/usage/user-setting",
"description": "Configuring user preferences and settings"
}
}

0
versioned_docs/version-1.25/usage/multi-factor-authentication.md → versioned_docs/version-1.25/usage/user-setting/multi-factor-authentication.md
View File

189
versioned_docs/version-1.25/usage/webhooks.md
View File

@@ -1,189 +0,0 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "webhooks"
sidebar_position: 30
aliases:
- /en-us/webhooks
---
# Webhooks
Gitea supports webhooks for repository events. This can be configured in the settings
page `/:username/:reponame/settings/hooks` by a repository admin. Webhooks can also be configured on a per-organization and whole system basis.
All event pushes are POST requests. The methods currently supported are:
- Gitea (can also be a GET request)
- Gogs
- Slack
- Discord
- Dingtalk
- Telegram
- Microsoft Teams
- Feishu
- Wechatwork
- Packagist
### Event information
:::warning
The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755
:::
The following is an example of event information that will be sent by Gitea to
a Payload URL:
```http
X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-GitHub-Event: push
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gogs-Event: push
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gitea-Event: push
```
```json
{
"secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
"ref": "refs/heads/develop",
"before": "28e1879d029cb852e4844d9c718537df08844e03",
"after": "bffeb74224043ba2feb48d137756c8a9331c449a",
"compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
"commits": [
{
"id": "bffeb74224043ba2feb48d137756c8a9331c449a",
"message": "Webhooks Yay!",
"url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
"author": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"committer": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"timestamp": "2017-03-13T13:52:11-04:00"
}
],
"repository": {
"id": 140,
"owner": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"name": "webhooks",
"full_name": "gitea/webhooks",
"description": "",
"private": false,
"fork": false,
"html_url": "http://localhost:3000/gitea/webhooks",
"ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
"clone_url": "http://localhost:3000/gitea/webhooks.git",
"website": "",
"stars_count": 0,
"forks_count": 1,
"watchers_count": 1,
"open_issues_count": 7,
"default_branch": "master",
"created_at": "2017-02-26T04:29:06-05:00",
"updated_at": "2017-03-13T13:51:58-04:00"
},
"pusher": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"sender": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
}
}
```
### Example
This is an example of how to use webhooks to run a php script upon push requests to the repository.
In your repository Settings, under Webhooks, Setup a Gitea webhook as follows:
- Target URL: http://mydomain.com/webhook.php
- HTTP Method: POST
- POST Content Type: application/json
- Secret: 123
- Trigger On: Push Events
- Active: Checked
Now on your server create the php file webhook.php
```php
<?php
$secret_key = '123';
// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
exit();
}
// get content type
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
if ($content_type != 'application/json') {
error_log('FAILED - not application/json - '. $content_type);
exit();
}
// get payload
$payload = trim(file_get_contents("php://input"));
if (empty($payload)) {
error_log('FAILED - no payload');
exit();
}
// get header signature
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
if (empty($header_signature)) {
error_log('FAILED - header signature missing');
exit();
}
// calculate payload signature
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
// check payload signature against header signature
if ($header_signature !== $payload_signature) {
error_log('FAILED - payload signature');
exit();
}
// convert json to array
$decoded = json_decode($payload, true);
// check for json decode errors
if (json_last_error() !== JSON_ERROR_NONE) {
error_log('FAILED - json decode - '. json_last_error());
exit();
}
// success, do something
```
There is a Test Delivery button in the webhook settings that allows to test the configuration as well as a list of the most Recent Deliveries.
### Authorization header
**With 1.19**, Gitea hooks can be configured to send an [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) to the webhook target.