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/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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 |

732
versioned_docs/version-1.27/usage/repository/webhooks.md Normal file
View File

@@ -0,0 +1,732 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "webhooks"
sidebar_position: 30
aliases:
- /en-us/webhooks
- /webhooks
---
# Webhooks
Gitea can send outbound webhooks for repository activity. Repository webhooks are
configured at `/:username/:reponame/settings/hooks` by a repository admin.
Equivalent webhook pages also exist for organizations, users, and system
administration.
Webhook configuration is available at four scopes:
- `Repository webhooks`: Trigger only for activity in one repository.
- `Organization webhooks`: Trigger for activity in repositories owned by that
organization.
- `User webhooks`: Trigger for activity in repositories owned by that user.
- `System webhooks`: Trigger for all eligible activity on the instance.
Gitea also supports admin-defined `default webhooks`. These are not an extra
delivery scope. Instead, they are copied into newly created repositories and
then behave like ordinary repository webhooks.
Gitea supports these outgoing webhook integrations:
- Gitea
- Gogs
- Slack
- Discord
- Dingtalk
- Telegram
- Microsoft Teams
- Feishu
- Matrix
- Wechatwork
- Packagist
The `Gitea` and `Gogs` webhook types send generic webhook payloads. The chat and
service integrations listed above transform the same internal event into a
service-specific request body.
## Configuration
This section covers the webhook settings you choose when creating or editing a
webhook.
### Configuring a webhook
When creating a webhook, the main options are:
- `Target URL`: The endpoint that receives the delivery.
- `HTTP Method`: Usually `POST` for generic webhooks.
- `POST Content Type`: `application/json` or
`application/x-www-form-urlencoded` for generic webhooks.
- `Secret`: Used to sign the raw request body with HMAC.
- `Authorization Header`: Optional custom `Authorization` header to send with
each request.
- `Branch Filter`: Optional glob filter for branch and tag related events.
- `Trigger On`: `Push Events`, `All Events`, or a custom event selection.
- `Active`: Whether the webhook is enabled.
:::note
Older examples may still show a `secret` field inside the JSON payload. Current
Gitea versions do not send the webhook secret in the payload body. Always verify
the request by checking the signature headers instead.
:::
### Branch filters
The branch filter uses glob syntax compatible with
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile).
- Empty, `*`, or `**` matches everything.
- A plain branch name such as `main` matches that branch.
- Full refs such as `refs/tags/v*` are also supported.
- Brace expressions such as `{main,release/*}` are supported.
- The filter only applies to events that carry a git ref, such as `create`,
`delete`, and `push`.
- Events without a ref, such as issues or releases, ignore the branch filter.
Examples:
- `main`
- `{main,feature/*}`
- `{refs/heads/feature/*,refs/tags/release/*}`
### Authorization header
Gitea can be configured to send a custom
[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
with each webhook delivery. This is independent from the webhook secret:
- Use the secret to verify integrity with HMAC.
- Use the `Authorization` header when the receiving endpoint requires
application-level authentication.
## Delivery
This section describes how Gitea sends webhook deliveries and how receivers can
identify and verify them.
### Delivery behavior
- Webhooks are delivered asynchronously over HTTP.
- Generic `Gitea` and `Gogs` webhooks support `POST` and `GET`; `POST` is the
normal choice.
- For `POST` requests, the payload can be sent either as JSON
(`application/json`) or as a form field named `payload`
(`application/x-www-form-urlencoded`).
- Provider-specific integrations may use the HTTP method and body format
required by that provider.
### Delivery headers
Every delivery includes a unique delivery ID and event headers. For
GitHub-compatible integrations, Gitea also sends the corresponding GitHub and
Gogs header names.
| Header | Description |
| --- | --- |
| `X-Gitea-Delivery` | Unique delivery UUID for this attempt. |
| `X-Gitea-Event` | Normalized event name, such as `push`, `issues`, or `pull_request`. |
| `X-Gitea-Event-Type` | More specific event type, such as `issue_assign` or `pull_request_review_comment`. |
| `X-Gitea-Signature` | Hex-encoded HMAC-SHA256 of the raw request body, without a prefix. |
| `X-Gitea-Hook-Installation-Target-Type` | Where the webhook is defined: typically `repository`, `organization`, `user`, or `system`. Default webhooks are copied into repositories before delivery, so they are typically delivered as `repository`. |
| `X-Gogs-Delivery`, `X-Gogs-Event`, `X-Gogs-Event-Type`, `X-Gogs-Signature` | Compatibility headers with the same values as the Gitea variants. |
| `X-GitHub-Delivery`, `X-GitHub-Event`, `X-GitHub-Event-Type` | GitHub-style compatibility headers. |
| `X-GitHub-Hook-Installation-Target-Type` | GitHub-style compatibility header for the webhook scope. |
| `X-Hub-Signature` | GitHub-compatible HMAC-SHA1 header in the form `sha1=<digest>`. |
| `X-Hub-Signature-256` | GitHub-compatible HMAC-SHA256 header in the form `sha256=<digest>`. |
If no secret is configured, the signature headers are still present, but their
digest values are empty.
#### `Event` versus `Event-Type`
Some Gitea webhook subscriptions are grouped together under one normalized event
name. For example, an issue assignment delivery uses the issue event group:
```http
X-Gitea-Event: issues
X-Gitea-Event-Type: issue_assign
X-GitHub-Event: issues
X-GitHub-Event-Type: issue_assign
```
Use `X-Gitea-Event-Type` when you need the exact trigger that fired the webhook.
#### Validating deliveries
Gitea signs the raw request body with your webhook secret. To validate a
delivery:
1. Read the request body exactly as it was received.
2. Compute the HMAC-SHA256 digest with your webhook secret.
3. Compare the result with `X-Gitea-Signature` or with the GitHub-compatible
`X-Hub-Signature-256` header.
4. Use a constant-time comparison when possible.
Important details:
- `X-Gitea-Signature` contains only the lowercase hexadecimal SHA-256 digest.
- `X-Hub-Signature-256` contains the same digest with a `sha256=` prefix.
- `X-Hub-Signature` is also sent for compatibility and uses SHA-1.
- The body must be verified before JSON parsing or any other modification.
##### PHP example
The following example verifies a generic `Gitea` webhook sent as
`application/json`.
```php
<?php
$secret = '123';
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
exit('Only POST is allowed');
}
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
if ($payload === false || $signature === '') {
http_response_code(400);
exit('Missing payload or signature');
}
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
$data = json_decode($payload, true);
if (!is_array($data)) {
http_response_code(400);
exit('Invalid JSON payload');
}
http_response_code(204);
```
## Events
This section follows the same event-by-event style used by GitHub's webhook
documentation: each event describes when it occurs and what the top-level
payload contains.
The event groups match the webhook settings UI: `Repository Events`,
`Issue Events`, `Pull Request Events`, and `Workflow Events`.
### Repository Events
- `create`, `delete`, `fork`, `push`, `wiki`, `repository`, `release`, `package`, `status`
#### `create`
This event occurs when a branch or tag is created.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `sha` | `string` | **Required.** The object ID of the created reference. |
| `ref` | `string` | **Required.** The created branch or tag name. |
| `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
| `repository` | `object` | **Required.** The repository where the reference was created. |
| `sender` | `object` | **Required.** The user who created the reference. |
#### `delete`
This event occurs when a branch or tag is deleted.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `ref` | `string` | **Required.** The deleted branch or tag name. |
| `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
| `pusher_type` | `string` | **Required.** The actor type that deleted the ref. Current Gitea payloads use `user`. |
| `repository` | `object` | **Required.** The repository where the reference was deleted. |
| `sender` | `object` | **Required.** The user who deleted the reference. |
#### `fork`
This event occurs when a repository is forked.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `forkee` | `object` | **Required.** The newly created fork repository. |
| `repository` | `object` | **Required.** The original repository that was forked. |
| `sender` | `object` | **Required.** The user who created the fork. |
#### `push`
This event occurs when commits are pushed to a branch or tag.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `ref` | `string` | **Required.** The full pushed ref, such as `refs/heads/main`. |
| `before` | `string` | **Required.** The commit SHA before the push. |
| `after` | `string` | **Required.** The commit SHA after the push. |
| `compare_url` | `string` | **Required.** URL to compare `before` and `after`. |
| `commits` | `array` | **Required.** Commits included in the push. |
| `total_commits` | `integer` | **Required.** Number of commits in the push. |
| `head_commit` | `object` | The most recent commit in the push. |
| `repository` | `object` | **Required.** The repository that received the push. |
| `pusher` | `object` | **Required.** The user who performed the push. |
| `sender` | `object` | **Required.** The user who triggered the webhook. |
#### `wiki`
This event occurs when a wiki page is created, edited, or deleted.
**Action type:** `created`, `edited`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The wiki page action. |
| `repository` | `object` | **Required.** The repository that owns the wiki. |
| `sender` | `object` | **Required.** The user who changed the wiki page. |
| `page` | `string` | **Required.** The wiki page name. |
| `comment` | `string` | The wiki commit message or comment. |
#### `repository`
This event occurs when a repository is created or deleted.
**Action type:** `created`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The repository action. |
| `repository` | `object` | **Required.** The repository that was created or deleted. |
| `organization` | `object` | Present when the repository belongs to an organization. |
| `sender` | `object` | **Required.** The user who performed the action. |
#### `release`
This event occurs when a release is published, updated, or deleted.
**Action type:** `published`, `updated`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The release action. |
| `release` | `object` | **Required.** The release that was acted on. |
| `repository` | `object` | **Required.** The repository containing the release. |
| `sender` | `object` | **Required.** The user who performed the action. |
#### `package`
This event occurs when a package is created or deleted.
**Action type:** `created`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The package action. |
| `repository` | `object` | The repository associated with the package, when applicable. |
| `package` | `object` | **Required.** The package that was acted on. |
| `organization` | `object` | Present when the package owner is an organization. |
| `sender` | `object` | **Required.** The user who performed the action. |
#### `status`
This event occurs when a commit status is created or updated through the API.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `commit` | `object` | The commit associated with the status. |
| `context` | `string` | **Required.** The status context, such as `ci/build`. |
| `created_at` | `string` | **Required.** The time the status was created. |
| `description` | `string` | Status description text. |
| `id` | `integer` | **Required.** The status identifier. |
| `repository` | `object` | **Required.** The repository containing the commit. |
| `sender` | `object` | **Required.** The user who created the status. |
| `sha` | `string` | **Required.** The commit SHA. |
| `state` | `string` | **Required.** The state, such as `pending`, `success`, `error`, or `failure`. |
| `target_url` | `string` | Target URL associated with the status. |
| `updated_at` | `string` | The time the status was last updated. |
Unlike most other payloads, this event does not use an `action` field. The
state transition is represented by `state`.
### Issue Events
- `issues`, `issue_assign`, `issue_label`, `issue_milestone`, `issue_comment`
#### `issues`
This event occurs when an issue is opened, closed, reopened, edited, or deleted.
**Action type:** `opened`, `closed`, `reopened`, `edited`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The issue action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_assign`
This event occurs when an issue is assigned or unassigned.
**Action type:** `assigned`, `unassigned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The assignment action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_label`
This event occurs when issue labels are updated or cleared.
**Action type:** `label_updated`, `label_cleared`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The label update action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_milestone`
This event occurs when an issue is milestoned or demilestoned.
**Action type:** `milestoned`, `demilestoned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The milestone action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_comment`
This event occurs when a comment on an issue is created, edited, or deleted.
**Action type:** `created`, `edited`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The comment action. |
| `issue` | `object` | **Required.** The issue that the comment belongs to. |
| `pull_request` | `object` | Present only when the comment is on a pull request timeline. |
| `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
| `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `is_pull` | `boolean` | **Required.** Whether the comment is on a pull request timeline. |
### Pull Request Events
- `pull_request`, `pull_request_assign`, `pull_request_label`, `pull_request_milestone`, `pull_request_comment`, `pull_request_review`, `pull_request_review_approved`, `pull_request_review_rejected`, `pull_request_review_comment`, `pull_request_sync`, `pull_request_review_request`
#### `pull_request`
This event occurs when a pull request is opened, closed, reopened, edited, or deleted.
**Action type:** `opened`, `closed`, `reopened`, `edited`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The pull request action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_assign`
This event occurs when a pull request is assigned or unassigned.
**Action type:** `assigned`, `unassigned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The assignment action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_label`
This event occurs when pull request labels are updated or cleared.
**Action type:** `label_updated`, `label_cleared`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The label update action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_milestone`
This event occurs when a pull request is milestoned or demilestoned.
**Action type:** `milestoned`, `demilestoned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The milestone action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_comment`
This event occurs when a timeline comment on a pull request is created, edited, or deleted.
**Action type:** `created`, `edited`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The comment action. |
| `issue` | `object` | **Required.** The related issue record for the pull request. |
| `pull_request` | `object` | **Required.** The pull request the timeline comment belongs to. |
| `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
| `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `is_pull` | `boolean` | **Required.** Always `true` for this event. |
#### `pull_request_review`
This is a subscription-only umbrella event in the webhook settings UI.
It does not have its own delivery payload. When selected, Gitea delivers the
more specific events `pull_request_review_approved`,
`pull_request_review_rejected`, and `pull_request_review_comment`.
#### `pull_request_review_approved`
This event occurs when a pull request review is submitted with approval.
**Action type:** `reviewed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `reviewed`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who submitted the review. |
| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `approved`. |
#### `pull_request_review_rejected`
This event occurs when a pull request review is submitted with a rejection or a
request for changes.
**Action type:** `reviewed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `reviewed`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who submitted the review. |
| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `rejected`. |
#### `pull_request_review_comment`
This event occurs when a pull request review is submitted as a comment.
**Action type:** `reviewed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `reviewed`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who submitted the review. |
| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `comment`. |
#### `pull_request_sync`
This event occurs when a pull request is synchronized after new commits are pushed.
**Action type:** `synchronized`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `synchronized`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was synchronized. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the synchronization. |
| `commit_id` | `string` | The commit SHA associated with the synchronization event, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_review_request`
This event occurs when a reviewer is requested or a review request is removed.
**Action type:** `review_requested`, `review_request_removed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The review request action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | The reviewer that was requested or removed. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
### Workflow Events
- `workflow_run`, `workflow_job`
#### `workflow_run`
This event occurs when a Gitea Actions workflow run changes status.
**Action type:** `queued`, `waiting`, `in_progress`, `completed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The workflow run status transition. |
| `workflow` | `object` | **Required.** The workflow definition. |
| `workflow_run` | `object` | **Required.** The workflow run that was acted on. |
| `pull_request` | `object` | Present when the workflow run is associated with a pull request. |
| `organization` | `object` | Present when the repository owner is an organization. |
| `repository` | `object` | **Required.** The repository containing the workflow. |
| `sender` | `object` | **Required.** The user who triggered the workflow run update. |
#### `workflow_job`
This event occurs when a Gitea Actions workflow job changes status.
**Action type:** `queued`, `waiting`, `in_progress`, `completed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The workflow job status transition. |
| `workflow_job` | `object` | **Required.** The workflow job that was acted on. |
| `pull_request` | `object` | Present when the workflow job is associated with a pull request. |
| `organization` | `object` | Present when the repository owner is an organization. |
| `repository` | `object` | **Required.** The repository containing the workflow job. |
| `sender` | `object` | **Required.** The user who triggered the workflow job update. |
## Testing, recent deliveries, and replay
Each webhook page includes:
- `Test Delivery`, which sends a synthetic `push` event for the repository.
- `Recent Deliveries`, which shows request and response details.
- `Redelivery`, which replays an earlier webhook delivery.
If the repository has no commits yet, the test delivery uses a generated fake
commit so the webhook can still be exercised.
## Administration notes
Administrators can further control webhook delivery with instance settings such
as host allow lists, delivery timeouts, and cleanup policies. See the
[Webhook section of the configuration cheat sheet](../../administration/config-cheat-sheet.md#webhook-webhook).