gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-11 05:24:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add v1.26 documentation (#376)

Browse Source 
Co-authored-by: silverwind <2021+silverwind@noreply.gitea.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/376
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
This commit is contained in:
Lunny Xiao
2026-04-09 19:27:32 +00:00
parent b339770f3c
commit a7ab7af00f
329 changed files with 71328 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

30
versioned_docs/version-1.26/usage/repository/blame.md Normal file
View File

@@ -0,0 +1,30 @@
---
date: "2023-08-14T00:00:00+00:00"
slug: "blame"
sidebar_position: 13
aliases:
- /en-us/blame
- /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`.

31
versioned_docs/version-1.26/usage/repository/clone-filter.md Normal file
View File

@@ -0,0 +1,31 @@
---
date: "2021-02-02"
slug: "clone-filters"
sidebar_position: 25
aliases:
- /en-us/clone-filters
- /clone-filters
---
# Clone filters (partial clone)
Git introduces `--filter` option to `git clone` command, which filters out
large files and objects (such as blobs) to create partial clone of a repo.
Clone filters are especially useful for large repo and/or metered connection,
where full clone (without `--filter`) can be expensive (as all history data
must be downloaded).
This requires Git version 2.22 or later, both on the Gitea server and on the
client. For clone filters to work properly, make sure that Git version
on the client is at least the same as on the server (or later). Login to
Gitea server as admin and head to Site Administration -> Configuration to
see Git version of the server.
By default, clone filters are enabled, unless `DISABLE_PARTIAL_CLONE` under
`[git]` is set to `true`.
See [GitHub blog post: Get up to speed with partial clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/)
for common use cases of clone filters (blobless and treeless clones), and
[GitLab docs for partial clone](https://docs.gitlab.com/ee/topics/git/partial_clone.html)
for more advanced use cases (such as filter by file size and remove
filters to turn partial clone into full clone).

57
versioned_docs/version-1.26/usage/repository/code-owners.md Normal file
View File

@@ -0,0 +1,57 @@
---
date: "2023-05-24T16:00:00+00:00"
slug: "code-owners"
sidebar_position: 30
aliases:
- /en-us/code-owners
- /code-owners
---
# Code Owners
Gitea maintains code owner files. It looks for it in the following locations in this order:
- `./CODEOWNERS`
- `./docs/CODEOWNERS`
- `./.gitea/CODEOWNERS`
And stops at the first found file.
File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
Regexp specified in golang Regex format.
Regexp can start with `!` for negative rules - match all files except specified.
Example file:
```bash
.*\\.go @user1 @user2 # This is comment
# Comment too
# You can assigning code owning for users or teams
frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
# You can use negative pattern
!frontend/src/.* @org1/team3 @user5
# You can use power of go regexp
docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
!/assets/.*\\.(bin|exe|msi) @user9
```
### Escaping
You can escape characters `#`, ` ` (space) and `\` with `\`, like:
```
dir/with\#hashtag @user1
path\ with\ space @user2
path/with\\backslash @user3
```
Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
```
path/\\.with\\.dots
path/with\\+plus
```

38
versioned_docs/version-1.26/usage/repository/incoming-email.md Normal file
View File

@@ -0,0 +1,38 @@
---
date: "2022-12-01T00:00:00+00:00"
slug: "incoming-email"
sidebar_position: 130
aliases:
- /en-us/incoming-email
- /incoming-email
---
# Incoming Email
Gitea supports the execution of several actions through incoming mails. This page describes how to set this up.
## Requirements
Handling incoming email messages requires an IMAP-enabled email account.
The recommended strategy is to use [email sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) but a catch-all mailbox does work too.
The receiving email address contains a user/action specific token which tells Gitea which action should be performed.
This token is expected in the `To` and `Delivered-To` header fields.
Gitea tries to detect automatic responses to skip and the email server should be configured to reduce the incoming noise too (spam, newsletter).
## Configuration
To activate the handling of incoming email messages you have to configure the `email.incoming` section in the configuration file.
The `REPLY_TO_ADDRESS` contains the address an email client will respond to.
This address needs to contain the `%{token}` placeholder which will be replaced with a token describing the user/action.
This placeholder must only appear once in the address and must be in the user part of the address (before the `@`).
An example using email sub-addressing may look like this: `incoming+%{token}@example.com`
If a catch-all mailbox is used, the placeholder may be used anywhere in the user part of the address: `incoming+%{token}@example.com`, `incoming_%{token}@example.com`, `%{token}@example.com`
## Security
Be careful when choosing the domain used for receiving incoming email.
It's recommended receiving incoming email on a subdomain, such as `incoming.example.com` to prevent potential security problems with other services running on `example.com`.

155
versioned_docs/version-1.26/usage/repository/markdown.md Normal file
View File

@@ -0,0 +1,155 @@
---
date: "2025-04-05T00:00:00+08:00"
slug: "markdown"
aliases:
- /markdown
sidebar_position: 4
---
# Markdown
Gitea uses MarkDown structured text in many places, you can recognise it by the `.md` file extension.
Markdown is plain text format for writing structured documents, allowing one to write
"plain" text files that nonetheless have _"fancy"_ **formatting**, while still keeping the plain-text version readable.
Unfortunately, due to historical implementation differences, many subtle dialects exist.
To avoid adding to the confusion, Gitea tries to follow "[GitHub Flavoured Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/)" as close as possible.
"GFM" is an extension on top of the rigorously-specified [CommonMark](https://commonmark.org/) standard.
CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse)
and git forges (GitHub, GitLab and our very own Gitea), thus you shouldn't run into any surprises with Gitea.
For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation:
- [Basic formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
- [Advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting)
For a deeper history about CommonMark, its spec, and its reason for existence, see [CommonMark.org](https://commonmark.org/).
## Rendering options
Some Gitea's markdown rendering behaviors can be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
## Link path resolving
When rendering links for `<a href>`, `<img src>` and `<video src>`, Gitea resolves the link paths in the rendering context.
- If the link is an absolute path with scheme, the link is kept as-is.
- If the link is an URL path, it is resolved with the base path of current rendering context.
- In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: `/owner-name/repo-name`.
- In a repository file context (markdown files in the repository), the base path is current git ref path.
### Special link tokens
To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
This will always resolve to Gitea's ROOT_URL.
Gitea also supports GitHub's `?raw=1` query parameter.
A request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to
`/owner-name/repo-name/raw/branch/main/file`. This makes it possible to target raw contents from relative links
(normally, the `src/` section of the path is provided automatically by Gitea and cannot be overriden).
### Link handling examples
For example, when rendering a markdown file in `/owner-name/repo-name/src/branch/main/dir`:
1) Absolute with scheme: Link `https://example.org` will be rendered as-is.
2) Relative from current file: Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
3) Relative from repo root: Link `/sub/file` (note leading slash) is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
4) Raw media: If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
5) Raw relative: `sub/file?raw=1` will resolve to `/owner-name/repo-name/src/branch/main/dir/sub/file?raw=1`,
which will redirect to `/owner-name/repo-name/raw/branch/main/dir/sub/file`.
6) explicit root: Link `/:root/any-path` is always resolved to `$ROOT_URL/any-path` without any further processing.
## Issue and pull-request reference
Using issue/pull-request numbers in a list:
```
* #123
* #456
```
It will be rendered with issue titles to:
```
* the issue title (#123)
* the other issue title (#456)
```
## Theme-based image display
Gitea supports the GitHub-like theme-based image display. Supported syntax:
* Use Markdown image
```
![My-Light](my-light.png#gh-light-mode-only)![My-Dark](my-dark.png#gh-dark-mode-only)
```
* Use `<img>` HTML tag
```
<img src="my-light.png#gh-light-mode-only" height="120" width="120"/>
<img src="my-dark.png#gh-dark-mode-only" height="120" width="120"/>
```
* Use `<picture>` with `<source media>` (only works for themes with "auto" color preference)
```
<picture>
<source media="(prefers-color-scheme: dark)" srcset="my-dark.png">
<source media="(prefers-color-scheme: light)" srcset="my-light.png">
<img src="my-light.png">
</picture>
```
## Math expressions
Gitea supports GitHub-like math expression formatting.
### Inline expression
- ``` $\alpha$ ```: quoted by single-dollar `$`
- ``` $$\alpha$$ ```: quoted by double-dollar `$$`
- ``` $`\alpha`$ ```: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.
### Block expression
Using `$$`:
````
$$
\alpha
$$
````
Using code-block with language:
````
```math
\alpha
```
````
## Frontmatter
Gitea supports frontmatter and Table of Contents (TOC) rendering. By default, frontmatter rendering is enabled, and TOC rendering is disabled.
### Enabling TOC rendering
To enable TOC rendering for a markdown file, add `include_toc: true` to its frontmatter section.
### Disabling frontmatter
To disable frontmatter rendering for a markdown file, add `gitea: none` to its frontmatter section.
### Example
```yaml
---
include_toc: true
gitea: none
---
```
Then, when you preview this markdown file in Gitea, the frontmatter section will not be rendered, and a Table of Contents will be generated at the top of the content.

