mirror of
https://gitea.com/gitea/docs.git
synced 2026-06-11 04:31:26 +00:00
update webhook documentation (#393)
Reviewed-on: https://gitea.com/gitea/docs/pulls/393
This commit is contained in:
Lunny Xiao
@@ -9,11 +9,26 @@ aliases:
|
||||
|
||||
# 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 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.
|
||||
|
||||
- Gitea (can also be a GET request)
|
||||
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
|
||||
@@ -21,170 +36,697 @@ All event pushes are POST requests. The methods currently supported are:
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### Event information
|
||||
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.
|
||||
|
||||
:::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
|
||||
## 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.
|
||||
:::
|
||||
|
||||
The following is an example of event information that will be sent by Gitea to
|
||||
a Payload URL:
|
||||
### 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-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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
Use `X-Gitea-Event-Type` when you need the exact trigger that fired the webhook.
|
||||
|
||||
### Example
|
||||
#### Validating deliveries
|
||||
|
||||
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:
|
||||
Gitea signs the raw request body with your webhook secret. To validate a
|
||||
delivery:
|
||||
|
||||
- Target URL: http://mydomain.com/webhook.php
|
||||
- HTTP Method: POST
|
||||
- POST Content Type: application/json
|
||||
- Secret: 123
|
||||
- Trigger On: Push Events
|
||||
- Active: Checked
|
||||
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.
|
||||
|
||||
Now on your server create the php file webhook.php
|
||||
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_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
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.
|
||||
## Events
|
||||
|
||||
### Authorization header
|
||||
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.
|
||||
|
||||
**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.
|
||||
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).
|
||||
|
||||
@@ -8,178 +8,713 @@ aliases:
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
|
||||
所有事件推送都是 POST 请求。目前支持：
|
||||
Gitea 可以为仓库活动发送出站 Webhook。仓库级 Webhook 由仓库管理员在
|
||||
`/:username/:reponame/settings/hooks` 中配置。组织、用户和系统管理级别
|
||||
也有对应的 Webhook 配置页面。
|
||||
|
||||
- Gitea (也可以是 GET 请求)
|
||||
Webhook 配置支持四种作用域：
|
||||
|
||||
- `仓库 Webhook`：仅对单个仓库中的活动触发。
|
||||
- `组织 Webhook`：对该组织拥有的仓库中的活动触发。
|
||||
- `用户 Webhook`：对该用户拥有的仓库中的活动触发。
|
||||
- `系统 Webhook`：对实例中的所有符合条件的活动触发。
|
||||
|
||||
Gitea 还支持由管理员定义的 `默认 Webhook`。它并不是额外的投递作用域，
|
||||
而是会在新仓库创建时被复制到仓库中，之后按普通仓库 Webhook 的方式工作。
|
||||
|
||||
Gitea 支持以下出站 Webhook 集成：
|
||||
|
||||
- Gitea
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk（钉钉）
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork（企业微信）
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### 事件信息
|
||||
`Gitea` 和 `Gogs` 类型会发送通用 Webhook 负载。上面列出的聊天和服务集成
|
||||
会将同一个内部事件转换为各自服务所需的请求体格式。
|
||||
|
||||
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
|
||||
本页分为三个部分：
|
||||
|
||||
以下是 Gitea 将发送给 payload URL 的事件信息示例：
|
||||
- `配置`：如何配置 Webhook 设置，例如 URL、密钥、分支过滤器和授权头。
|
||||
- `投递`：Gitea 如何发送 Webhook 请求、会携带哪些请求头，以及如何校验投递。
|
||||
- `事件`：Gitea 会投递哪些事件，以及每个事件包含哪些顶层 payload 参数。
|
||||
|
||||
## 配置
|
||||
|
||||
本节介绍在创建或编辑 Webhook 时可以设置的选项。
|
||||
|
||||
### 配置 Webhook
|
||||
|
||||
创建 Webhook 时，主要配置项包括：
|
||||
|
||||
- `Target URL`：接收投递的目标地址。
|
||||
- `HTTP Method`：通用 Webhook 通常使用 `POST`。
|
||||
- `POST Content Type`：通用 Webhook 可使用 `application/json` 或
|
||||
`application/x-www-form-urlencoded`。
|
||||
- `Secret`：用于对原始请求体进行 HMAC 签名。
|
||||
- `Authorization Header`：可选的自定义 `Authorization` 请求头，会随每次请求发送。
|
||||
- `Branch Filter`：可选的分支或标签过滤规则。
|
||||
- `Trigger On`：`Push Events`、`All Events` 或自定义事件选择。
|
||||
- `Active`：是否启用该 Webhook。
|
||||
|
||||
:::note
|
||||
旧示例里可能仍会在 JSON payload 中看到 `secret` 字段。当前版本的 Gitea
|
||||
不会再把 Webhook 密钥放进 payload 正文中。请始终通过签名请求头来验证请求。
|
||||
:::
|
||||
|
||||
### 分支过滤器
|
||||
|
||||
分支过滤器使用与
|
||||
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
|
||||
兼容的 glob 语法。
|
||||
|
||||
- 空值、`*` 或 `**` 表示匹配全部。
|
||||
- 像 `main` 这样的普通分支名会匹配该分支。
|
||||
- 也支持 `refs/tags/v*` 这样的完整 ref。
|
||||
- 支持 `{main,release/*}` 这样的花括号表达式。
|
||||
- 过滤器只对带 git ref 的事件生效，例如 `create`、`delete` 和 `push`。
|
||||
- 不带 ref 的事件，例如 issue 或 release，会忽略分支过滤器。
|
||||
|
||||
示例：
|
||||
|
||||
- `main`
|
||||
- `{main,feature/*}`
|
||||
- `{refs/heads/feature/*,refs/tags/release/*}`
|
||||
|
||||
### 授权头
|
||||
|
||||
Gitea 可以配置为在每次 Webhook 投递时发送自定义
|
||||
[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
它与 Webhook 密钥是相互独立的：
|
||||
|
||||
- 使用密钥通过 HMAC 校验请求完整性。
|
||||
- 当接收端需要应用层认证时，使用 `Authorization` 请求头。
|
||||
|
||||
## 投递
|
||||
|
||||
本节说明 Gitea 如何发送 Webhook 投递，以及接收端如何识别和验证这些请求。
|
||||
|
||||
### 投递行为
|
||||
|
||||
- Webhook 会通过 HTTP 异步投递。
|
||||
- 通用 `Gitea` 和 `Gogs` Webhook 支持 `POST` 与 `GET`；通常应使用 `POST`。
|
||||
- 对于 `POST` 请求，payload 可以直接作为 JSON
|
||||
（`application/json`）发送，也可以放在名为 `payload` 的表单字段中
|
||||
（`application/x-www-form-urlencoded`）。
|
||||
- 某些特定服务的集成可能会使用该服务要求的 HTTP 方法和请求体格式。
|
||||
|
||||
### 投递请求头
|
||||
|
||||
每次投递都包含唯一的 delivery ID 和事件请求头。对于兼容 GitHub 的集成，
|
||||
Gitea 也会同时发送对应的 GitHub 和 Gogs 风格请求头。
|
||||
|
||||
| 请求头 | 说明 |
|
||||
| --- | --- |
|
||||
| `X-Gitea-Delivery` | 本次投递尝试的唯一 UUID。 |
|
||||
| `X-Gitea-Event` | 规范化事件名，例如 `push`、`issues` 或 `pull_request`。 |
|
||||
| `X-Gitea-Event-Type` | 更具体的事件类型，例如 `issue_assign` 或 `pull_request_review_comment`。 |
|
||||
| `X-Gitea-Signature` | 原始请求体的十六进制 HMAC-SHA256 值，不带前缀。 |
|
||||
| `X-Gitea-Hook-Installation-Target-Type` | Webhook 定义所在范围，通常是 `repository`、`organization`、`user` 或 `system`。默认 Webhook 会先复制到仓库后再投递，因此通常会表现为 `repository`。 |
|
||||
| `X-Gogs-Delivery`、`X-Gogs-Event`、`X-Gogs-Event-Type`、`X-Gogs-Signature` | 与 Gitea 对应请求头值相同的兼容请求头。 |
|
||||
| `X-GitHub-Delivery`、`X-GitHub-Event`、`X-GitHub-Event-Type` | GitHub 风格兼容请求头。 |
|
||||
| `X-GitHub-Hook-Installation-Target-Type` | GitHub 风格的 Webhook 作用域请求头。 |
|
||||
| `X-Hub-Signature` | GitHub 兼容的 HMAC-SHA1 请求头，格式为 `sha1=<digest>`。 |
|
||||
| `X-Hub-Signature-256` | GitHub 兼容的 HMAC-SHA256 请求头，格式为 `sha256=<digest>`。 |
|
||||
|
||||
如果未配置密钥，签名请求头仍然会存在，但摘要值为空。
|
||||
|
||||
#### `Event` 与 `Event-Type`
|
||||
|
||||
某些 Gitea Webhook 订阅会被归类到同一个规范化事件名下。例如，issue 指派
|
||||
投递会归类到 issue 事件组：
|
||||
|
||||
```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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你需要知道真正触发投递的具体事件类型，请使用 `X-Gitea-Event-Type`。
|
||||
|
||||
### 示例
|
||||
#### 校验投递
|
||||
|
||||
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
|
||||
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
|
||||
Gitea 会使用你的 Webhook 密钥对原始请求体进行签名。要校验一次投递：
|
||||
|
||||
- 目标 URL：http://mydomain.com/webhook.php
|
||||
- HTTP 方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 触发条件：推送事件
|
||||
- 激活：勾选
|
||||
1. 按接收到的原始内容读取请求体。
|
||||
2. 使用 Webhook 密钥计算 HMAC-SHA256 摘要。
|
||||
3. 将结果与 `X-Gitea-Signature` 或 GitHub 兼容的
|
||||
`X-Hub-Signature-256` 进行比较。
|
||||
4. 尽量使用常量时间比较函数。
|
||||
|
||||
现在在你的服务器上创建 php 文件 webhook.php。
|
||||
注意事项：
|
||||
|
||||
- `X-Gitea-Signature` 仅包含小写十六进制的 SHA-256 摘要。
|
||||
- `X-Hub-Signature-256` 使用相同摘要，但带有 `sha256=` 前缀。
|
||||
- `X-Hub-Signature` 也会出于兼容性目的发送，其算法是 SHA-1。
|
||||
- 在完成签名校验之前，不应先解析 JSON 或修改请求体。
|
||||
|
||||
##### PHP 示例
|
||||
|
||||
下面的示例演示如何校验以 `application/json` 发送的通用 `Gitea` Webhook。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$secret_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
|
||||
## 事件
|
||||
|
||||
### 授权头（Authorization header）
|
||||
本节采用与 GitHub Webhook 文档类似的按事件逐项描述方式：每个事件都会说明
|
||||
其触发时机，以及 payload 中包含哪些顶层字段。
|
||||
|
||||
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
事件分组与 Webhook 设置界面中的分组一致：`Repository Events`、
|
||||
`Issue Events`、`Pull Request Events` 和 `Workflow Events`。
|
||||
|
||||
### 仓库事件
|
||||
|
||||
- `create`、`delete`、`fork`、`push`、`wiki`、`repository`、`release`、`package`、`status`
|
||||
|
||||
#### `create`
|
||||
|
||||
当分支或标签被创建时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `sha` | `string` | **必填。** 新建引用对应的对象 ID。 |
|
||||
| `ref` | `string` | **必填。** 被创建的分支名或标签名。 |
|
||||
| `ref_type` | `string` | **必填。** 引用类型，例如 `branch` 或 `tag`。 |
|
||||
| `repository` | `object` | **必填。** 创建该引用的仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建该引用的用户。 |
|
||||
|
||||
#### `delete`
|
||||
|
||||
当分支或标签被删除时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被删除的分支名或标签名。 |
|
||||
| `ref_type` | `string` | **必填。** 引用类型，例如 `branch` 或 `tag`。 |
|
||||
| `pusher_type` | `string` | **必填。** 删除该 ref 的行为主体类型。当前 Gitea payload 中使用 `user`。 |
|
||||
| `repository` | `object` | **必填。** 删除该引用所在的仓库。 |
|
||||
| `sender` | `object` | **必填。** 删除该引用的用户。 |
|
||||
|
||||
#### `fork`
|
||||
|
||||
当仓库被 fork 时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `forkee` | `object` | **必填。** 新创建的 fork 仓库。 |
|
||||
| `repository` | `object` | **必填。** 被 fork 的原始仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建 fork 的用户。 |
|
||||
|
||||
#### `push`
|
||||
|
||||
当提交被推送到某个分支或标签时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被推送的完整 ref，例如 `refs/heads/main`。 |
|
||||
| `before` | `string` | **必填。** 推送前的提交 SHA。 |
|
||||
| `after` | `string` | **必填。** 推送后的提交 SHA。 |
|
||||
| `compare_url` | `string` | **必填。** 用于比较 `before` 和 `after` 的 URL。 |
|
||||
| `commits` | `array` | **必填。** 本次推送包含的提交列表。 |
|
||||
| `total_commits` | `integer` | **必填。** 本次推送中的提交数量。 |
|
||||
| `head_commit` | `object` | 本次推送中的最新提交。 |
|
||||
| `repository` | `object` | **必填。** 接收此次推送的仓库。 |
|
||||
| `pusher` | `object` | **必填。** 执行推送的用户。 |
|
||||
| `sender` | `object` | **必填。** 触发 Webhook 的用户。 |
|
||||
|
||||
#### `wiki`
|
||||
|
||||
当 Wiki 页面被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Wiki 页面操作类型。 |
|
||||
| `repository` | `object` | **必填。** 拥有该 Wiki 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 修改 Wiki 页面的用户。 |
|
||||
| `page` | `string` | **必填。** Wiki 页面名称。 |
|
||||
| `comment` | `string` | Wiki 提交信息或备注。 |
|
||||
|
||||
#### `repository`
|
||||
|
||||
当仓库被创建或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 仓库操作类型。 |
|
||||
| `repository` | `object` | **必填。** 被创建或删除的仓库。 |
|
||||
| `organization` | `object` | 当仓库属于某个组织时会出现。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `release`
|
||||
|
||||
当发布版本被发布、更新或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `published`、`updated`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Release 操作类型。 |
|
||||
| `release` | `object` | **必填。** 被操作的发布版本。 |
|
||||
| `repository` | `object` | **必填。** 包含该发布版本的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `package`
|
||||
|
||||
当包被创建或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 包操作类型。 |
|
||||
| `repository` | `object` | 与该包关联的仓库；如果适用则会出现。 |
|
||||
| `package` | `object` | **必填。** 被操作的包。 |
|
||||
| `organization` | `object` | 当包所有者是组织时会出现。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `status`
|
||||
|
||||
当通过 API 创建或更新提交状态时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `commit` | `object` | 与该状态关联的提交。 |
|
||||
| `context` | `string` | **必填。** 状态上下文，例如 `ci/build`。 |
|
||||
| `created_at` | `string` | **必填。** 状态创建时间。 |
|
||||
| `description` | `string` | 状态描述文本。 |
|
||||
| `id` | `integer` | **必填。** 状态标识符。 |
|
||||
| `repository` | `object` | **必填。** 包含该提交的仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建该状态的用户。 |
|
||||
| `sha` | `string` | **必填。** 提交 SHA。 |
|
||||
| `state` | `string` | **必填。** 状态值，例如 `pending`、`success`、`error` 或 `failure`。 |
|
||||
| `target_url` | `string` | 与该状态关联的目标 URL。 |
|
||||
| `updated_at` | `string` | 状态最后更新时间。 |
|
||||
|
||||
与多数其他 payload 不同，此事件不使用 `action` 字段，状态变化通过 `state`
|
||||
字段表示。
|
||||
|
||||
### 议题事件
|
||||
|
||||
- `issues`、`issue_assign`、`issue_label`、`issue_milestone`、`issue_comment`
|
||||
|
||||
#### `issues`
|
||||
|
||||
当 issue 被打开、关闭、重新打开、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Issue 操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_assign`
|
||||
|
||||
当 issue 被指派或取消指派时，会触发此事件。
|
||||
|
||||
**动作类型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_label`
|
||||
|
||||
当 issue 标签被更新或清空时，会触发此事件。
|
||||
|
||||
**动作类型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 标签更新操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_milestone`
|
||||
|
||||
当 issue 被设置里程碑或移除里程碑时，会触发此事件。
|
||||
|
||||
**动作类型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_comment`
|
||||
|
||||
当 issue 评论被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评论操作类型。 |
|
||||
| `issue` | `object` | **必填。** 该评论所属的 issue。 |
|
||||
| `pull_request` | `object` | 当该评论位于 pull request 时间线上时会出现。 |
|
||||
| `comment` | `object` | **必填。** 被创建、编辑或删除的评论。 |
|
||||
| `changes` | `object` | 可选。当操作类型为 `edited` 时，表示评论正文的旧值。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `is_pull` | `boolean` | **必填。** 该评论是否位于 pull request 时间线上。 |
|
||||
|
||||
### Pull Request 事件
|
||||
|
||||
- `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`
|
||||
|
||||
当 pull request 被打开、关闭、重新打开、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Pull request 操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_assign`
|
||||
|
||||
当 pull request 被指派或取消指派时，会触发此事件。
|
||||
|
||||
**动作类型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_label`
|
||||
|
||||
当 pull request 标签被更新或清空时，会触发此事件。
|
||||
|
||||
**动作类型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 标签更新操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_milestone`
|
||||
|
||||
当 pull request 被设置里程碑或移除里程碑时，会触发此事件。
|
||||
|
||||
**动作类型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_comment`
|
||||
|
||||
当 pull request 时间线评论被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评论操作类型。 |
|
||||
| `issue` | `object` | **必填。** 与该 pull request 关联的 issue 记录。 |
|
||||
| `pull_request` | `object` | **必填。** 评论所属的 pull request。 |
|
||||
| `comment` | `object` | **必填。** 被创建、编辑或删除的评论。 |
|
||||
| `changes` | `object` | 可选。当操作类型为 `edited` 时，表示评论正文的旧值。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `is_pull` | `boolean` | **必填。** 对此事件来说始终为 `true`。 |
|
||||
|
||||
#### `pull_request_review`
|
||||
|
||||
这是 Webhook 设置界面中的一个仅用于订阅的汇总事件。
|
||||
|
||||
它不会生成独立的投递 payload。勾选后，Gitea 实际投递的是更具体的
|
||||
`pull_request_review_approved`、`pull_request_review_rejected` 和
|
||||
`pull_request_review_comment` 事件。
|
||||
|
||||
#### `pull_request_review_approved`
|
||||
|
||||
当 pull request review 以批准形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `approved`。 |
|
||||
|
||||
#### `pull_request_review_rejected`
|
||||
|
||||
当 pull request review 以拒绝或请求修改的形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `rejected`。 |
|
||||
|
||||
#### `pull_request_review_comment`
|
||||
|
||||
当 pull request review 以评论形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `comment`。 |
|
||||
|
||||
#### `pull_request_sync`
|
||||
|
||||
当新的提交被推送后，pull request 被同步时，会触发此事件。
|
||||
|
||||
**动作类型：** `synchronized`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `synchronized`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被同步的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行同步操作的用户。 |
|
||||
| `commit_id` | `string` | 与该同步事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_review_request`
|
||||
|
||||
当请求审查者或移除审查请求时，会触发此事件。
|
||||
|
||||
**动作类型：** `review_requested`、`review_request_removed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评审请求操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 被请求或被移除的评审者。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
### 工作流事件
|
||||
|
||||
- `workflow_run`、`workflow_job`
|
||||
|
||||
#### `workflow_run`
|
||||
|
||||
当 Gitea Actions 工作流运行状态发生变化时，会触发此事件。
|
||||
|
||||
**动作类型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流运行状态变化。 |
|
||||
| `workflow` | `object` | **必填。** 工作流定义。 |
|
||||
| `workflow_run` | `object` | **必填。** 被操作的工作流运行记录。 |
|
||||
| `pull_request` | `object` | 当该工作流运行与某个 pull request 相关时会出现。 |
|
||||
| `organization` | `object` | 当仓库所有者是组织时会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该工作流的仓库。 |
|
||||
| `sender` | `object` | **必填。** 触发该工作流运行更新的用户。 |
|
||||
|
||||
#### `workflow_job`
|
||||
|
||||
当 Gitea Actions 工作流任务状态发生变化时，会触发此事件。
|
||||
|
||||
**动作类型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流任务状态变化。 |
|
||||
| `workflow_job` | `object` | **必填。** 被操作的工作流任务。 |
|
||||
| `pull_request` | `object` | 当该工作流任务与某个 pull request 相关时会出现。 |
|
||||
| `organization` | `object` | 当仓库所有者是组织时会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该工作流任务的仓库。 |
|
||||
| `sender` | `object` | **必填。** 触发该工作流任务更新的用户。 |
|
||||
|
||||
## 测试、最近投递与重放
|
||||
|
||||
每个 Webhook 页面都包含：
|
||||
|
||||
- `Test Delivery`：会向仓库发送一次模拟的 `push` 事件。
|
||||
- `Recent Deliveries`：显示请求和响应详情。
|
||||
- `Redelivery`：重新投递一次历史 Webhook 记录。
|
||||
|
||||
如果仓库还没有任何提交，测试投递会使用一个生成的假提交，以便仍然可以测试
|
||||
Webhook。
|
||||
|
||||
## 管理说明
|
||||
|
||||
管理员还可以通过实例级设置控制 Webhook 投递，例如主机允许列表、投递超时和
|
||||
清理策略。详见
|
||||
[配置速查表中的 Webhook 小节](../../administration/config-cheat-sheet.md#webhook-webhook)。
|
||||
|
||||
@@ -8,178 +8,713 @@ aliases:
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
|
||||
所有事件推送都是 POST 请求。目前支持：
|
||||
Gitea 可以为仓库活动发送出站 Webhook。仓库级 Webhook 由仓库管理员在
|
||||
`/:username/:reponame/settings/hooks` 中配置。组织、用户和系统管理级别
|
||||
也有对应的 Webhook 配置页面。
|
||||
|
||||
- Gitea (也可以是 GET 请求)
|
||||
Webhook 配置支持四种作用域：
|
||||
|
||||
- `仓库 Webhook`：仅对单个仓库中的活动触发。
|
||||
- `组织 Webhook`：对该组织拥有的仓库中的活动触发。
|
||||
- `用户 Webhook`：对该用户拥有的仓库中的活动触发。
|
||||
- `系统 Webhook`：对实例中的所有符合条件的活动触发。
|
||||
|
||||
Gitea 还支持由管理员定义的 `默认 Webhook`。它并不是额外的投递作用域，
|
||||
而是会在新仓库创建时被复制到仓库中，之后按普通仓库 Webhook 的方式工作。
|
||||
|
||||
Gitea 支持以下出站 Webhook 集成：
|
||||
|
||||
- Gitea
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk（钉钉）
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork（企业微信）
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### 事件信息
|
||||
`Gitea` 和 `Gogs` 类型会发送通用 Webhook 负载。上面列出的聊天和服务集成
|
||||
会将同一个内部事件转换为各自服务所需的请求体格式。
|
||||
|
||||
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
|
||||
本页分为三个部分：
|
||||
|
||||
以下是 Gitea 将发送给 payload URL 的事件信息示例：
|
||||
- `配置`：如何配置 Webhook 设置，例如 URL、密钥、分支过滤器和授权头。
|
||||
- `投递`：Gitea 如何发送 Webhook 请求、会携带哪些请求头，以及如何校验投递。
|
||||
- `事件`：Gitea 会投递哪些事件，以及每个事件包含哪些顶层 payload 参数。
|
||||
|
||||
## 配置
|
||||
|
||||
本节介绍在创建或编辑 Webhook 时可以设置的选项。
|
||||
|
||||
### 配置 Webhook
|
||||
|
||||
创建 Webhook 时，主要配置项包括：
|
||||
|
||||
- `Target URL`：接收投递的目标地址。
|
||||
- `HTTP Method`：通用 Webhook 通常使用 `POST`。
|
||||
- `POST Content Type`：通用 Webhook 可使用 `application/json` 或
|
||||
`application/x-www-form-urlencoded`。
|
||||
- `Secret`：用于对原始请求体进行 HMAC 签名。
|
||||
- `Authorization Header`：可选的自定义 `Authorization` 请求头，会随每次请求发送。
|
||||
- `Branch Filter`：可选的分支或标签过滤规则。
|
||||
- `Trigger On`：`Push Events`、`All Events` 或自定义事件选择。
|
||||
- `Active`：是否启用该 Webhook。
|
||||
|
||||
:::note
|
||||
旧示例里可能仍会在 JSON payload 中看到 `secret` 字段。当前版本的 Gitea
|
||||
不会再把 Webhook 密钥放进 payload 正文中。请始终通过签名请求头来验证请求。
|
||||
:::
|
||||
|
||||
### 分支过滤器
|
||||
|
||||
分支过滤器使用与
|
||||
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
|
||||
兼容的 glob 语法。
|
||||
|
||||
- 空值、`*` 或 `**` 表示匹配全部。
|
||||
- 像 `main` 这样的普通分支名会匹配该分支。
|
||||
- 也支持 `refs/tags/v*` 这样的完整 ref。
|
||||
- 支持 `{main,release/*}` 这样的花括号表达式。
|
||||
- 过滤器只对带 git ref 的事件生效，例如 `create`、`delete` 和 `push`。
|
||||
- 不带 ref 的事件，例如 issue 或 release，会忽略分支过滤器。
|
||||
|
||||
示例：
|
||||
|
||||
- `main`
|
||||
- `{main,feature/*}`
|
||||
- `{refs/heads/feature/*,refs/tags/release/*}`
|
||||
|
||||
### 授权头
|
||||
|
||||
Gitea 可以配置为在每次 Webhook 投递时发送自定义
|
||||
[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
它与 Webhook 密钥是相互独立的：
|
||||
|
||||
- 使用密钥通过 HMAC 校验请求完整性。
|
||||
- 当接收端需要应用层认证时，使用 `Authorization` 请求头。
|
||||
|
||||
## 投递
|
||||
|
||||
本节说明 Gitea 如何发送 Webhook 投递，以及接收端如何识别和验证这些请求。
|
||||
|
||||
### 投递行为
|
||||
|
||||
- Webhook 会通过 HTTP 异步投递。
|
||||
- 通用 `Gitea` 和 `Gogs` Webhook 支持 `POST` 与 `GET`；通常应使用 `POST`。
|
||||
- 对于 `POST` 请求，payload 可以直接作为 JSON
|
||||
（`application/json`）发送，也可以放在名为 `payload` 的表单字段中
|
||||
（`application/x-www-form-urlencoded`）。
|
||||
- 某些特定服务的集成可能会使用该服务要求的 HTTP 方法和请求体格式。
|
||||
|
||||
### 投递请求头
|
||||
|
||||
每次投递都包含唯一的 delivery ID 和事件请求头。对于兼容 GitHub 的集成，
|
||||
Gitea 也会同时发送对应的 GitHub 和 Gogs 风格请求头。
|
||||
|
||||
| 请求头 | 说明 |
|
||||
| --- | --- |
|
||||
| `X-Gitea-Delivery` | 本次投递尝试的唯一 UUID。 |
|
||||
| `X-Gitea-Event` | 规范化事件名，例如 `push`、`issues` 或 `pull_request`。 |
|
||||
| `X-Gitea-Event-Type` | 更具体的事件类型，例如 `issue_assign` 或 `pull_request_review_comment`。 |
|
||||
| `X-Gitea-Signature` | 原始请求体的十六进制 HMAC-SHA256 值，不带前缀。 |
|
||||
| `X-Gitea-Hook-Installation-Target-Type` | Webhook 定义所在范围，通常是 `repository`、`organization`、`user` 或 `system`。默认 Webhook 会先复制到仓库后再投递，因此通常会表现为 `repository`。 |
|
||||
| `X-Gogs-Delivery`、`X-Gogs-Event`、`X-Gogs-Event-Type`、`X-Gogs-Signature` | 与 Gitea 对应请求头值相同的兼容请求头。 |
|
||||
| `X-GitHub-Delivery`、`X-GitHub-Event`、`X-GitHub-Event-Type` | GitHub 风格兼容请求头。 |
|
||||
| `X-GitHub-Hook-Installation-Target-Type` | GitHub 风格的 Webhook 作用域请求头。 |
|
||||
| `X-Hub-Signature` | GitHub 兼容的 HMAC-SHA1 请求头，格式为 `sha1=<digest>`。 |
|
||||
| `X-Hub-Signature-256` | GitHub 兼容的 HMAC-SHA256 请求头，格式为 `sha256=<digest>`。 |
|
||||
|
||||
如果未配置密钥，签名请求头仍然会存在，但摘要值为空。
|
||||
|
||||
#### `Event` 与 `Event-Type`
|
||||
|
||||
某些 Gitea Webhook 订阅会被归类到同一个规范化事件名下。例如，issue 指派
|
||||
投递会归类到 issue 事件组：
|
||||
|
||||
```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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你需要知道真正触发投递的具体事件类型，请使用 `X-Gitea-Event-Type`。
|
||||
|
||||
### 示例
|
||||
#### 校验投递
|
||||
|
||||
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
|
||||
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
|
||||
Gitea 会使用你的 Webhook 密钥对原始请求体进行签名。要校验一次投递：
|
||||
|
||||
- 目标 URL：http://mydomain.com/webhook.php
|
||||
- HTTP 方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 触发条件：推送事件
|
||||
- 激活：勾选
|
||||
1. 按接收到的原始内容读取请求体。
|
||||
2. 使用 Webhook 密钥计算 HMAC-SHA256 摘要。
|
||||
3. 将结果与 `X-Gitea-Signature` 或 GitHub 兼容的
|
||||
`X-Hub-Signature-256` 进行比较。
|
||||
4. 尽量使用常量时间比较函数。
|
||||
|
||||
现在在你的服务器上创建 php 文件 webhook.php。
|
||||
注意事项：
|
||||
|
||||
- `X-Gitea-Signature` 仅包含小写十六进制的 SHA-256 摘要。
|
||||
- `X-Hub-Signature-256` 使用相同摘要，但带有 `sha256=` 前缀。
|
||||
- `X-Hub-Signature` 也会出于兼容性目的发送，其算法是 SHA-1。
|
||||
- 在完成签名校验之前，不应先解析 JSON 或修改请求体。
|
||||
|
||||
##### PHP 示例
|
||||
|
||||
下面的示例演示如何校验以 `application/json` 发送的通用 `Gitea` Webhook。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$secret_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
|
||||
## 事件
|
||||
|
||||
### 授权头（Authorization header）
|
||||
本节采用与 GitHub Webhook 文档类似的按事件逐项描述方式：每个事件都会说明
|
||||
其触发时机，以及 payload 中包含哪些顶层字段。
|
||||
|
||||
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
事件分组与 Webhook 设置界面中的分组一致：`Repository Events`、
|
||||
`Issue Events`、`Pull Request Events` 和 `Workflow Events`。
|
||||
|
||||
### 仓库事件
|
||||
|
||||
- `create`、`delete`、`fork`、`push`、`wiki`、`repository`、`release`、`package`、`status`
|
||||
|
||||
#### `create`
|
||||
|
||||
当分支或标签被创建时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `sha` | `string` | **必填。** 新建引用对应的对象 ID。 |
|
||||
| `ref` | `string` | **必填。** 被创建的分支名或标签名。 |
|
||||
| `ref_type` | `string` | **必填。** 引用类型，例如 `branch` 或 `tag`。 |
|
||||
| `repository` | `object` | **必填。** 创建该引用的仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建该引用的用户。 |
|
||||
|
||||
#### `delete`
|
||||
|
||||
当分支或标签被删除时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被删除的分支名或标签名。 |
|
||||
| `ref_type` | `string` | **必填。** 引用类型，例如 `branch` 或 `tag`。 |
|
||||
| `pusher_type` | `string` | **必填。** 删除该 ref 的行为主体类型。当前 Gitea payload 中使用 `user`。 |
|
||||
| `repository` | `object` | **必填。** 删除该引用所在的仓库。 |
|
||||
| `sender` | `object` | **必填。** 删除该引用的用户。 |
|
||||
|
||||
#### `fork`
|
||||
|
||||
当仓库被 fork 时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `forkee` | `object` | **必填。** 新创建的 fork 仓库。 |
|
||||
| `repository` | `object` | **必填。** 被 fork 的原始仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建 fork 的用户。 |
|
||||
|
||||
#### `push`
|
||||
|
||||
当提交被推送到某个分支或标签时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被推送的完整 ref，例如 `refs/heads/main`。 |
|
||||
| `before` | `string` | **必填。** 推送前的提交 SHA。 |
|
||||
| `after` | `string` | **必填。** 推送后的提交 SHA。 |
|
||||
| `compare_url` | `string` | **必填。** 用于比较 `before` 和 `after` 的 URL。 |
|
||||
| `commits` | `array` | **必填。** 本次推送包含的提交列表。 |
|
||||
| `total_commits` | `integer` | **必填。** 本次推送中的提交数量。 |
|
||||
| `head_commit` | `object` | 本次推送中的最新提交。 |
|
||||
| `repository` | `object` | **必填。** 接收此次推送的仓库。 |
|
||||
| `pusher` | `object` | **必填。** 执行推送的用户。 |
|
||||
| `sender` | `object` | **必填。** 触发 Webhook 的用户。 |
|
||||
|
||||
#### `wiki`
|
||||
|
||||
当 Wiki 页面被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Wiki 页面操作类型。 |
|
||||
| `repository` | `object` | **必填。** 拥有该 Wiki 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 修改 Wiki 页面的用户。 |
|
||||
| `page` | `string` | **必填。** Wiki 页面名称。 |
|
||||
| `comment` | `string` | Wiki 提交信息或备注。 |
|
||||
|
||||
#### `repository`
|
||||
|
||||
当仓库被创建或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 仓库操作类型。 |
|
||||
| `repository` | `object` | **必填。** 被创建或删除的仓库。 |
|
||||
| `organization` | `object` | 当仓库属于某个组织时会出现。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `release`
|
||||
|
||||
当发布版本被发布、更新或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `published`、`updated`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Release 操作类型。 |
|
||||
| `release` | `object` | **必填。** 被操作的发布版本。 |
|
||||
| `repository` | `object` | **必填。** 包含该发布版本的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `package`
|
||||
|
||||
当包被创建或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 包操作类型。 |
|
||||
| `repository` | `object` | 与该包关联的仓库；如果适用则会出现。 |
|
||||
| `package` | `object` | **必填。** 被操作的包。 |
|
||||
| `organization` | `object` | 当包所有者是组织时会出现。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `status`
|
||||
|
||||
当通过 API 创建或更新提交状态时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `commit` | `object` | 与该状态关联的提交。 |
|
||||
| `context` | `string` | **必填。** 状态上下文，例如 `ci/build`。 |
|
||||
| `created_at` | `string` | **必填。** 状态创建时间。 |
|
||||
| `description` | `string` | 状态描述文本。 |
|
||||
| `id` | `integer` | **必填。** 状态标识符。 |
|
||||
| `repository` | `object` | **必填。** 包含该提交的仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建该状态的用户。 |
|
||||
| `sha` | `string` | **必填。** 提交 SHA。 |
|
||||
| `state` | `string` | **必填。** 状态值，例如 `pending`、`success`、`error` 或 `failure`。 |
|
||||
| `target_url` | `string` | 与该状态关联的目标 URL。 |
|
||||
| `updated_at` | `string` | 状态最后更新时间。 |
|
||||
|
||||
与多数其他 payload 不同，此事件不使用 `action` 字段，状态变化通过 `state`
|
||||
字段表示。
|
||||
|
||||
### 议题事件
|
||||
|
||||
- `issues`、`issue_assign`、`issue_label`、`issue_milestone`、`issue_comment`
|
||||
|
||||
#### `issues`
|
||||
|
||||
当 issue 被打开、关闭、重新打开、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Issue 操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_assign`
|
||||
|
||||
当 issue 被指派或取消指派时，会触发此事件。
|
||||
|
||||
**动作类型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_label`
|
||||
|
||||
当 issue 标签被更新或清空时，会触发此事件。
|
||||
|
||||
**动作类型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 标签更新操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_milestone`
|
||||
|
||||
当 issue 被设置里程碑或移除里程碑时，会触发此事件。
|
||||
|
||||
**动作类型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_comment`
|
||||
|
||||
当 issue 评论被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评论操作类型。 |
|
||||
| `issue` | `object` | **必填。** 该评论所属的 issue。 |
|
||||
| `pull_request` | `object` | 当该评论位于 pull request 时间线上时会出现。 |
|
||||
| `comment` | `object` | **必填。** 被创建、编辑或删除的评论。 |
|
||||
| `changes` | `object` | 可选。当操作类型为 `edited` 时，表示评论正文的旧值。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `is_pull` | `boolean` | **必填。** 该评论是否位于 pull request 时间线上。 |
|
||||
|
||||
### Pull Request 事件
|
||||
|
||||
- `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`
|
||||
|
||||
当 pull request 被打开、关闭、重新打开、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Pull request 操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_assign`
|
||||
|
||||
当 pull request 被指派或取消指派时，会触发此事件。
|
||||
|
||||
**动作类型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_label`
|
||||
|
||||
当 pull request 标签被更新或清空时，会触发此事件。
|
||||
|
||||
**动作类型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 标签更新操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_milestone`
|
||||
|
||||
当 pull request 被设置里程碑或移除里程碑时，会触发此事件。
|
||||
|
||||
**动作类型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_comment`
|
||||
|
||||
当 pull request 时间线评论被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评论操作类型。 |
|
||||
| `issue` | `object` | **必填。** 与该 pull request 关联的 issue 记录。 |
|
||||
| `pull_request` | `object` | **必填。** 评论所属的 pull request。 |
|
||||
| `comment` | `object` | **必填。** 被创建、编辑或删除的评论。 |
|
||||
| `changes` | `object` | 可选。当操作类型为 `edited` 时，表示评论正文的旧值。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `is_pull` | `boolean` | **必填。** 对此事件来说始终为 `true`。 |
|
||||
|
||||
#### `pull_request_review`
|
||||
|
||||
这是 Webhook 设置界面中的一个仅用于订阅的汇总事件。
|
||||
|
||||
它不会生成独立的投递 payload。勾选后，Gitea 实际投递的是更具体的
|
||||
`pull_request_review_approved`、`pull_request_review_rejected` 和
|
||||
`pull_request_review_comment` 事件。
|
||||
|
||||
#### `pull_request_review_approved`
|
||||
|
||||
当 pull request review 以批准形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `approved`。 |
|
||||
|
||||
#### `pull_request_review_rejected`
|
||||
|
||||
当 pull request review 以拒绝或请求修改的形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `rejected`。 |
|
||||
|
||||
#### `pull_request_review_comment`
|
||||
|
||||
当 pull request review 以评论形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `comment`。 |
|
||||
|
||||
#### `pull_request_sync`
|
||||
|
||||
当新的提交被推送后，pull request 被同步时，会触发此事件。
|
||||
|
||||
**动作类型：** `synchronized`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `synchronized`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被同步的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行同步操作的用户。 |
|
||||
| `commit_id` | `string` | 与该同步事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_review_request`
|
||||
|
||||
当请求审查者或移除审查请求时，会触发此事件。
|
||||
|
||||
**动作类型：** `review_requested`、`review_request_removed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评审请求操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 被请求或被移除的评审者。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
### 工作流事件
|
||||
|
||||
- `workflow_run`、`workflow_job`
|
||||
|
||||
#### `workflow_run`
|
||||
|
||||
当 Gitea Actions 工作流运行状态发生变化时，会触发此事件。
|
||||
|
||||
**动作类型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流运行状态变化。 |
|
||||
| `workflow` | `object` | **必填。** 工作流定义。 |
|
||||
| `workflow_run` | `object` | **必填。** 被操作的工作流运行记录。 |
|
||||
| `pull_request` | `object` | 当该工作流运行与某个 pull request 相关时会出现。 |
|
||||
| `organization` | `object` | 当仓库所有者是组织时会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该工作流的仓库。 |
|
||||
| `sender` | `object` | **必填。** 触发该工作流运行更新的用户。 |
|
||||
|
||||
#### `workflow_job`
|
||||
|
||||
当 Gitea Actions 工作流任务状态发生变化时，会触发此事件。
|
||||
|
||||
**动作类型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流任务状态变化。 |
|
||||
| `workflow_job` | `object` | **必填。** 被操作的工作流任务。 |
|
||||
| `pull_request` | `object` | 当该工作流任务与某个 pull request 相关时会出现。 |
|
||||
| `organization` | `object` | 当仓库所有者是组织时会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该工作流任务的仓库。 |
|
||||
| `sender` | `object` | **必填。** 触发该工作流任务更新的用户。 |
|
||||
|
||||
## 测试、最近投递与重放
|
||||
|
||||
每个 Webhook 页面都包含：
|
||||
|
||||
- `Test Delivery`：会向仓库发送一次模拟的 `push` 事件。
|
||||
- `Recent Deliveries`：显示请求和响应详情。
|
||||
- `Redelivery`：重新投递一次历史 Webhook 记录。
|
||||
|
||||
如果仓库还没有任何提交，测试投递会使用一个生成的假提交，以便仍然可以测试
|
||||
Webhook。
|
||||
|
||||
## 管理说明
|
||||
|
||||
管理员还可以通过实例级设置控制 Webhook 投递，例如主机允许列表、投递超时和
|
||||
清理策略。详见
|
||||
[配置速查表中的 Webhook 小节](../../administration/config-cheat-sheet.md#webhook-webhook)。
|
||||
|
||||
@@ -8,178 +8,713 @@ aliases:
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
|
||||
所有事件推送都是 POST 请求。目前支持：
|
||||
Gitea 可以为仓库活动发送出站 Webhook。仓库级 Webhook 由仓库管理员在
|
||||
`/:username/:reponame/settings/hooks` 中配置。组织、用户和系统管理级别
|
||||
也有对应的 Webhook 配置页面。
|
||||
|
||||
- Gitea (也可以是 GET 请求)
|
||||
Webhook 配置支持四种作用域：
|
||||
|
||||
- `仓库 Webhook`：仅对单个仓库中的活动触发。
|
||||
- `组织 Webhook`：对该组织拥有的仓库中的活动触发。
|
||||
- `用户 Webhook`：对该用户拥有的仓库中的活动触发。
|
||||
- `系统 Webhook`：对实例中的所有符合条件的活动触发。
|
||||
|
||||
Gitea 还支持由管理员定义的 `默认 Webhook`。它并不是额外的投递作用域，
|
||||
而是会在新仓库创建时被复制到仓库中，之后按普通仓库 Webhook 的方式工作。
|
||||
|
||||
Gitea 支持以下出站 Webhook 集成：
|
||||
|
||||
- Gitea
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk（钉钉）
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork（企业微信）
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### 事件信息
|
||||
`Gitea` 和 `Gogs` 类型会发送通用 Webhook 负载。上面列出的聊天和服务集成
|
||||
会将同一个内部事件转换为各自服务所需的请求体格式。
|
||||
|
||||
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
|
||||
本页分为三个部分：
|
||||
|
||||
以下是 Gitea 将发送给 payload URL 的事件信息示例：
|
||||
- `配置`：如何配置 Webhook 设置，例如 URL、密钥、分支过滤器和授权头。
|
||||
- `投递`：Gitea 如何发送 Webhook 请求、会携带哪些请求头，以及如何校验投递。
|
||||
- `事件`：Gitea 会投递哪些事件，以及每个事件包含哪些顶层 payload 参数。
|
||||
|
||||
## 配置
|
||||
|
||||
本节介绍在创建或编辑 Webhook 时可以设置的选项。
|
||||
|
||||
### 配置 Webhook
|
||||
|
||||
创建 Webhook 时，主要配置项包括：
|
||||
|
||||
- `Target URL`：接收投递的目标地址。
|
||||
- `HTTP Method`：通用 Webhook 通常使用 `POST`。
|
||||
- `POST Content Type`：通用 Webhook 可使用 `application/json` 或
|
||||
`application/x-www-form-urlencoded`。
|
||||
- `Secret`：用于对原始请求体进行 HMAC 签名。
|
||||
- `Authorization Header`：可选的自定义 `Authorization` 请求头，会随每次请求发送。
|
||||
- `Branch Filter`：可选的分支或标签过滤规则。
|
||||
- `Trigger On`：`Push Events`、`All Events` 或自定义事件选择。
|
||||
- `Active`：是否启用该 Webhook。
|
||||
|
||||
:::note
|
||||
旧示例里可能仍会在 JSON payload 中看到 `secret` 字段。当前版本的 Gitea
|
||||
不会再把 Webhook 密钥放进 payload 正文中。请始终通过签名请求头来验证请求。
|
||||
:::
|
||||
|
||||
### 分支过滤器
|
||||
|
||||
分支过滤器使用与
|
||||
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
|
||||
兼容的 glob 语法。
|
||||
|
||||
- 空值、`*` 或 `**` 表示匹配全部。
|
||||
- 像 `main` 这样的普通分支名会匹配该分支。
|
||||
- 也支持 `refs/tags/v*` 这样的完整 ref。
|
||||
- 支持 `{main,release/*}` 这样的花括号表达式。
|
||||
- 过滤器只对带 git ref 的事件生效，例如 `create`、`delete` 和 `push`。
|
||||
- 不带 ref 的事件，例如 issue 或 release，会忽略分支过滤器。
|
||||
|
||||
示例：
|
||||
|
||||
- `main`
|
||||
- `{main,feature/*}`
|
||||
- `{refs/heads/feature/*,refs/tags/release/*}`
|
||||
|
||||
### 授权头
|
||||
|
||||
Gitea 可以配置为在每次 Webhook 投递时发送自定义
|
||||
[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
它与 Webhook 密钥是相互独立的：
|
||||
|
||||
- 使用密钥通过 HMAC 校验请求完整性。
|
||||
- 当接收端需要应用层认证时，使用 `Authorization` 请求头。
|
||||
|
||||
## 投递
|
||||
|
||||
本节说明 Gitea 如何发送 Webhook 投递，以及接收端如何识别和验证这些请求。
|
||||
|
||||
### 投递行为
|
||||
|
||||
- Webhook 会通过 HTTP 异步投递。
|
||||
- 通用 `Gitea` 和 `Gogs` Webhook 支持 `POST` 与 `GET`；通常应使用 `POST`。
|
||||
- 对于 `POST` 请求，payload 可以直接作为 JSON
|
||||
（`application/json`）发送，也可以放在名为 `payload` 的表单字段中
|
||||
（`application/x-www-form-urlencoded`）。
|
||||
- 某些特定服务的集成可能会使用该服务要求的 HTTP 方法和请求体格式。
|
||||
|
||||
### 投递请求头
|
||||
|
||||
每次投递都包含唯一的 delivery ID 和事件请求头。对于兼容 GitHub 的集成，
|
||||
Gitea 也会同时发送对应的 GitHub 和 Gogs 风格请求头。
|
||||
|
||||
| 请求头 | 说明 |
|
||||
| --- | --- |
|
||||
| `X-Gitea-Delivery` | 本次投递尝试的唯一 UUID。 |
|
||||
| `X-Gitea-Event` | 规范化事件名，例如 `push`、`issues` 或 `pull_request`。 |
|
||||
| `X-Gitea-Event-Type` | 更具体的事件类型，例如 `issue_assign` 或 `pull_request_review_comment`。 |
|
||||
| `X-Gitea-Signature` | 原始请求体的十六进制 HMAC-SHA256 值，不带前缀。 |
|
||||
| `X-Gitea-Hook-Installation-Target-Type` | Webhook 定义所在范围，通常是 `repository`、`organization`、`user` 或 `system`。默认 Webhook 会先复制到仓库后再投递，因此通常会表现为 `repository`。 |
|
||||
| `X-Gogs-Delivery`、`X-Gogs-Event`、`X-Gogs-Event-Type`、`X-Gogs-Signature` | 与 Gitea 对应请求头值相同的兼容请求头。 |
|
||||
| `X-GitHub-Delivery`、`X-GitHub-Event`、`X-GitHub-Event-Type` | GitHub 风格兼容请求头。 |
|
||||
| `X-GitHub-Hook-Installation-Target-Type` | GitHub 风格的 Webhook 作用域请求头。 |
|
||||
| `X-Hub-Signature` | GitHub 兼容的 HMAC-SHA1 请求头，格式为 `sha1=<digest>`。 |
|
||||
| `X-Hub-Signature-256` | GitHub 兼容的 HMAC-SHA256 请求头，格式为 `sha256=<digest>`。 |
|
||||
|
||||
如果未配置密钥，签名请求头仍然会存在，但摘要值为空。
|
||||
|
||||
#### `Event` 与 `Event-Type`
|
||||
|
||||
某些 Gitea Webhook 订阅会被归类到同一个规范化事件名下。例如，issue 指派
|
||||
投递会归类到 issue 事件组：
|
||||
|
||||
```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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你需要知道真正触发投递的具体事件类型，请使用 `X-Gitea-Event-Type`。
|
||||
|
||||
### 示例
|
||||
#### 校验投递
|
||||
|
||||
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
|
||||
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
|
||||
Gitea 会使用你的 Webhook 密钥对原始请求体进行签名。要校验一次投递：
|
||||
|
||||
- 目标 URL：http://mydomain.com/webhook.php
|
||||
- HTTP 方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 触发条件：推送事件
|
||||
- 激活：勾选
|
||||
1. 按接收到的原始内容读取请求体。
|
||||
2. 使用 Webhook 密钥计算 HMAC-SHA256 摘要。
|
||||
3. 将结果与 `X-Gitea-Signature` 或 GitHub 兼容的
|
||||
`X-Hub-Signature-256` 进行比较。
|
||||
4. 尽量使用常量时间比较函数。
|
||||
|
||||
现在在你的服务器上创建 php 文件 webhook.php。
|
||||
注意事项：
|
||||
|
||||
- `X-Gitea-Signature` 仅包含小写十六进制的 SHA-256 摘要。
|
||||
- `X-Hub-Signature-256` 使用相同摘要，但带有 `sha256=` 前缀。
|
||||
- `X-Hub-Signature` 也会出于兼容性目的发送，其算法是 SHA-1。
|
||||
- 在完成签名校验之前，不应先解析 JSON 或修改请求体。
|
||||
|
||||
##### PHP 示例
|
||||
|
||||
下面的示例演示如何校验以 `application/json` 发送的通用 `Gitea` Webhook。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$secret_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
|
||||
## 事件
|
||||
|
||||
### 授权头（Authorization header）
|
||||
本节采用与 GitHub Webhook 文档类似的按事件逐项描述方式：每个事件都会说明
|
||||
其触发时机，以及 payload 中包含哪些顶层字段。
|
||||
|
||||
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
事件分组与 Webhook 设置界面中的分组一致：`Repository Events`、
|
||||
`Issue Events`、`Pull Request Events` 和 `Workflow Events`。
|
||||
|
||||
### 仓库事件
|
||||
|
||||
- `create`、`delete`、`fork`、`push`、`wiki`、`repository`、`release`、`package`、`status`
|
||||
|
||||
#### `create`
|
||||
|
||||
当分支或标签被创建时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `sha` | `string` | **必填。** 新建引用对应的对象 ID。 |
|
||||
| `ref` | `string` | **必填。** 被创建的分支名或标签名。 |
|
||||
| `ref_type` | `string` | **必填。** 引用类型，例如 `branch` 或 `tag`。 |
|
||||
| `repository` | `object` | **必填。** 创建该引用的仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建该引用的用户。 |
|
||||
|
||||
#### `delete`
|
||||
|
||||
当分支或标签被删除时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被删除的分支名或标签名。 |
|
||||
| `ref_type` | `string` | **必填。** 引用类型，例如 `branch` 或 `tag`。 |
|
||||
| `pusher_type` | `string` | **必填。** 删除该 ref 的行为主体类型。当前 Gitea payload 中使用 `user`。 |
|
||||
| `repository` | `object` | **必填。** 删除该引用所在的仓库。 |
|
||||
| `sender` | `object` | **必填。** 删除该引用的用户。 |
|
||||
|
||||
#### `fork`
|
||||
|
||||
当仓库被 fork 时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `forkee` | `object` | **必填。** 新创建的 fork 仓库。 |
|
||||
| `repository` | `object` | **必填。** 被 fork 的原始仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建 fork 的用户。 |
|
||||
|
||||
#### `push`
|
||||
|
||||
当提交被推送到某个分支或标签时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被推送的完整 ref，例如 `refs/heads/main`。 |
|
||||
| `before` | `string` | **必填。** 推送前的提交 SHA。 |
|
||||
| `after` | `string` | **必填。** 推送后的提交 SHA。 |
|
||||
| `compare_url` | `string` | **必填。** 用于比较 `before` 和 `after` 的 URL。 |
|
||||
| `commits` | `array` | **必填。** 本次推送包含的提交列表。 |
|
||||
| `total_commits` | `integer` | **必填。** 本次推送中的提交数量。 |
|
||||
| `head_commit` | `object` | 本次推送中的最新提交。 |
|
||||
| `repository` | `object` | **必填。** 接收此次推送的仓库。 |
|
||||
| `pusher` | `object` | **必填。** 执行推送的用户。 |
|
||||
| `sender` | `object` | **必填。** 触发 Webhook 的用户。 |
|
||||
|
||||
#### `wiki`
|
||||
|
||||
当 Wiki 页面被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Wiki 页面操作类型。 |
|
||||
| `repository` | `object` | **必填。** 拥有该 Wiki 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 修改 Wiki 页面的用户。 |
|
||||
| `page` | `string` | **必填。** Wiki 页面名称。 |
|
||||
| `comment` | `string` | Wiki 提交信息或备注。 |
|
||||
|
||||
#### `repository`
|
||||
|
||||
当仓库被创建或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 仓库操作类型。 |
|
||||
| `repository` | `object` | **必填。** 被创建或删除的仓库。 |
|
||||
| `organization` | `object` | 当仓库属于某个组织时会出现。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `release`
|
||||
|
||||
当发布版本被发布、更新或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `published`、`updated`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Release 操作类型。 |
|
||||
| `release` | `object` | **必填。** 被操作的发布版本。 |
|
||||
| `repository` | `object` | **必填。** 包含该发布版本的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `package`
|
||||
|
||||
当包被创建或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 包操作类型。 |
|
||||
| `repository` | `object` | 与该包关联的仓库；如果适用则会出现。 |
|
||||
| `package` | `object` | **必填。** 被操作的包。 |
|
||||
| `organization` | `object` | 当包所有者是组织时会出现。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
|
||||
#### `status`
|
||||
|
||||
当通过 API 创建或更新提交状态时，会触发此事件。
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `commit` | `object` | 与该状态关联的提交。 |
|
||||
| `context` | `string` | **必填。** 状态上下文，例如 `ci/build`。 |
|
||||
| `created_at` | `string` | **必填。** 状态创建时间。 |
|
||||
| `description` | `string` | 状态描述文本。 |
|
||||
| `id` | `integer` | **必填。** 状态标识符。 |
|
||||
| `repository` | `object` | **必填。** 包含该提交的仓库。 |
|
||||
| `sender` | `object` | **必填。** 创建该状态的用户。 |
|
||||
| `sha` | `string` | **必填。** 提交 SHA。 |
|
||||
| `state` | `string` | **必填。** 状态值，例如 `pending`、`success`、`error` 或 `failure`。 |
|
||||
| `target_url` | `string` | 与该状态关联的目标 URL。 |
|
||||
| `updated_at` | `string` | 状态最后更新时间。 |
|
||||
|
||||
与多数其他 payload 不同，此事件不使用 `action` 字段，状态变化通过 `state`
|
||||
字段表示。
|
||||
|
||||
### 议题事件
|
||||
|
||||
- `issues`、`issue_assign`、`issue_label`、`issue_milestone`、`issue_comment`
|
||||
|
||||
#### `issues`
|
||||
|
||||
当 issue 被打开、关闭、重新打开、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Issue 操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_assign`
|
||||
|
||||
当 issue 被指派或取消指派时，会触发此事件。
|
||||
|
||||
**动作类型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_label`
|
||||
|
||||
当 issue 标签被更新或清空时，会触发此事件。
|
||||
|
||||
**动作类型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 标签更新操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_milestone`
|
||||
|
||||
当 issue 被设置里程碑或移除里程碑时，会触发此事件。
|
||||
|
||||
**动作类型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作类型。 |
|
||||
| `number` | `integer` | **必填。** Issue 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 issue 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
|
||||
#### `issue_comment`
|
||||
|
||||
当 issue 评论被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评论操作类型。 |
|
||||
| `issue` | `object` | **必填。** 该评论所属的 issue。 |
|
||||
| `pull_request` | `object` | 当该评论位于 pull request 时间线上时会出现。 |
|
||||
| `comment` | `object` | **必填。** 被创建、编辑或删除的评论。 |
|
||||
| `changes` | `object` | 可选。当操作类型为 `edited` 时，表示评论正文的旧值。 |
|
||||
| `repository` | `object` | **必填。** 包含该 issue 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `is_pull` | `boolean` | **必填。** 该评论是否位于 pull request 时间线上。 |
|
||||
|
||||
### Pull Request 事件
|
||||
|
||||
- `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`
|
||||
|
||||
当 pull request 被打开、关闭、重新打开、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Pull request 操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_assign`
|
||||
|
||||
当 pull request 被指派或取消指派时，会触发此事件。
|
||||
|
||||
**动作类型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_label`
|
||||
|
||||
当 pull request 标签被更新或清空时，会触发此事件。
|
||||
|
||||
**动作类型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 标签更新操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_milestone`
|
||||
|
||||
当 pull request 被设置里程碑或移除里程碑时，会触发此事件。
|
||||
|
||||
**动作类型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_comment`
|
||||
|
||||
当 pull request 时间线评论被创建、编辑或删除时，会触发此事件。
|
||||
|
||||
**动作类型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评论操作类型。 |
|
||||
| `issue` | `object` | **必填。** 与该 pull request 关联的 issue 记录。 |
|
||||
| `pull_request` | `object` | **必填。** 评论所属的 pull request。 |
|
||||
| `comment` | `object` | **必填。** 被创建、编辑或删除的评论。 |
|
||||
| `changes` | `object` | 可选。当操作类型为 `edited` 时，表示评论正文的旧值。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `is_pull` | `boolean` | **必填。** 对此事件来说始终为 `true`。 |
|
||||
|
||||
#### `pull_request_review`
|
||||
|
||||
这是 Webhook 设置界面中的一个仅用于订阅的汇总事件。
|
||||
|
||||
它不会生成独立的投递 payload。勾选后，Gitea 实际投递的是更具体的
|
||||
`pull_request_review_approved`、`pull_request_review_rejected` 和
|
||||
`pull_request_review_comment` 事件。
|
||||
|
||||
#### `pull_request_review_approved`
|
||||
|
||||
当 pull request review 以批准形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `approved`。 |
|
||||
|
||||
#### `pull_request_review_rejected`
|
||||
|
||||
当 pull request review 以拒绝或请求修改的形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `rejected`。 |
|
||||
|
||||
#### `pull_request_review_comment`
|
||||
|
||||
当 pull request review 以评论形式提交时，会触发此事件。
|
||||
|
||||
**动作类型：** `reviewed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被评审的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 提交该评审的用户。 |
|
||||
| `commit_id` | `string` | 与该评审事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | **必填。** 评审负载。对此事件，`review.type` 为 `comment`。 |
|
||||
|
||||
#### `pull_request_sync`
|
||||
|
||||
当新的提交被推送后，pull request 被同步时，会触发此事件。
|
||||
|
||||
**动作类型：** `synchronized`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 始终为 `synchronized`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被同步的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在评审请求事件中会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行同步操作的用户。 |
|
||||
| `commit_id` | `string` | 与该同步事件关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
#### `pull_request_review_request`
|
||||
|
||||
当请求审查者或移除审查请求时，会触发此事件。
|
||||
|
||||
**动作类型：** `review_requested`、`review_request_removed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 评审请求操作类型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 编号。 |
|
||||
| `changes` | `object` | 可选。编辑字段之前的值，或标签变化明细。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 被请求或被移除的评审者。 |
|
||||
| `repository` | `object` | **必填。** 包含该 pull request 的仓库。 |
|
||||
| `sender` | `object` | **必填。** 执行该操作的用户。 |
|
||||
| `commit_id` | `string` | 与该 pull request 操作关联的提交 SHA；如果适用则会出现。 |
|
||||
| `review` | `object` | 在 pull request review 事件中会出现。 |
|
||||
|
||||
### 工作流事件
|
||||
|
||||
- `workflow_run`、`workflow_job`
|
||||
|
||||
#### `workflow_run`
|
||||
|
||||
当 Gitea Actions 工作流运行状态发生变化时，会触发此事件。
|
||||
|
||||
**动作类型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流运行状态变化。 |
|
||||
| `workflow` | `object` | **必填。** 工作流定义。 |
|
||||
| `workflow_run` | `object` | **必填。** 被操作的工作流运行记录。 |
|
||||
| `pull_request` | `object` | 当该工作流运行与某个 pull request 相关时会出现。 |
|
||||
| `organization` | `object` | 当仓库所有者是组织时会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该工作流的仓库。 |
|
||||
| `sender` | `object` | **必填。** 触发该工作流运行更新的用户。 |
|
||||
|
||||
#### `workflow_job`
|
||||
|
||||
当 Gitea Actions 工作流任务状态发生变化时，会触发此事件。
|
||||
|
||||
**动作类型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 参数
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流任务状态变化。 |
|
||||
| `workflow_job` | `object` | **必填。** 被操作的工作流任务。 |
|
||||
| `pull_request` | `object` | 当该工作流任务与某个 pull request 相关时会出现。 |
|
||||
| `organization` | `object` | 当仓库所有者是组织时会出现。 |
|
||||
| `repository` | `object` | **必填。** 包含该工作流任务的仓库。 |
|
||||
| `sender` | `object` | **必填。** 触发该工作流任务更新的用户。 |
|
||||
|
||||
## 测试、最近投递与重放
|
||||
|
||||
每个 Webhook 页面都包含：
|
||||
|
||||
- `Test Delivery`：会向仓库发送一次模拟的 `push` 事件。
|
||||
- `Recent Deliveries`：显示请求和响应详情。
|
||||
- `Redelivery`：重新投递一次历史 Webhook 记录。
|
||||
|
||||
如果仓库还没有任何提交，测试投递会使用一个生成的假提交，以便仍然可以测试
|
||||
Webhook。
|
||||
|
||||
## 管理说明
|
||||
|
||||
管理员还可以通过实例级设置控制 Webhook 投递，例如主机允许列表、投递超时和
|
||||
清理策略。详见
|
||||
[配置速查表中的 Webhook 小节](../../administration/config-cheat-sheet.md#webhook-webhook)。
|
||||
|
||||
@@ -8,178 +8,713 @@ aliases:
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
|
||||
所有事件推送都是 POST 请求。目前支持：
|
||||
Gitea 可以為儲存庫活動送出對外 Webhook。儲存庫層級的 Webhook 由儲存庫管理員
|
||||
在 `/:username/:reponame/settings/hooks` 中設定。組織、使用者與系統管理層級
|
||||
也有對應的 Webhook 設定頁面。
|
||||
|
||||
- Gitea (也可以是 GET 请求)
|
||||
Webhook 設定支援四種範圍：
|
||||
|
||||
- `儲存庫 Webhook`：只會對單一儲存庫中的活動觸發。
|
||||
- `組織 Webhook`：對該組織擁有的儲存庫中的活動觸發。
|
||||
- `使用者 Webhook`：對該使用者擁有的儲存庫中的活動觸發。
|
||||
- `系統 Webhook`：對實例中所有符合條件的活動觸發。
|
||||
|
||||
Gitea 也支援由管理員定義的 `預設 Webhook`。它並不是額外的投遞範圍，而是會在
|
||||
建立新儲存庫時被複製到該儲存庫中，之後就會像一般儲存庫 Webhook 一樣運作。
|
||||
|
||||
Gitea 支援以下對外 Webhook 整合：
|
||||
|
||||
- Gitea
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk（钉钉）
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork（企业微信）
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### 事件信息
|
||||
`Gitea` 與 `Gogs` 類型會送出通用 Webhook payload。上面列出的聊天與服務整合
|
||||
則會把同一個內部事件轉換成各自服務所需的請求主體格式。
|
||||
|
||||
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
|
||||
本頁分成三個部分：
|
||||
|
||||
以下是 Gitea 将发送给 payload URL 的事件信息示例：
|
||||
- `設定`：如何設定 Webhook 選項，例如 URL、密鑰、分支過濾器與授權標頭。
|
||||
- `投遞`：Gitea 如何送出 Webhook 請求、會附帶哪些標頭，以及如何驗證投遞。
|
||||
- `事件`：Gitea 會投遞哪些事件，以及每個事件包含哪些頂層 payload 參數。
|
||||
|
||||
## 設定
|
||||
|
||||
本節介紹在建立或編輯 Webhook 時可以設定的選項。
|
||||
|
||||
### 設定 Webhook
|
||||
|
||||
建立 Webhook 時，主要設定項目包括：
|
||||
|
||||
- `Target URL`：接收投遞的目標位址。
|
||||
- `HTTP Method`：通用 Webhook 通常使用 `POST`。
|
||||
- `POST Content Type`：通用 Webhook 可使用 `application/json` 或
|
||||
`application/x-www-form-urlencoded`。
|
||||
- `Secret`：用來對原始請求主體進行 HMAC 簽章。
|
||||
- `Authorization Header`：可選的自訂 `Authorization` 標頭，會隨每次請求送出。
|
||||
- `Branch Filter`：可選的分支或標籤過濾規則。
|
||||
- `Trigger On`：`Push Events`、`All Events` 或自訂事件選擇。
|
||||
- `Active`：是否啟用該 Webhook。
|
||||
|
||||
:::note
|
||||
舊版範例中可能仍會在 JSON payload 裡看到 `secret` 欄位。當前版本的 Gitea
|
||||
不會再把 Webhook 密鑰放進 payload 內容中。請務必透過簽章標頭驗證請求。
|
||||
:::
|
||||
|
||||
### 分支過濾器
|
||||
|
||||
分支過濾器使用與
|
||||
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
|
||||
相容的 glob 語法。
|
||||
|
||||
- 空值、`*` 或 `**` 代表符合全部。
|
||||
- 像 `main` 這樣的一般分支名稱會符合該分支。
|
||||
- 也支援 `refs/tags/v*` 這類完整 ref。
|
||||
- 支援 `{main,release/*}` 這類大括號表達式。
|
||||
- 過濾器只會套用在帶有 git ref 的事件，例如 `create`、`delete` 與 `push`。
|
||||
- 不帶 ref 的事件，例如 issue 或 release，會忽略分支過濾器。
|
||||
|
||||
範例：
|
||||
|
||||
- `main`
|
||||
- `{main,feature/*}`
|
||||
- `{refs/heads/feature/*,refs/tags/release/*}`
|
||||
|
||||
### 授權標頭
|
||||
|
||||
Gitea 可以設定為在每次 Webhook 投遞時送出自訂的
|
||||
[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
它與 Webhook 密鑰彼此獨立：
|
||||
|
||||
- 使用密鑰透過 HMAC 驗證請求完整性。
|
||||
- 當接收端需要應用層認證時，使用 `Authorization` 標頭。
|
||||
|
||||
## 投遞
|
||||
|
||||
本節說明 Gitea 如何送出 Webhook 投遞，以及接收端如何識別與驗證這些請求。
|
||||
|
||||
### 投遞行為
|
||||
|
||||
- Webhook 會透過 HTTP 非同步投遞。
|
||||
- 通用 `Gitea` 與 `Gogs` Webhook 支援 `POST` 與 `GET`；通常應使用 `POST`。
|
||||
- 對於 `POST` 請求，payload 可以直接以 JSON
|
||||
（`application/json`）送出，也可以放在名為 `payload` 的表單欄位中
|
||||
（`application/x-www-form-urlencoded`）。
|
||||
- 某些特定服務整合可能會使用該服務要求的 HTTP 方法與請求主體格式。
|
||||
|
||||
### 投遞標頭
|
||||
|
||||
每次投遞都包含唯一的 delivery ID 與事件標頭。對於相容 GitHub 的整合，
|
||||
Gitea 也會同時送出對應的 GitHub 與 Gogs 風格標頭。
|
||||
|
||||
| 標頭 | 說明 |
|
||||
| --- | --- |
|
||||
| `X-Gitea-Delivery` | 本次投遞嘗試的唯一 UUID。 |
|
||||
| `X-Gitea-Event` | 規範化事件名稱，例如 `push`、`issues` 或 `pull_request`。 |
|
||||
| `X-Gitea-Event-Type` | 更具體的事件類型，例如 `issue_assign` 或 `pull_request_review_comment`。 |
|
||||
| `X-Gitea-Signature` | 原始請求主體的十六進位 HMAC-SHA256 值，不含前綴。 |
|
||||
| `X-Gitea-Hook-Installation-Target-Type` | Webhook 定義所在範圍，通常是 `repository`、`organization`、`user` 或 `system`。預設 Webhook 會先複製到儲存庫後再投遞，因此通常會呈現為 `repository`。 |
|
||||
| `X-Gogs-Delivery`、`X-Gogs-Event`、`X-Gogs-Event-Type`、`X-Gogs-Signature` | 與 Gitea 對應標頭值相同的相容性標頭。 |
|
||||
| `X-GitHub-Delivery`、`X-GitHub-Event`、`X-GitHub-Event-Type` | GitHub 風格相容性標頭。 |
|
||||
| `X-GitHub-Hook-Installation-Target-Type` | GitHub 風格的 Webhook 範圍標頭。 |
|
||||
| `X-Hub-Signature` | GitHub 相容的 HMAC-SHA1 標頭，格式為 `sha1=<digest>`。 |
|
||||
| `X-Hub-Signature-256` | GitHub 相容的 HMAC-SHA256 標頭，格式為 `sha256=<digest>`。 |
|
||||
|
||||
如果未設定密鑰，簽章標頭仍然會存在，但摘要值為空。
|
||||
|
||||
#### `Event` 與 `Event-Type`
|
||||
|
||||
某些 Gitea Webhook 訂閱會被歸類到同一個規範化事件名稱下。例如，issue 指派
|
||||
投遞會歸類到 issue 事件群組：
|
||||
|
||||
```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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你需要知道實際觸發投遞的具體事件類型，請使用 `X-Gitea-Event-Type`。
|
||||
|
||||
### 示例
|
||||
#### 驗證投遞
|
||||
|
||||
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
|
||||
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
|
||||
Gitea 會使用你的 Webhook 密鑰對原始請求主體進行簽章。要驗證一次投遞：
|
||||
|
||||
- 目标 URL：http://mydomain.com/webhook.php
|
||||
- HTTP 方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 触发条件：推送事件
|
||||
- 激活：勾选
|
||||
1. 以接收到的原始內容讀取請求主體。
|
||||
2. 使用 Webhook 密鑰計算 HMAC-SHA256 摘要。
|
||||
3. 將結果與 `X-Gitea-Signature` 或 GitHub 相容的
|
||||
`X-Hub-Signature-256` 進行比較。
|
||||
4. 盡量使用常數時間比較函式。
|
||||
|
||||
现在在你的服务器上创建 php 文件 webhook.php。
|
||||
注意事項：
|
||||
|
||||
- `X-Gitea-Signature` 只包含小寫十六進位的 SHA-256 摘要。
|
||||
- `X-Hub-Signature-256` 使用相同摘要，但帶有 `sha256=` 前綴。
|
||||
- `X-Hub-Signature` 也會為了相容性而送出，其演算法為 SHA-1。
|
||||
- 在完成簽章驗證之前，不應先解析 JSON 或修改請求主體。
|
||||
|
||||
##### PHP 範例
|
||||
|
||||
下面的範例示範如何驗證以 `application/json` 送出的通用 `Gitea` Webhook。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$secret_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
|
||||
## 事件
|
||||
|
||||
### 授权头（Authorization header）
|
||||
本節採用與 GitHub Webhook 文件類似的逐事件描述方式：每個事件都會說明
|
||||
觸發時機，以及 payload 中包含哪些頂層欄位。
|
||||
|
||||
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
事件分組與 Webhook 設定介面中的分組一致：`Repository Events`、
|
||||
`Issue Events`、`Pull Request Events` 與 `Workflow Events`。
|
||||
|
||||
### 儲存庫事件
|
||||
|
||||
- `create`、`delete`、`fork`、`push`、`wiki`、`repository`、`release`、`package`、`status`
|
||||
|
||||
#### `create`
|
||||
|
||||
當分支或標籤被建立時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `sha` | `string` | **必填。** 新建引用對應的物件 ID。 |
|
||||
| `ref` | `string` | **必填。** 被建立的分支名稱或標籤名稱。 |
|
||||
| `ref_type` | `string` | **必填。** 引用類型，例如 `branch` 或 `tag`。 |
|
||||
| `repository` | `object` | **必填。** 建立該引用的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立該引用的使用者。 |
|
||||
|
||||
#### `delete`
|
||||
|
||||
當分支或標籤被刪除時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被刪除的分支名稱或標籤名稱。 |
|
||||
| `ref_type` | `string` | **必填。** 引用類型，例如 `branch` 或 `tag`。 |
|
||||
| `pusher_type` | `string` | **必填。** 刪除該 ref 的行為主體類型。目前 Gitea payload 使用 `user`。 |
|
||||
| `repository` | `object` | **必填。** 刪除該引用所在的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 刪除該引用的使用者。 |
|
||||
|
||||
#### `fork`
|
||||
|
||||
當儲存庫被 fork 時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `forkee` | `object` | **必填。** 新建立的 fork 儲存庫。 |
|
||||
| `repository` | `object` | **必填。** 被 fork 的原始儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立 fork 的使用者。 |
|
||||
|
||||
#### `push`
|
||||
|
||||
當提交被推送到某個分支或標籤時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被推送的完整 ref，例如 `refs/heads/main`。 |
|
||||
| `before` | `string` | **必填。** 推送前的提交 SHA。 |
|
||||
| `after` | `string` | **必填。** 推送後的提交 SHA。 |
|
||||
| `compare_url` | `string` | **必填。** 用於比較 `before` 與 `after` 的 URL。 |
|
||||
| `commits` | `array` | **必填。** 本次推送包含的提交清單。 |
|
||||
| `total_commits` | `integer` | **必填。** 本次推送中的提交數量。 |
|
||||
| `head_commit` | `object` | 本次推送中的最新提交。 |
|
||||
| `repository` | `object` | **必填。** 接收此次推送的儲存庫。 |
|
||||
| `pusher` | `object` | **必填。** 執行推送的使用者。 |
|
||||
| `sender` | `object` | **必填。** 觸發 Webhook 的使用者。 |
|
||||
|
||||
#### `wiki`
|
||||
|
||||
當 Wiki 頁面被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Wiki 頁面操作類型。 |
|
||||
| `repository` | `object` | **必填。** 擁有該 Wiki 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 修改 Wiki 頁面的使用者。 |
|
||||
| `page` | `string` | **必填。** Wiki 頁面名稱。 |
|
||||
| `comment` | `string` | Wiki 提交訊息或註解。 |
|
||||
|
||||
#### `repository`
|
||||
|
||||
當儲存庫被建立或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 儲存庫操作類型。 |
|
||||
| `repository` | `object` | **必填。** 被建立或刪除的儲存庫。 |
|
||||
| `organization` | `object` | 當儲存庫屬於某個組織時會出現。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `release`
|
||||
|
||||
當發行版本被發佈、更新或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `published`、`updated`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Release 操作類型。 |
|
||||
| `release` | `object` | **必填。** 被操作的發行版本。 |
|
||||
| `repository` | `object` | **必填。** 包含該發行版本的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `package`
|
||||
|
||||
當套件被建立或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 套件操作類型。 |
|
||||
| `repository` | `object` | 與該套件關聯的儲存庫；如果適用則會出現。 |
|
||||
| `package` | `object` | **必填。** 被操作的套件。 |
|
||||
| `organization` | `object` | 當套件擁有者是組織時會出現。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `status`
|
||||
|
||||
當透過 API 建立或更新提交狀態時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `commit` | `object` | 與該狀態關聯的提交。 |
|
||||
| `context` | `string` | **必填。** 狀態內容，例如 `ci/build`。 |
|
||||
| `created_at` | `string` | **必填。** 狀態建立時間。 |
|
||||
| `description` | `string` | 狀態描述文字。 |
|
||||
| `id` | `integer` | **必填。** 狀態識別碼。 |
|
||||
| `repository` | `object` | **必填。** 包含該提交的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立該狀態的使用者。 |
|
||||
| `sha` | `string` | **必填。** 提交 SHA。 |
|
||||
| `state` | `string` | **必填。** 狀態值，例如 `pending`、`success`、`error` 或 `failure`。 |
|
||||
| `target_url` | `string` | 與該狀態關聯的目標 URL。 |
|
||||
| `updated_at` | `string` | 狀態最後更新時間。 |
|
||||
|
||||
與多數其他 payload 不同，此事件不使用 `action` 欄位，狀態變化透過 `state`
|
||||
欄位表示。
|
||||
|
||||
### 議題事件
|
||||
|
||||
- `issues`、`issue_assign`、`issue_label`、`issue_milestone`、`issue_comment`
|
||||
|
||||
#### `issues`
|
||||
|
||||
當 issue 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Issue 操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_assign`
|
||||
|
||||
當 issue 被指派或取消指派時，會觸發此事件。
|
||||
|
||||
**動作類型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_label`
|
||||
|
||||
當 issue 標籤被更新或清空時，會觸發此事件。
|
||||
|
||||
**動作類型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 標籤更新操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_milestone`
|
||||
|
||||
當 issue 被設定里程碑或移除里程碑時，會觸發此事件。
|
||||
|
||||
**動作類型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_comment`
|
||||
|
||||
當 issue 評論被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 評論操作類型。 |
|
||||
| `issue` | `object` | **必填。** 該評論所屬的 issue。 |
|
||||
| `pull_request` | `object` | 當該評論位於 pull request 時間線上時會出現。 |
|
||||
| `comment` | `object` | **必填。** 被建立、編輯或刪除的評論。 |
|
||||
| `changes` | `object` | 可選。當操作類型為 `edited` 時，表示評論內容的舊值。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `is_pull` | `boolean` | **必填。** 該評論是否位於 pull request 時間線上。 |
|
||||
|
||||
### Pull Request 事件
|
||||
|
||||
- `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`
|
||||
|
||||
當 pull request 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Pull request 操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_assign`
|
||||
|
||||
當 pull request 被指派或取消指派時，會觸發此事件。
|
||||
|
||||
**動作類型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_label`
|
||||
|
||||
當 pull request 標籤被更新或清空時，會觸發此事件。
|
||||
|
||||
**動作類型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 標籤更新操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_milestone`
|
||||
|
||||
當 pull request 被設定里程碑或移除里程碑時，會觸發此事件。
|
||||
|
||||
**動作類型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_comment`
|
||||
|
||||
當 pull request 時間線評論被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 評論操作類型。 |
|
||||
| `issue` | `object` | **必填。** 與該 pull request 關聯的 issue 記錄。 |
|
||||
| `pull_request` | `object` | **必填。** 評論所屬的 pull request。 |
|
||||
| `comment` | `object` | **必填。** 被建立、編輯或刪除的評論。 |
|
||||
| `changes` | `object` | 可選。當操作類型為 `edited` 時，表示評論內容的舊值。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `is_pull` | `boolean` | **必填。** 對此事件而言固定為 `true`。 |
|
||||
|
||||
#### `pull_request_review`
|
||||
|
||||
這是 Webhook 設定介面中的一個僅用於訂閱的彙總事件。
|
||||
|
||||
它不會產生獨立的投遞 payload。勾選後，Gitea 實際投遞的是更具體的
|
||||
`pull_request_review_approved`、`pull_request_review_rejected` 與
|
||||
`pull_request_review_comment` 事件。
|
||||
|
||||
#### `pull_request_review_approved`
|
||||
|
||||
當 pull request review 以核准形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `approved`。 |
|
||||
|
||||
#### `pull_request_review_rejected`
|
||||
|
||||
當 pull request review 以拒絕或請求修改的形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `rejected`。 |
|
||||
|
||||
#### `pull_request_review_comment`
|
||||
|
||||
當 pull request review 以評論形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `comment`。 |
|
||||
|
||||
#### `pull_request_sync`
|
||||
|
||||
當新的提交被推送後，pull request 被同步時，會觸發此事件。
|
||||
|
||||
**動作類型：** `synchronized`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `synchronized`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被同步的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行同步操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該同步事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_review_request`
|
||||
|
||||
當請求審查者或移除審查請求時，會觸發此事件。
|
||||
|
||||
**動作類型：** `review_requested`、`review_request_removed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 審查請求操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 被請求或被移除的審查者。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
### 工作流程事件
|
||||
|
||||
- `workflow_run`、`workflow_job`
|
||||
|
||||
#### `workflow_run`
|
||||
|
||||
當 Gitea Actions 工作流程執行狀態發生變化時，會觸發此事件。
|
||||
|
||||
**動作類型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流程執行狀態變化。 |
|
||||
| `workflow` | `object` | **必填。** 工作流程定義。 |
|
||||
| `workflow_run` | `object` | **必填。** 被操作的工作流程執行記錄。 |
|
||||
| `pull_request` | `object` | 當該工作流程執行與某個 pull request 相關時會出現。 |
|
||||
| `organization` | `object` | 當儲存庫擁有者是組織時會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該工作流程的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 觸發該工作流程執行更新的使用者。 |
|
||||
|
||||
#### `workflow_job`
|
||||
|
||||
當 Gitea Actions 工作流程作業狀態發生變化時，會觸發此事件。
|
||||
|
||||
**動作類型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流程作業狀態變化。 |
|
||||
| `workflow_job` | `object` | **必填。** 被操作的工作流程作業。 |
|
||||
| `pull_request` | `object` | 當該工作流程作業與某個 pull request 相關時會出現。 |
|
||||
| `organization` | `object` | 當儲存庫擁有者是組織時會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該工作流程作業的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 觸發該工作流程作業更新的使用者。 |
|
||||
|
||||
## 測試、最近投遞與重新投遞
|
||||
|
||||
每個 Webhook 頁面都包含：
|
||||
|
||||
- `Test Delivery`：會向儲存庫送出一次模擬的 `push` 事件。
|
||||
- `Recent Deliveries`：顯示請求與回應詳細資訊。
|
||||
- `Redelivery`：重新投遞一筆歷史 Webhook 記錄。
|
||||
|
||||
如果儲存庫還沒有任何提交，測試投遞會使用一個產生的假提交，以便仍能測試
|
||||
Webhook。
|
||||
|
||||
## 管理說明
|
||||
|
||||
管理員還可以透過實例層級設定控制 Webhook 投遞，例如主機允許清單、投遞逾時
|
||||
與清理策略。詳見
|
||||
[設定速查表中的 Webhook 小節](../../administration/config-cheat-sheet.md#webhook-webhook)。
|
||||
|
||||
@@ -8,178 +8,713 @@ aliases:
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
|
||||
所有事件推送都是 POST 请求。目前支持：
|
||||
Gitea 可以為儲存庫活動送出對外 Webhook。儲存庫層級的 Webhook 由儲存庫管理員
|
||||
在 `/:username/:reponame/settings/hooks` 中設定。組織、使用者與系統管理層級
|
||||
也有對應的 Webhook 設定頁面。
|
||||
|
||||
- Gitea (也可以是 GET 请求)
|
||||
Webhook 設定支援四種範圍：
|
||||
|
||||
- `儲存庫 Webhook`：只會對單一儲存庫中的活動觸發。
|
||||
- `組織 Webhook`：對該組織擁有的儲存庫中的活動觸發。
|
||||
- `使用者 Webhook`：對該使用者擁有的儲存庫中的活動觸發。
|
||||
- `系統 Webhook`：對實例中所有符合條件的活動觸發。
|
||||
|
||||
Gitea 也支援由管理員定義的 `預設 Webhook`。它並不是額外的投遞範圍，而是會在
|
||||
建立新儲存庫時被複製到該儲存庫中，之後就會像一般儲存庫 Webhook 一樣運作。
|
||||
|
||||
Gitea 支援以下對外 Webhook 整合：
|
||||
|
||||
- Gitea
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk（钉钉）
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork（企业微信）
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### 事件信息
|
||||
`Gitea` 與 `Gogs` 類型會送出通用 Webhook payload。上面列出的聊天與服務整合
|
||||
則會把同一個內部事件轉換成各自服務所需的請求主體格式。
|
||||
|
||||
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
|
||||
本頁分成三個部分：
|
||||
|
||||
以下是 Gitea 将发送给 payload URL 的事件信息示例：
|
||||
- `設定`：如何設定 Webhook 選項，例如 URL、密鑰、分支過濾器與授權標頭。
|
||||
- `投遞`：Gitea 如何送出 Webhook 請求、會附帶哪些標頭，以及如何驗證投遞。
|
||||
- `事件`：Gitea 會投遞哪些事件，以及每個事件包含哪些頂層 payload 參數。
|
||||
|
||||
## 設定
|
||||
|
||||
本節介紹在建立或編輯 Webhook 時可以設定的選項。
|
||||
|
||||
### 設定 Webhook
|
||||
|
||||
建立 Webhook 時，主要設定項目包括：
|
||||
|
||||
- `Target URL`：接收投遞的目標位址。
|
||||
- `HTTP Method`：通用 Webhook 通常使用 `POST`。
|
||||
- `POST Content Type`：通用 Webhook 可使用 `application/json` 或
|
||||
`application/x-www-form-urlencoded`。
|
||||
- `Secret`：用來對原始請求主體進行 HMAC 簽章。
|
||||
- `Authorization Header`：可選的自訂 `Authorization` 標頭，會隨每次請求送出。
|
||||
- `Branch Filter`：可選的分支或標籤過濾規則。
|
||||
- `Trigger On`：`Push Events`、`All Events` 或自訂事件選擇。
|
||||
- `Active`：是否啟用該 Webhook。
|
||||
|
||||
:::note
|
||||
舊版範例中可能仍會在 JSON payload 裡看到 `secret` 欄位。當前版本的 Gitea
|
||||
不會再把 Webhook 密鑰放進 payload 內容中。請務必透過簽章標頭驗證請求。
|
||||
:::
|
||||
|
||||
### 分支過濾器
|
||||
|
||||
分支過濾器使用與
|
||||
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
|
||||
相容的 glob 語法。
|
||||
|
||||
- 空值、`*` 或 `**` 代表符合全部。
|
||||
- 像 `main` 這樣的一般分支名稱會符合該分支。
|
||||
- 也支援 `refs/tags/v*` 這類完整 ref。
|
||||
- 支援 `{main,release/*}` 這類大括號表達式。
|
||||
- 過濾器只會套用在帶有 git ref 的事件，例如 `create`、`delete` 與 `push`。
|
||||
- 不帶 ref 的事件，例如 issue 或 release，會忽略分支過濾器。
|
||||
|
||||
範例：
|
||||
|
||||
- `main`
|
||||
- `{main,feature/*}`
|
||||
- `{refs/heads/feature/*,refs/tags/release/*}`
|
||||
|
||||
### 授權標頭
|
||||
|
||||
Gitea 可以設定為在每次 Webhook 投遞時送出自訂的
|
||||
[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
它與 Webhook 密鑰彼此獨立：
|
||||
|
||||
- 使用密鑰透過 HMAC 驗證請求完整性。
|
||||
- 當接收端需要應用層認證時，使用 `Authorization` 標頭。
|
||||
|
||||
## 投遞
|
||||
|
||||
本節說明 Gitea 如何送出 Webhook 投遞，以及接收端如何識別與驗證這些請求。
|
||||
|
||||
### 投遞行為
|
||||
|
||||
- Webhook 會透過 HTTP 非同步投遞。
|
||||
- 通用 `Gitea` 與 `Gogs` Webhook 支援 `POST` 與 `GET`；通常應使用 `POST`。
|
||||
- 對於 `POST` 請求，payload 可以直接以 JSON
|
||||
（`application/json`）送出，也可以放在名為 `payload` 的表單欄位中
|
||||
（`application/x-www-form-urlencoded`）。
|
||||
- 某些特定服務整合可能會使用該服務要求的 HTTP 方法與請求主體格式。
|
||||
|
||||
### 投遞標頭
|
||||
|
||||
每次投遞都包含唯一的 delivery ID 與事件標頭。對於相容 GitHub 的整合，
|
||||
Gitea 也會同時送出對應的 GitHub 與 Gogs 風格標頭。
|
||||
|
||||
| 標頭 | 說明 |
|
||||
| --- | --- |
|
||||
| `X-Gitea-Delivery` | 本次投遞嘗試的唯一 UUID。 |
|
||||
| `X-Gitea-Event` | 規範化事件名稱，例如 `push`、`issues` 或 `pull_request`。 |
|
||||
| `X-Gitea-Event-Type` | 更具體的事件類型，例如 `issue_assign` 或 `pull_request_review_comment`。 |
|
||||
| `X-Gitea-Signature` | 原始請求主體的十六進位 HMAC-SHA256 值，不含前綴。 |
|
||||
| `X-Gitea-Hook-Installation-Target-Type` | Webhook 定義所在範圍，通常是 `repository`、`organization`、`user` 或 `system`。預設 Webhook 會先複製到儲存庫後再投遞，因此通常會呈現為 `repository`。 |
|
||||
| `X-Gogs-Delivery`、`X-Gogs-Event`、`X-Gogs-Event-Type`、`X-Gogs-Signature` | 與 Gitea 對應標頭值相同的相容性標頭。 |
|
||||
| `X-GitHub-Delivery`、`X-GitHub-Event`、`X-GitHub-Event-Type` | GitHub 風格相容性標頭。 |
|
||||
| `X-GitHub-Hook-Installation-Target-Type` | GitHub 風格的 Webhook 範圍標頭。 |
|
||||
| `X-Hub-Signature` | GitHub 相容的 HMAC-SHA1 標頭，格式為 `sha1=<digest>`。 |
|
||||
| `X-Hub-Signature-256` | GitHub 相容的 HMAC-SHA256 標頭，格式為 `sha256=<digest>`。 |
|
||||
|
||||
如果未設定密鑰，簽章標頭仍然會存在，但摘要值為空。
|
||||
|
||||
#### `Event` 與 `Event-Type`
|
||||
|
||||
某些 Gitea Webhook 訂閱會被歸類到同一個規範化事件名稱下。例如，issue 指派
|
||||
投遞會歸類到 issue 事件群組：
|
||||
|
||||
```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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你需要知道實際觸發投遞的具體事件類型，請使用 `X-Gitea-Event-Type`。
|
||||
|
||||
### 示例
|
||||
#### 驗證投遞
|
||||
|
||||
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
|
||||
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
|
||||
Gitea 會使用你的 Webhook 密鑰對原始請求主體進行簽章。要驗證一次投遞：
|
||||
|
||||
- 目标 URL：http://mydomain.com/webhook.php
|
||||
- HTTP 方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 触发条件：推送事件
|
||||
- 激活：勾选
|
||||
1. 以接收到的原始內容讀取請求主體。
|
||||
2. 使用 Webhook 密鑰計算 HMAC-SHA256 摘要。
|
||||
3. 將結果與 `X-Gitea-Signature` 或 GitHub 相容的
|
||||
`X-Hub-Signature-256` 進行比較。
|
||||
4. 盡量使用常數時間比較函式。
|
||||
|
||||
现在在你的服务器上创建 php 文件 webhook.php。
|
||||
注意事項：
|
||||
|
||||
- `X-Gitea-Signature` 只包含小寫十六進位的 SHA-256 摘要。
|
||||
- `X-Hub-Signature-256` 使用相同摘要，但帶有 `sha256=` 前綴。
|
||||
- `X-Hub-Signature` 也會為了相容性而送出，其演算法為 SHA-1。
|
||||
- 在完成簽章驗證之前，不應先解析 JSON 或修改請求主體。
|
||||
|
||||
##### PHP 範例
|
||||
|
||||
下面的範例示範如何驗證以 `application/json` 送出的通用 `Gitea` Webhook。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$secret_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
|
||||
## 事件
|
||||
|
||||
### 授权头（Authorization header）
|
||||
本節採用與 GitHub Webhook 文件類似的逐事件描述方式：每個事件都會說明
|
||||
觸發時機，以及 payload 中包含哪些頂層欄位。
|
||||
|
||||
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
事件分組與 Webhook 設定介面中的分組一致：`Repository Events`、
|
||||
`Issue Events`、`Pull Request Events` 與 `Workflow Events`。
|
||||
|
||||
### 儲存庫事件
|
||||
|
||||
- `create`、`delete`、`fork`、`push`、`wiki`、`repository`、`release`、`package`、`status`
|
||||
|
||||
#### `create`
|
||||
|
||||
當分支或標籤被建立時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `sha` | `string` | **必填。** 新建引用對應的物件 ID。 |
|
||||
| `ref` | `string` | **必填。** 被建立的分支名稱或標籤名稱。 |
|
||||
| `ref_type` | `string` | **必填。** 引用類型，例如 `branch` 或 `tag`。 |
|
||||
| `repository` | `object` | **必填。** 建立該引用的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立該引用的使用者。 |
|
||||
|
||||
#### `delete`
|
||||
|
||||
當分支或標籤被刪除時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被刪除的分支名稱或標籤名稱。 |
|
||||
| `ref_type` | `string` | **必填。** 引用類型，例如 `branch` 或 `tag`。 |
|
||||
| `pusher_type` | `string` | **必填。** 刪除該 ref 的行為主體類型。目前 Gitea payload 使用 `user`。 |
|
||||
| `repository` | `object` | **必填。** 刪除該引用所在的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 刪除該引用的使用者。 |
|
||||
|
||||
#### `fork`
|
||||
|
||||
當儲存庫被 fork 時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `forkee` | `object` | **必填。** 新建立的 fork 儲存庫。 |
|
||||
| `repository` | `object` | **必填。** 被 fork 的原始儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立 fork 的使用者。 |
|
||||
|
||||
#### `push`
|
||||
|
||||
當提交被推送到某個分支或標籤時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被推送的完整 ref，例如 `refs/heads/main`。 |
|
||||
| `before` | `string` | **必填。** 推送前的提交 SHA。 |
|
||||
| `after` | `string` | **必填。** 推送後的提交 SHA。 |
|
||||
| `compare_url` | `string` | **必填。** 用於比較 `before` 與 `after` 的 URL。 |
|
||||
| `commits` | `array` | **必填。** 本次推送包含的提交清單。 |
|
||||
| `total_commits` | `integer` | **必填。** 本次推送中的提交數量。 |
|
||||
| `head_commit` | `object` | 本次推送中的最新提交。 |
|
||||
| `repository` | `object` | **必填。** 接收此次推送的儲存庫。 |
|
||||
| `pusher` | `object` | **必填。** 執行推送的使用者。 |
|
||||
| `sender` | `object` | **必填。** 觸發 Webhook 的使用者。 |
|
||||
|
||||
#### `wiki`
|
||||
|
||||
當 Wiki 頁面被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Wiki 頁面操作類型。 |
|
||||
| `repository` | `object` | **必填。** 擁有該 Wiki 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 修改 Wiki 頁面的使用者。 |
|
||||
| `page` | `string` | **必填。** Wiki 頁面名稱。 |
|
||||
| `comment` | `string` | Wiki 提交訊息或註解。 |
|
||||
|
||||
#### `repository`
|
||||
|
||||
當儲存庫被建立或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 儲存庫操作類型。 |
|
||||
| `repository` | `object` | **必填。** 被建立或刪除的儲存庫。 |
|
||||
| `organization` | `object` | 當儲存庫屬於某個組織時會出現。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `release`
|
||||
|
||||
當發行版本被發佈、更新或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `published`、`updated`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Release 操作類型。 |
|
||||
| `release` | `object` | **必填。** 被操作的發行版本。 |
|
||||
| `repository` | `object` | **必填。** 包含該發行版本的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `package`
|
||||
|
||||
當套件被建立或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 套件操作類型。 |
|
||||
| `repository` | `object` | 與該套件關聯的儲存庫；如果適用則會出現。 |
|
||||
| `package` | `object` | **必填。** 被操作的套件。 |
|
||||
| `organization` | `object` | 當套件擁有者是組織時會出現。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `status`
|
||||
|
||||
當透過 API 建立或更新提交狀態時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `commit` | `object` | 與該狀態關聯的提交。 |
|
||||
| `context` | `string` | **必填。** 狀態內容，例如 `ci/build`。 |
|
||||
| `created_at` | `string` | **必填。** 狀態建立時間。 |
|
||||
| `description` | `string` | 狀態描述文字。 |
|
||||
| `id` | `integer` | **必填。** 狀態識別碼。 |
|
||||
| `repository` | `object` | **必填。** 包含該提交的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立該狀態的使用者。 |
|
||||
| `sha` | `string` | **必填。** 提交 SHA。 |
|
||||
| `state` | `string` | **必填。** 狀態值，例如 `pending`、`success`、`error` 或 `failure`。 |
|
||||
| `target_url` | `string` | 與該狀態關聯的目標 URL。 |
|
||||
| `updated_at` | `string` | 狀態最後更新時間。 |
|
||||
|
||||
與多數其他 payload 不同，此事件不使用 `action` 欄位，狀態變化透過 `state`
|
||||
欄位表示。
|
||||
|
||||
### 議題事件
|
||||
|
||||
- `issues`、`issue_assign`、`issue_label`、`issue_milestone`、`issue_comment`
|
||||
|
||||
#### `issues`
|
||||
|
||||
當 issue 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Issue 操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_assign`
|
||||
|
||||
當 issue 被指派或取消指派時，會觸發此事件。
|
||||
|
||||
**動作類型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_label`
|
||||
|
||||
當 issue 標籤被更新或清空時，會觸發此事件。
|
||||
|
||||
**動作類型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 標籤更新操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_milestone`
|
||||
|
||||
當 issue 被設定里程碑或移除里程碑時，會觸發此事件。
|
||||
|
||||
**動作類型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_comment`
|
||||
|
||||
當 issue 評論被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 評論操作類型。 |
|
||||
| `issue` | `object` | **必填。** 該評論所屬的 issue。 |
|
||||
| `pull_request` | `object` | 當該評論位於 pull request 時間線上時會出現。 |
|
||||
| `comment` | `object` | **必填。** 被建立、編輯或刪除的評論。 |
|
||||
| `changes` | `object` | 可選。當操作類型為 `edited` 時，表示評論內容的舊值。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `is_pull` | `boolean` | **必填。** 該評論是否位於 pull request 時間線上。 |
|
||||
|
||||
### Pull Request 事件
|
||||
|
||||
- `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`
|
||||
|
||||
當 pull request 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Pull request 操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_assign`
|
||||
|
||||
當 pull request 被指派或取消指派時，會觸發此事件。
|
||||
|
||||
**動作類型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_label`
|
||||
|
||||
當 pull request 標籤被更新或清空時，會觸發此事件。
|
||||
|
||||
**動作類型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 標籤更新操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_milestone`
|
||||
|
||||
當 pull request 被設定里程碑或移除里程碑時，會觸發此事件。
|
||||
|
||||
**動作類型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_comment`
|
||||
|
||||
當 pull request 時間線評論被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 評論操作類型。 |
|
||||
| `issue` | `object` | **必填。** 與該 pull request 關聯的 issue 記錄。 |
|
||||
| `pull_request` | `object` | **必填。** 評論所屬的 pull request。 |
|
||||
| `comment` | `object` | **必填。** 被建立、編輯或刪除的評論。 |
|
||||
| `changes` | `object` | 可選。當操作類型為 `edited` 時，表示評論內容的舊值。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `is_pull` | `boolean` | **必填。** 對此事件而言固定為 `true`。 |
|
||||
|
||||
#### `pull_request_review`
|
||||
|
||||
這是 Webhook 設定介面中的一個僅用於訂閱的彙總事件。
|
||||
|
||||
它不會產生獨立的投遞 payload。勾選後，Gitea 實際投遞的是更具體的
|
||||
`pull_request_review_approved`、`pull_request_review_rejected` 與
|
||||
`pull_request_review_comment` 事件。
|
||||
|
||||
#### `pull_request_review_approved`
|
||||
|
||||
當 pull request review 以核准形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `approved`。 |
|
||||
|
||||
#### `pull_request_review_rejected`
|
||||
|
||||
當 pull request review 以拒絕或請求修改的形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `rejected`。 |
|
||||
|
||||
#### `pull_request_review_comment`
|
||||
|
||||
當 pull request review 以評論形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `comment`。 |
|
||||
|
||||
#### `pull_request_sync`
|
||||
|
||||
當新的提交被推送後，pull request 被同步時，會觸發此事件。
|
||||
|
||||
**動作類型：** `synchronized`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `synchronized`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被同步的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行同步操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該同步事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_review_request`
|
||||
|
||||
當請求審查者或移除審查請求時，會觸發此事件。
|
||||
|
||||
**動作類型：** `review_requested`、`review_request_removed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 審查請求操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 被請求或被移除的審查者。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
### 工作流程事件
|
||||
|
||||
- `workflow_run`、`workflow_job`
|
||||
|
||||
#### `workflow_run`
|
||||
|
||||
當 Gitea Actions 工作流程執行狀態發生變化時，會觸發此事件。
|
||||
|
||||
**動作類型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流程執行狀態變化。 |
|
||||
| `workflow` | `object` | **必填。** 工作流程定義。 |
|
||||
| `workflow_run` | `object` | **必填。** 被操作的工作流程執行記錄。 |
|
||||
| `pull_request` | `object` | 當該工作流程執行與某個 pull request 相關時會出現。 |
|
||||
| `organization` | `object` | 當儲存庫擁有者是組織時會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該工作流程的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 觸發該工作流程執行更新的使用者。 |
|
||||
|
||||
#### `workflow_job`
|
||||
|
||||
當 Gitea Actions 工作流程作業狀態發生變化時，會觸發此事件。
|
||||
|
||||
**動作類型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流程作業狀態變化。 |
|
||||
| `workflow_job` | `object` | **必填。** 被操作的工作流程作業。 |
|
||||
| `pull_request` | `object` | 當該工作流程作業與某個 pull request 相關時會出現。 |
|
||||
| `organization` | `object` | 當儲存庫擁有者是組織時會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該工作流程作業的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 觸發該工作流程作業更新的使用者。 |
|
||||
|
||||
## 測試、最近投遞與重新投遞
|
||||
|
||||
每個 Webhook 頁面都包含：
|
||||
|
||||
- `Test Delivery`：會向儲存庫送出一次模擬的 `push` 事件。
|
||||
- `Recent Deliveries`：顯示請求與回應詳細資訊。
|
||||
- `Redelivery`：重新投遞一筆歷史 Webhook 記錄。
|
||||
|
||||
如果儲存庫還沒有任何提交，測試投遞會使用一個產生的假提交，以便仍能測試
|
||||
Webhook。
|
||||
|
||||
## 管理說明
|
||||
|
||||
管理員還可以透過實例層級設定控制 Webhook 投遞，例如主機允許清單、投遞逾時
|
||||
與清理策略。詳見
|
||||
[設定速查表中的 Webhook 小節](../../administration/config-cheat-sheet.md#webhook-webhook)。
|
||||
|
||||
@@ -8,178 +8,713 @@ aliases:
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
|
||||
所有事件推送都是 POST 请求。目前支持：
|
||||
Gitea 可以為儲存庫活動送出對外 Webhook。儲存庫層級的 Webhook 由儲存庫管理員
|
||||
在 `/:username/:reponame/settings/hooks` 中設定。組織、使用者與系統管理層級
|
||||
也有對應的 Webhook 設定頁面。
|
||||
|
||||
- Gitea (也可以是 GET 请求)
|
||||
Webhook 設定支援四種範圍：
|
||||
|
||||
- `儲存庫 Webhook`：只會對單一儲存庫中的活動觸發。
|
||||
- `組織 Webhook`：對該組織擁有的儲存庫中的活動觸發。
|
||||
- `使用者 Webhook`：對該使用者擁有的儲存庫中的活動觸發。
|
||||
- `系統 Webhook`：對實例中所有符合條件的活動觸發。
|
||||
|
||||
Gitea 也支援由管理員定義的 `預設 Webhook`。它並不是額外的投遞範圍，而是會在
|
||||
建立新儲存庫時被複製到該儲存庫中，之後就會像一般儲存庫 Webhook 一樣運作。
|
||||
|
||||
Gitea 支援以下對外 Webhook 整合：
|
||||
|
||||
- Gitea
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk（钉钉）
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork（企业微信）
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### 事件信息
|
||||
`Gitea` 與 `Gogs` 類型會送出通用 Webhook payload。上面列出的聊天與服務整合
|
||||
則會把同一個內部事件轉換成各自服務所需的請求主體格式。
|
||||
|
||||
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
|
||||
本頁分成三個部分：
|
||||
|
||||
以下是 Gitea 将发送给 payload URL 的事件信息示例：
|
||||
- `設定`：如何設定 Webhook 選項，例如 URL、密鑰、分支過濾器與授權標頭。
|
||||
- `投遞`：Gitea 如何送出 Webhook 請求、會附帶哪些標頭，以及如何驗證投遞。
|
||||
- `事件`：Gitea 會投遞哪些事件，以及每個事件包含哪些頂層 payload 參數。
|
||||
|
||||
## 設定
|
||||
|
||||
本節介紹在建立或編輯 Webhook 時可以設定的選項。
|
||||
|
||||
### 設定 Webhook
|
||||
|
||||
建立 Webhook 時，主要設定項目包括：
|
||||
|
||||
- `Target URL`：接收投遞的目標位址。
|
||||
- `HTTP Method`：通用 Webhook 通常使用 `POST`。
|
||||
- `POST Content Type`：通用 Webhook 可使用 `application/json` 或
|
||||
`application/x-www-form-urlencoded`。
|
||||
- `Secret`：用來對原始請求主體進行 HMAC 簽章。
|
||||
- `Authorization Header`：可選的自訂 `Authorization` 標頭，會隨每次請求送出。
|
||||
- `Branch Filter`：可選的分支或標籤過濾規則。
|
||||
- `Trigger On`：`Push Events`、`All Events` 或自訂事件選擇。
|
||||
- `Active`：是否啟用該 Webhook。
|
||||
|
||||
:::note
|
||||
舊版範例中可能仍會在 JSON payload 裡看到 `secret` 欄位。當前版本的 Gitea
|
||||
不會再把 Webhook 密鑰放進 payload 內容中。請務必透過簽章標頭驗證請求。
|
||||
:::
|
||||
|
||||
### 分支過濾器
|
||||
|
||||
分支過濾器使用與
|
||||
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
|
||||
相容的 glob 語法。
|
||||
|
||||
- 空值、`*` 或 `**` 代表符合全部。
|
||||
- 像 `main` 這樣的一般分支名稱會符合該分支。
|
||||
- 也支援 `refs/tags/v*` 這類完整 ref。
|
||||
- 支援 `{main,release/*}` 這類大括號表達式。
|
||||
- 過濾器只會套用在帶有 git ref 的事件，例如 `create`、`delete` 與 `push`。
|
||||
- 不帶 ref 的事件，例如 issue 或 release，會忽略分支過濾器。
|
||||
|
||||
範例：
|
||||
|
||||
- `main`
|
||||
- `{main,feature/*}`
|
||||
- `{refs/heads/feature/*,refs/tags/release/*}`
|
||||
|
||||
### 授權標頭
|
||||
|
||||
Gitea 可以設定為在每次 Webhook 投遞時送出自訂的
|
||||
[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
它與 Webhook 密鑰彼此獨立：
|
||||
|
||||
- 使用密鑰透過 HMAC 驗證請求完整性。
|
||||
- 當接收端需要應用層認證時，使用 `Authorization` 標頭。
|
||||
|
||||
## 投遞
|
||||
|
||||
本節說明 Gitea 如何送出 Webhook 投遞，以及接收端如何識別與驗證這些請求。
|
||||
|
||||
### 投遞行為
|
||||
|
||||
- Webhook 會透過 HTTP 非同步投遞。
|
||||
- 通用 `Gitea` 與 `Gogs` Webhook 支援 `POST` 與 `GET`；通常應使用 `POST`。
|
||||
- 對於 `POST` 請求，payload 可以直接以 JSON
|
||||
（`application/json`）送出，也可以放在名為 `payload` 的表單欄位中
|
||||
（`application/x-www-form-urlencoded`）。
|
||||
- 某些特定服務整合可能會使用該服務要求的 HTTP 方法與請求主體格式。
|
||||
|
||||
### 投遞標頭
|
||||
|
||||
每次投遞都包含唯一的 delivery ID 與事件標頭。對於相容 GitHub 的整合，
|
||||
Gitea 也會同時送出對應的 GitHub 與 Gogs 風格標頭。
|
||||
|
||||
| 標頭 | 說明 |
|
||||
| --- | --- |
|
||||
| `X-Gitea-Delivery` | 本次投遞嘗試的唯一 UUID。 |
|
||||
| `X-Gitea-Event` | 規範化事件名稱，例如 `push`、`issues` 或 `pull_request`。 |
|
||||
| `X-Gitea-Event-Type` | 更具體的事件類型，例如 `issue_assign` 或 `pull_request_review_comment`。 |
|
||||
| `X-Gitea-Signature` | 原始請求主體的十六進位 HMAC-SHA256 值，不含前綴。 |
|
||||
| `X-Gitea-Hook-Installation-Target-Type` | Webhook 定義所在範圍，通常是 `repository`、`organization`、`user` 或 `system`。預設 Webhook 會先複製到儲存庫後再投遞，因此通常會呈現為 `repository`。 |
|
||||
| `X-Gogs-Delivery`、`X-Gogs-Event`、`X-Gogs-Event-Type`、`X-Gogs-Signature` | 與 Gitea 對應標頭值相同的相容性標頭。 |
|
||||
| `X-GitHub-Delivery`、`X-GitHub-Event`、`X-GitHub-Event-Type` | GitHub 風格相容性標頭。 |
|
||||
| `X-GitHub-Hook-Installation-Target-Type` | GitHub 風格的 Webhook 範圍標頭。 |
|
||||
| `X-Hub-Signature` | GitHub 相容的 HMAC-SHA1 標頭，格式為 `sha1=<digest>`。 |
|
||||
| `X-Hub-Signature-256` | GitHub 相容的 HMAC-SHA256 標頭，格式為 `sha256=<digest>`。 |
|
||||
|
||||
如果未設定密鑰，簽章標頭仍然會存在，但摘要值為空。
|
||||
|
||||
#### `Event` 與 `Event-Type`
|
||||
|
||||
某些 Gitea Webhook 訂閱會被歸類到同一個規範化事件名稱下。例如，issue 指派
|
||||
投遞會歸類到 issue 事件群組：
|
||||
|
||||
```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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你需要知道實際觸發投遞的具體事件類型，請使用 `X-Gitea-Event-Type`。
|
||||
|
||||
### 示例
|
||||
#### 驗證投遞
|
||||
|
||||
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
|
||||
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
|
||||
Gitea 會使用你的 Webhook 密鑰對原始請求主體進行簽章。要驗證一次投遞：
|
||||
|
||||
- 目标 URL：http://mydomain.com/webhook.php
|
||||
- HTTP 方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 触发条件：推送事件
|
||||
- 激活：勾选
|
||||
1. 以接收到的原始內容讀取請求主體。
|
||||
2. 使用 Webhook 密鑰計算 HMAC-SHA256 摘要。
|
||||
3. 將結果與 `X-Gitea-Signature` 或 GitHub 相容的
|
||||
`X-Hub-Signature-256` 進行比較。
|
||||
4. 盡量使用常數時間比較函式。
|
||||
|
||||
现在在你的服务器上创建 php 文件 webhook.php。
|
||||
注意事項：
|
||||
|
||||
- `X-Gitea-Signature` 只包含小寫十六進位的 SHA-256 摘要。
|
||||
- `X-Hub-Signature-256` 使用相同摘要，但帶有 `sha256=` 前綴。
|
||||
- `X-Hub-Signature` 也會為了相容性而送出，其演算法為 SHA-1。
|
||||
- 在完成簽章驗證之前，不應先解析 JSON 或修改請求主體。
|
||||
|
||||
##### PHP 範例
|
||||
|
||||
下面的範例示範如何驗證以 `application/json` 送出的通用 `Gitea` Webhook。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$secret_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
|
||||
## 事件
|
||||
|
||||
### 授权头（Authorization header）
|
||||
本節採用與 GitHub Webhook 文件類似的逐事件描述方式：每個事件都會說明
|
||||
觸發時機，以及 payload 中包含哪些頂層欄位。
|
||||
|
||||
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
事件分組與 Webhook 設定介面中的分組一致：`Repository Events`、
|
||||
`Issue Events`、`Pull Request Events` 與 `Workflow Events`。
|
||||
|
||||
### 儲存庫事件
|
||||
|
||||
- `create`、`delete`、`fork`、`push`、`wiki`、`repository`、`release`、`package`、`status`
|
||||
|
||||
#### `create`
|
||||
|
||||
當分支或標籤被建立時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `sha` | `string` | **必填。** 新建引用對應的物件 ID。 |
|
||||
| `ref` | `string` | **必填。** 被建立的分支名稱或標籤名稱。 |
|
||||
| `ref_type` | `string` | **必填。** 引用類型，例如 `branch` 或 `tag`。 |
|
||||
| `repository` | `object` | **必填。** 建立該引用的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立該引用的使用者。 |
|
||||
|
||||
#### `delete`
|
||||
|
||||
當分支或標籤被刪除時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被刪除的分支名稱或標籤名稱。 |
|
||||
| `ref_type` | `string` | **必填。** 引用類型，例如 `branch` 或 `tag`。 |
|
||||
| `pusher_type` | `string` | **必填。** 刪除該 ref 的行為主體類型。目前 Gitea payload 使用 `user`。 |
|
||||
| `repository` | `object` | **必填。** 刪除該引用所在的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 刪除該引用的使用者。 |
|
||||
|
||||
#### `fork`
|
||||
|
||||
當儲存庫被 fork 時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `forkee` | `object` | **必填。** 新建立的 fork 儲存庫。 |
|
||||
| `repository` | `object` | **必填。** 被 fork 的原始儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立 fork 的使用者。 |
|
||||
|
||||
#### `push`
|
||||
|
||||
當提交被推送到某個分支或標籤時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `ref` | `string` | **必填。** 被推送的完整 ref，例如 `refs/heads/main`。 |
|
||||
| `before` | `string` | **必填。** 推送前的提交 SHA。 |
|
||||
| `after` | `string` | **必填。** 推送後的提交 SHA。 |
|
||||
| `compare_url` | `string` | **必填。** 用於比較 `before` 與 `after` 的 URL。 |
|
||||
| `commits` | `array` | **必填。** 本次推送包含的提交清單。 |
|
||||
| `total_commits` | `integer` | **必填。** 本次推送中的提交數量。 |
|
||||
| `head_commit` | `object` | 本次推送中的最新提交。 |
|
||||
| `repository` | `object` | **必填。** 接收此次推送的儲存庫。 |
|
||||
| `pusher` | `object` | **必填。** 執行推送的使用者。 |
|
||||
| `sender` | `object` | **必填。** 觸發 Webhook 的使用者。 |
|
||||
|
||||
#### `wiki`
|
||||
|
||||
當 Wiki 頁面被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Wiki 頁面操作類型。 |
|
||||
| `repository` | `object` | **必填。** 擁有該 Wiki 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 修改 Wiki 頁面的使用者。 |
|
||||
| `page` | `string` | **必填。** Wiki 頁面名稱。 |
|
||||
| `comment` | `string` | Wiki 提交訊息或註解。 |
|
||||
|
||||
#### `repository`
|
||||
|
||||
當儲存庫被建立或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 儲存庫操作類型。 |
|
||||
| `repository` | `object` | **必填。** 被建立或刪除的儲存庫。 |
|
||||
| `organization` | `object` | 當儲存庫屬於某個組織時會出現。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `release`
|
||||
|
||||
當發行版本被發佈、更新或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `published`、`updated`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Release 操作類型。 |
|
||||
| `release` | `object` | **必填。** 被操作的發行版本。 |
|
||||
| `repository` | `object` | **必填。** 包含該發行版本的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `package`
|
||||
|
||||
當套件被建立或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 套件操作類型。 |
|
||||
| `repository` | `object` | 與該套件關聯的儲存庫；如果適用則會出現。 |
|
||||
| `package` | `object` | **必填。** 被操作的套件。 |
|
||||
| `organization` | `object` | 當套件擁有者是組織時會出現。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
|
||||
#### `status`
|
||||
|
||||
當透過 API 建立或更新提交狀態時，會觸發此事件。
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `commit` | `object` | 與該狀態關聯的提交。 |
|
||||
| `context` | `string` | **必填。** 狀態內容，例如 `ci/build`。 |
|
||||
| `created_at` | `string` | **必填。** 狀態建立時間。 |
|
||||
| `description` | `string` | 狀態描述文字。 |
|
||||
| `id` | `integer` | **必填。** 狀態識別碼。 |
|
||||
| `repository` | `object` | **必填。** 包含該提交的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 建立該狀態的使用者。 |
|
||||
| `sha` | `string` | **必填。** 提交 SHA。 |
|
||||
| `state` | `string` | **必填。** 狀態值，例如 `pending`、`success`、`error` 或 `failure`。 |
|
||||
| `target_url` | `string` | 與該狀態關聯的目標 URL。 |
|
||||
| `updated_at` | `string` | 狀態最後更新時間。 |
|
||||
|
||||
與多數其他 payload 不同，此事件不使用 `action` 欄位，狀態變化透過 `state`
|
||||
欄位表示。
|
||||
|
||||
### 議題事件
|
||||
|
||||
- `issues`、`issue_assign`、`issue_label`、`issue_milestone`、`issue_comment`
|
||||
|
||||
#### `issues`
|
||||
|
||||
當 issue 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Issue 操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_assign`
|
||||
|
||||
當 issue 被指派或取消指派時，會觸發此事件。
|
||||
|
||||
**動作類型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_label`
|
||||
|
||||
當 issue 標籤被更新或清空時，會觸發此事件。
|
||||
|
||||
**動作類型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 標籤更新操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_milestone`
|
||||
|
||||
當 issue 被設定里程碑或移除里程碑時，會觸發此事件。
|
||||
|
||||
**動作類型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作類型。 |
|
||||
| `number` | `integer` | **必填。** Issue 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `issue` | `object` | **必填。** 被操作的 issue。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 issue 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
|
||||
#### `issue_comment`
|
||||
|
||||
當 issue 評論被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 評論操作類型。 |
|
||||
| `issue` | `object` | **必填。** 該評論所屬的 issue。 |
|
||||
| `pull_request` | `object` | 當該評論位於 pull request 時間線上時會出現。 |
|
||||
| `comment` | `object` | **必填。** 被建立、編輯或刪除的評論。 |
|
||||
| `changes` | `object` | 可選。當操作類型為 `edited` 時，表示評論內容的舊值。 |
|
||||
| `repository` | `object` | **必填。** 包含該 issue 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `is_pull` | `boolean` | **必填。** 該評論是否位於 pull request 時間線上。 |
|
||||
|
||||
### Pull Request 事件
|
||||
|
||||
- `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`
|
||||
|
||||
當 pull request 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `opened`、`closed`、`reopened`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** Pull request 操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_assign`
|
||||
|
||||
當 pull request 被指派或取消指派時，會觸發此事件。
|
||||
|
||||
**動作類型：** `assigned`、`unassigned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 指派操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_label`
|
||||
|
||||
當 pull request 標籤被更新或清空時，會觸發此事件。
|
||||
|
||||
**動作類型：** `label_updated`、`label_cleared`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 標籤更新操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_milestone`
|
||||
|
||||
當 pull request 被設定里程碑或移除里程碑時，會觸發此事件。
|
||||
|
||||
**動作類型：** `milestoned`、`demilestoned`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 里程碑操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_comment`
|
||||
|
||||
當 pull request 時間線評論被建立、編輯或刪除時，會觸發此事件。
|
||||
|
||||
**動作類型：** `created`、`edited`、`deleted`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 評論操作類型。 |
|
||||
| `issue` | `object` | **必填。** 與該 pull request 關聯的 issue 記錄。 |
|
||||
| `pull_request` | `object` | **必填。** 評論所屬的 pull request。 |
|
||||
| `comment` | `object` | **必填。** 被建立、編輯或刪除的評論。 |
|
||||
| `changes` | `object` | 可選。當操作類型為 `edited` 時，表示評論內容的舊值。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `is_pull` | `boolean` | **必填。** 對此事件而言固定為 `true`。 |
|
||||
|
||||
#### `pull_request_review`
|
||||
|
||||
這是 Webhook 設定介面中的一個僅用於訂閱的彙總事件。
|
||||
|
||||
它不會產生獨立的投遞 payload。勾選後，Gitea 實際投遞的是更具體的
|
||||
`pull_request_review_approved`、`pull_request_review_rejected` 與
|
||||
`pull_request_review_comment` 事件。
|
||||
|
||||
#### `pull_request_review_approved`
|
||||
|
||||
當 pull request review 以核准形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `approved`。 |
|
||||
|
||||
#### `pull_request_review_rejected`
|
||||
|
||||
當 pull request review 以拒絕或請求修改的形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `rejected`。 |
|
||||
|
||||
#### `pull_request_review_comment`
|
||||
|
||||
當 pull request review 以評論形式提交時，會觸發此事件。
|
||||
|
||||
**動作類型：** `reviewed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `reviewed`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被審查的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 提交該審查的使用者。 |
|
||||
| `commit_id` | `string` | 與該審查事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | **必填。** 審查 payload。對此事件而言，`review.type` 為 `comment`。 |
|
||||
|
||||
#### `pull_request_sync`
|
||||
|
||||
當新的提交被推送後，pull request 被同步時，會觸發此事件。
|
||||
|
||||
**動作類型：** `synchronized`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 固定為 `synchronized`。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被同步的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 在審查請求事件中會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行同步操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該同步事件關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
#### `pull_request_review_request`
|
||||
|
||||
當請求審查者或移除審查請求時，會觸發此事件。
|
||||
|
||||
**動作類型：** `review_requested`、`review_request_removed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 審查請求操作類型。 |
|
||||
| `number` | `integer` | **必填。** Pull request 編號。 |
|
||||
| `changes` | `object` | 可選。編輯欄位之前的值，或標籤變更明細。 |
|
||||
| `pull_request` | `object` | **必填。** 被操作的 pull request。 |
|
||||
| `requested_reviewer` | `object` | 被請求或被移除的審查者。 |
|
||||
| `repository` | `object` | **必填。** 包含該 pull request 的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 執行該操作的使用者。 |
|
||||
| `commit_id` | `string` | 與該 pull request 操作關聯的提交 SHA；如果適用則會出現。 |
|
||||
| `review` | `object` | 在 pull request review 事件中會出現。 |
|
||||
|
||||
### 工作流程事件
|
||||
|
||||
- `workflow_run`、`workflow_job`
|
||||
|
||||
#### `workflow_run`
|
||||
|
||||
當 Gitea Actions 工作流程執行狀態發生變化時，會觸發此事件。
|
||||
|
||||
**動作類型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流程執行狀態變化。 |
|
||||
| `workflow` | `object` | **必填。** 工作流程定義。 |
|
||||
| `workflow_run` | `object` | **必填。** 被操作的工作流程執行記錄。 |
|
||||
| `pull_request` | `object` | 當該工作流程執行與某個 pull request 相關時會出現。 |
|
||||
| `organization` | `object` | 當儲存庫擁有者是組織時會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該工作流程的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 觸發該工作流程執行更新的使用者。 |
|
||||
|
||||
#### `workflow_job`
|
||||
|
||||
當 Gitea Actions 工作流程作業狀態發生變化時，會觸發此事件。
|
||||
|
||||
**動作類型：** `queued`、`waiting`、`in_progress`、`completed`
|
||||
|
||||
##### Payload 參數
|
||||
|
||||
| 名稱 | 類型 | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `action` | `string` | **必填。** 工作流程作業狀態變化。 |
|
||||
| `workflow_job` | `object` | **必填。** 被操作的工作流程作業。 |
|
||||
| `pull_request` | `object` | 當該工作流程作業與某個 pull request 相關時會出現。 |
|
||||
| `organization` | `object` | 當儲存庫擁有者是組織時會出現。 |
|
||||
| `repository` | `object` | **必填。** 包含該工作流程作業的儲存庫。 |
|
||||
| `sender` | `object` | **必填。** 觸發該工作流程作業更新的使用者。 |
|
||||
|
||||
## 測試、最近投遞與重新投遞
|
||||
|
||||
每個 Webhook 頁面都包含：
|
||||
|
||||
- `Test Delivery`：會向儲存庫送出一次模擬的 `push` 事件。
|
||||
- `Recent Deliveries`：顯示請求與回應詳細資訊。
|
||||
- `Redelivery`：重新投遞一筆歷史 Webhook 記錄。
|
||||
|
||||
如果儲存庫還沒有任何提交，測試投遞會使用一個產生的假提交，以便仍能測試
|
||||
Webhook。
|
||||
|
||||
## 管理說明
|
||||
|
||||
管理員還可以透過實例層級設定控制 Webhook 投遞，例如主機允許清單、投遞逾時
|
||||
與清理策略。詳見
|
||||
[設定速查表中的 Webhook 小節](../../administration/config-cheat-sheet.md#webhook-webhook)。
|
||||
|
||||
@@ -8,11 +8,26 @@ aliases:
|
||||
|
||||
# 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 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.
|
||||
|
||||
- Gitea (can also be a GET request)
|
||||
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
|
||||
@@ -20,170 +35,697 @@ All event pushes are POST requests. The methods currently supported are:
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### Event information
|
||||
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.
|
||||
|
||||
:::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
|
||||
## 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.
|
||||
:::
|
||||
|
||||
The following is an example of event information that will be sent by Gitea to
|
||||
a Payload URL:
|
||||
### 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-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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
Use `X-Gitea-Event-Type` when you need the exact trigger that fired the webhook.
|
||||
|
||||
### Example
|
||||
#### Validating deliveries
|
||||
|
||||
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:
|
||||
Gitea signs the raw request body with your webhook secret. To validate a
|
||||
delivery:
|
||||
|
||||
- Target URL: http://mydomain.com/webhook.php
|
||||
- HTTP Method: POST
|
||||
- POST Content Type: application/json
|
||||
- Secret: 123
|
||||
- Trigger On: Push Events
|
||||
- Active: Checked
|
||||
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.
|
||||
|
||||
Now on your server create the php file webhook.php
|
||||
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_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
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.
|
||||
## Events
|
||||
|
||||
### Authorization header
|
||||
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.
|
||||
|
||||
**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.
|
||||
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).
|
||||
|
||||
@@ -9,11 +9,26 @@ aliases:
|
||||
|
||||
# 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 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.
|
||||
|
||||
- Gitea (can also be a GET request)
|
||||
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
|
||||
@@ -21,170 +36,697 @@ All event pushes are POST requests. The methods currently supported are:
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Matrix
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### Event information
|
||||
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.
|
||||
|
||||
:::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
|
||||
## 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.
|
||||
:::
|
||||
|
||||
The following is an example of event information that will be sent by Gitea to
|
||||
a Payload URL:
|
||||
### 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-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
|
||||
X-Gitea-Event: issues
|
||||
X-Gitea-Event-Type: issue_assign
|
||||
X-GitHub-Event: issues
|
||||
X-GitHub-Event-Type: issue_assign
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
Use `X-Gitea-Event-Type` when you need the exact trigger that fired the webhook.
|
||||
|
||||
### Example
|
||||
#### Validating deliveries
|
||||
|
||||
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:
|
||||
Gitea signs the raw request body with your webhook secret. To validate a
|
||||
delivery:
|
||||
|
||||
- Target URL: http://mydomain.com/webhook.php
|
||||
- HTTP Method: POST
|
||||
- POST Content Type: application/json
|
||||
- Secret: 123
|
||||
- Trigger On: Push Events
|
||||
- Active: Checked
|
||||
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.
|
||||
|
||||
Now on your server create the php file webhook.php
|
||||
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_key = '123';
|
||||
$secret = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
|
||||
http_response_code(405);
|
||||
exit('Only POST is allowed');
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
$payload = file_get_contents('php://input');
|
||||
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
if ($payload === false || $signature === '') {
|
||||
http_response_code(400);
|
||||
exit('Missing payload or signature');
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
$expected = hash_hmac('sha256', $payload, $secret);
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
if (!hash_equals($expected, $signature)) {
|
||||
http_response_code(401);
|
||||
exit('Invalid signature');
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
|
||||
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
|
||||
$data = json_decode($payload, true);
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
if (!is_array($data)) {
|
||||
http_response_code(400);
|
||||
exit('Invalid JSON payload');
|
||||
}
|
||||
|
||||
// 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
|
||||
http_response_code(204);
|
||||
```
|
||||
|
||||
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.
|
||||
## Events
|
||||
|
||||
### Authorization header
|
||||
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.
|
||||
|
||||
**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.
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user