55
versioned_docs/version-1.26/usage/repository/migration.md Normal file
View File

@@ -0,0 +1,55 @@
---
date: "2024-09-11T09:30:00+08:00"
slug: "migration"
sidebar_position: 40
aliases:
- /migration
---
# Migration
You can migrate repositories from other Git services to your Gitea instance.
## How to migrate from Gogs/GitHub/GitLab to Gitea
To migrate from Gogs to Gitea:
- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
[Example (requires login)](https://demo.gitea.com/repo/migrate)
To migrate from GitLab to Gitea, you can use this non-affiliated tool:
https://github.com/loganinak/MigrateGitlabToGogs
## How to migrate from AWS CodeCommit to Gitea
- To use the AWS CodeCommit API, Gitea requires an access key ID and a secret access key. For security reasons, we recommend creating a new user with the minimum necessary permissions and generating an access key ID and secret access key for the migration. The minimum permissions required for this user are as follows:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"codecommit:GetRepository",
"codecommit:GitPull",
"codecommit:ListPullRequests",
"codecommit:GetPullRequest",
"codecommit:GetCommentsForPullRequest"
],
"Resource": [
"arn:aws:codecommit:<region>:<account>:<Repo-to-Migrate>
}
]
}
```
- If you do not need to migrate pull requests, you can remove the `ListPullRequests`, `GetPullRequest`, and `GetCommentsForPullRequest` actions.
- For instructions on how to create an IAM user and assign permissions, you can refer to this [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
- To clone this repository, Gitea requires HTTPS Git credentials. You can create HTTPS Git credentials according to this [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html).

18
versioned_docs/version-1.26/usage/repository/profile-readme.md Normal file
View File

@@ -0,0 +1,18 @@
---
date: "2023-03-02T21:00:00+05:00"
slug: "profile-readme"
sidebar_position: 42
aliases:
- /profile-readme
---
# 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)

64
versioned_docs/version-1.26/usage/repository/push.md Normal file
View File

@@ -0,0 +1,64 @@
---
date: "2020-07-06T16:00:00+02:00"
slug: "push"
sidebar_position: 15
aliases:
- /en-us/push-to-create
- /en-us/push-options
- /push
---
# Push
There are some additional features when pushing commits to Gitea server.
## Open PR through Push
When you push commits to a non-default branch for the first time,
you will receive a link you can click on to visit the compare page of your branch compared to your main branch.
From there, it's easy to create a pull request, even if you want to target another branch.
![Gitea Push Hint](/gitea-push-hint.png)
## Push Options
In Gitea `1.13`, support for some [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)
were added.
### Supported Options
- `repo.private` (true|false) - Change the repository's visibility.
This is particularly useful when combined with push-to-create.
- `repo.template` (true|false) - Change whether the repository is a template.
Example of changing a repository's visibility to public:
```shell
git push -o repo.private=false -u origin main
```
## Push To Create
Push to create is a feature that allows you to push to a repository that does not exist yet in Gitea. This is useful for automation and for allowing users to create repositories without having to go through the web interface. This feature is disabled by default.
### Enabling Push To Create
In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#repository-repository).
### Using Push To Create
Assuming you have a git repository in the current directory, you can push to a repository that does not exist yet in Gitea by running the following command:
```shell
# Add the remote you want to push to
git remote add origin git@{domain}:{username}/{repo name that does not exist yet}.git
# push to the remote
git push -u origin main
```
This assumes you are using an SSH remote, but you can also use HTTPS remotes as well.
Push-to-create will default to the visibility defined by `DEFAULT_PUSH_CREATE_PRIVATE` in `app.ini`.

99
versioned_docs/version-1.26/usage/repository/repo-mirror.md Normal file
View File

@@ -0,0 +1,99 @@
---
date: "2021-05-13T00:00:00-00:00"
slug: "repo-mirror"
sidebar_position: 45
aliases:
- /en-us/repo-mirror
- /repo-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.
## Use cases
The following are some possible use cases for repository mirroring:
- You migrated to Gitea but still need to keep your project in another source. In that case, you can simply set it up to mirror to Gitea (pull) and all the essential history of commits, tags, and branches are available in your Gitea instance.
- You have old projects in another source that you don’t use actively anymore, but don’t want to remove for archiving purposes. In that case, you can create a push mirror so that your active Gitea repository can push its changes to the old location.
## Pulling from a remote repository
For an existing remote repository, you can set up pull mirroring as follows:
1. Select **New Migration** in the **Create...** menu on the top right.
2. Select the remote repository service.
3. Enter a repository URL.
4. If the repository needs authentication fill in your authentication information.
5. Check the box **This repository will be a mirror**.
6. Select **Migrate repository** to save the configuration.
The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings.
:::warning
:exclamation::exclamation: You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation:
:::
## Pushing to a remote repository
For an existing repository, you can set up push mirroring as follows:
1. In your repository, go to **Settings** > **Repository**, and then the **Mirror Settings** section.
2. Enter a repository URL.
3. If the repository needs authentication expand the **Authorization** section and fill in your authentication information. Note that the requested **password** can also be your access token.
4. Select **Add Push Mirror** to save the configuration.
The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it.
:::warning
:exclamation::exclamation: This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation:
:::
### Setting up a push mirror from Gitea to GitHub
To set up a mirror from Gitea to GitHub, you need to follow these steps:
1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the *public_repo* box checked. Also check the **workflow** checkbox in case your repo uses GitHub Actions for continuous integration.
2. Create a repository with that name on GitHub. Unlike Gitea, GitHub does not support creating repositories by pushing to the remote. You can also use an existing remote repo if it has the same commit history as your Gitea repo.
3. In the settings of your Gitea repo, fill in the **Git Remote Repository URL**: `https://github.com/<your_github_group>/<your_github_project>.git`.
4. Fill in the **Authorization** fields with your GitHub username and the personal access token as **Password**.
5. (Optional, available on Gitea 1.18+) Select `Sync when new commits are pushed` so that the mirror will be updated as well as soon as there are changes. You can also disable the periodic sync if you like.
6. Select **Add Push Mirror** to save the configuration.
The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
### Setting up a push mirror from Gitea to GitLab
To set up a mirror from Gitea to GitLab, you need to follow these steps:
1. Create a [GitLab personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with *write_repository* scope.
2. Fill in the **Git Remote Repository URL**: `https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`.
3. Fill in the **Authorization** fields with `oauth2` as **Username** and your GitLab personal access token as **Password**.
4. Select **Add Push Mirror** to save the configuration.
The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
### Setting up a push mirror from Gitea to Bitbucket
To set up a mirror from Gitea to Bitbucket, you need to follow these steps:
1. Create a [Bitbucket app password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) with the *Repository Write* box checked.
2. Fill in the **Git Remote Repository URL**: `https://bitbucket.org/<your_bitbucket_group_or_name>/<your_bitbucket_project>.git`.
3. Fill in the **Authorization** fields with your Bitbucket username and the app password as **Password**.
4. Select **Add Push Mirror** to save the configuration.
The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
### Mirror an existing ssh repository
Currently Gitea supports no ssh push mirrors. You can work around this by adding a `post-receive` hook to your Gitea repository that pushes manually.
1. Make sure the user running Gitea has access to the git repo you are trying to mirror to from shell.
2. On the web interface at the repository settings > git hooks add a post-receive hook for the mirror. I.e.
```
#!/usr/bin/env bash
git push --mirror --quiet git@github.com:username/repository.git &>/dev/null &
echo "GitHub mirror initiated .."
```

87
versioned_docs/version-1.26/usage/repository/template-repositories.md Normal file
View File

@@ -0,0 +1,87 @@
---
date: "2019-11-28:00:00+02:00"
slug: "template-repositories"
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.
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 |

190
versioned_docs/version-1.26/usage/repository/webhooks.md Normal file
View File

@@ -0,0 +1,190 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "webhooks"
sidebar_position: 30
aliases:
- /en-us/webhooks
- /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.