From d31f4dd236e77d463fef63bb0e35b3a9f36a6693 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Tue, 17 Feb 2026 21:49:51 -0800 Subject: [PATCH] improve webhooks documentations --- docs/usage/repository/webhooks.md | 722 ++++++++++++++++++ .../current/usage/repository/webhooks.md | 722 ++++++++++++++++++ 2 files changed, 1444 insertions(+) diff --git a/docs/usage/repository/webhooks.md b/docs/usage/repository/webhooks.md index c65e6e19..355c17e8 100644 --- a/docs/usage/repository/webhooks.md +++ b/docs/usage/repository/webhooks.md @@ -113,6 +113,728 @@ X-Gitea-Event: push } ``` +### Supported events and payloads + +The `X-Gitea-Event` header carries the event type. The list below covers all supported events and their payloads, grouped like the webhook UI. Objects like `Repository`, `User`, `Issue`, `PullRequest`, `Comment`, `Release`, `Package`, `ActionWorkflow`, `ActionWorkflowRun`, and `ActionWorkflowJob` follow the API response schema. The examples below are trimmed for readability. + +#### Repository + +| Event type | Payload type | Description | +| --- | --- | --- | +| `create` | `CreatePayload` | Create branch or tag | +| `delete` | `DeletePayload` | Delete branch or tag | +| `fork` | `ForkPayload` | Repository forked | +| `push` | `PushPayload` | Push event | +| `repository` | `RepositoryPayload` | Repository event | +| `status` | `CommitStatusPayload` | Commit status update | + +#### Issues + +| Event type | Payload type | Description | +| --- | --- | --- | +| `issues` | `IssuePayload` | Issue event | +| `issue_assign` | `IssuePayload` | Issue assigned | +| `issue_label` | `IssuePayload` | Issue label change | +| `issue_milestone` | `IssuePayload` | Issue milestone change | +| `issue_comment` | `IssueCommentPayload` | Issue comment | + +#### Pull requests + +| Event type | Payload type | Description | +| --- | --- | --- | +| `pull_request` | `PullRequestPayload` | Pull request event | +| `pull_request_assign` | `PullRequestPayload` | Pull request assigned | +| `pull_request_label` | `PullRequestPayload` | Pull request label change | +| `pull_request_milestone` | `PullRequestPayload` | Pull request milestone change | +| `pull_request_comment` | `IssueCommentPayload` | Pull request comment | +| `pull_request_review_approved` | `PullRequestPayload` | Pull request approved | +| `pull_request_review_rejected` | `PullRequestPayload` | Pull request rejected | +| `pull_request_review_comment` | `PullRequestPayload` | Pull request review comment | +| `pull_request_sync` | `PullRequestPayload` | Pull request sync | +| `pull_request_review_request` | `PullRequestPayload` | Pull request review requested | + +#### Wiki + +| Event type | Payload type | Description | +| --- | --- | --- | +| `wiki` | `WikiPayload` | Wiki change | + +#### Releases + +| Event type | Payload type | Description | +| --- | --- | --- | +| `release` | `ReleasePayload` | Release event | + +#### Packages + +| Event type | Payload type | Description | +| --- | --- | --- | +| `package` | `PackagePayload` | Package event | + +#### Actions + +| Event type | Payload type | Description | +| --- | --- | --- | +| `workflow_run` | `WorkflowRunPayload` | Actions workflow run | +| `workflow_job` | `WorkflowJobPayload` | Actions workflow job | + +#### Common payload objects + +`PayloadUser` + +| Field | Type | Description | +| --- | --- | --- | +| `name` | string | Author/committer full name | +| `email` | string | Email address | +| `username` | string | Username | + +`PayloadCommitVerification` + +| Field | Type | Description | +| --- | --- | --- | +| `verified` | boolean | Verification status | +| `reason` | string | Verification reason | +| `signature` | string | GPG signature | +| `signer` | PayloadUser | Signer | +| `payload` | string | Signed payload | + +`PayloadCommit` + +| Field | Type | Description | +| --- | --- | --- | +| `id` | string | Commit SHA | +| `message` | string | Commit message | +| `url` | string | Commit URL | +| `author` | PayloadUser | Author | +| `committer` | PayloadUser | Committer | +| `verification` | PayloadCommitVerification | Signature details | +| `timestamp` | string | Commit timestamp | +| `added` | string[] | Added files | +| `removed` | string[] | Removed files | +| `modified` | string[] | Modified files | + +`ChangesFromPayload` + +| Field | Type | Description | +| --- | --- | --- | +| `from` | string | Previous value | + +`ChangesPayload` + +| Field | Type | Description | +| --- | --- | --- | +| `title` | ChangesFromPayload | Title changes | +| `body` | ChangesFromPayload | Body changes | +| `ref` | ChangesFromPayload | Ref changes | +| `added_labels` | Label[] | Added labels | +| `removed_labels` | Label[] | Removed labels | + +`ReviewPayload` + +| Field | Type | Description | +| --- | --- | --- | +| `type` | string | Review type (`approved`, `rejected`, `comment`) | +| `content` | string | Review content | + +#### CreatePayload (`create`) + +| Field | Type | Description | +| --- | --- | --- | +| `sha` | string | SHA of the new ref | +| `ref` | string | New ref name | +| `ref_type` | string | `branch` or `tag` | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | + +```json +{ + "sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4", + "ref": "refs/heads/feature/login", + "ref_type": "branch", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### DeletePayload (`delete`) + +| Field | Type | Description | +| --- | --- | --- | +| `ref` | string | Deleted ref name | +| `ref_type` | string | `branch` or `tag` | +| `pusher_type` | string | Actor type (currently `user`) | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | + +```json +{ + "ref": "refs/tags/v1.0.0", + "ref_type": "tag", + "pusher_type": "user", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### ForkPayload (`fork`) + +| Field | Type | Description | +| --- | --- | --- | +| `forkee` | Repository | Forked repository | +| `repository` | Repository | Source repository | +| `sender` | User | Sender | + +```json +{ + "forkee": { + "id": 10, + "full_name": "octo/demo-fork", + "html_url": "https://gitea.example.com/octo/demo-fork" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### PushPayload (`push`) + +| Field | Type | Description | +| --- | --- | --- | +| `ref` | string | Pushed ref | +| `before` | string | SHA before push | +| `after` | string | SHA after push | +| `compare_url` | string | Compare URL | +| `commits` | PayloadCommit[] | Commits list | +| `total_commits` | number | Total commits | +| `head_commit` | PayloadCommit | Head commit | +| `repository` | Repository | Repository info | +| `pusher` | User | Pusher | +| `sender` | User | Sender | + +```json +{ + "ref": "refs/heads/main", + "before": "28e1879d029cb852e4844d9c718537df08844e03", + "after": "bffeb74224043ba2feb48d137756c8a9331c449a", + "compare_url": "https://gitea.example.com/octo/demo/compare/28e1879...bffeb74", + "commits": [ + { + "id": "bffeb74224043ba2feb48d137756c8a9331c449a", + "message": "Update README", + "url": "https://gitea.example.com/octo/demo/commit/bffeb742", + "author": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "committer": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "timestamp": "2024-03-01T09:10:11Z", + "added": ["README.md"], + "removed": [], + "modified": [] + } + ], + "total_commits": 1, + "head_commit": { + "id": "bffeb74224043ba2feb48d137756c8a9331c449a", + "message": "Update README", + "url": "https://gitea.example.com/octo/demo/commit/bffeb742", + "author": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "committer": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "timestamp": "2024-03-01T09:10:11Z", + "added": ["README.md"], + "removed": [], + "modified": [] + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "pusher": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### IssuePayload (`issues`, `issue_assign`, `issue_label`, `issue_milestone`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | Action (`opened`, `closed`, `reopened`, `edited`, `deleted`, `assigned`, `unassigned`, `label_updated`, `label_cleared`, `synchronized`, `milestoned`, `demilestoned`, `reviewed`, `review_requested`, `review_request_removed`) | +| `number` | number | Issue number | +| `changes` | ChangesPayload | Changes for edits | +| `issue` | Issue | Issue info | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | +| `commit_id` | string | Related commit | + +```json +{ + "action": "opened", + "number": 12, + "issue": { + "id": 1001, + "number": 12, + "title": "Bug: login failed", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/issues/12" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "commit_id": "" +} +``` + +#### IssueCommentPayload (`issue_comment`, `pull_request_comment`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | `created`, `edited`, `deleted` | +| `issue` | Issue | Issue info | +| `pull_request` | PullRequest | Pull request info (if applicable) | +| `comment` | Comment | Comment info | +| `changes` | ChangesPayload | Changes for edits | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | +| `is_pull` | boolean | Whether comment is on a PR | + +```json +{ + "action": "created", + "issue": { + "id": 1001, + "number": 12, + "title": "Bug: login failed", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/issues/12" + }, + "pull_request": { + "id": 2001, + "number": 5, + "title": "Fix login", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/pulls/5" + }, + "comment": { + "id": 3001, + "body": "Looks good to me!", + "html_url": "https://gitea.example.com/octo/demo/issues/12#issuecomment-3001" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "is_pull": true +} +``` + +#### PullRequestPayload (pull_request series) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | Action (same as issue events, e.g. `opened`, `closed`, `edited`, `synchronized`, `reviewed`, `review_requested`) | +| `number` | number | Pull request number | +| `changes` | ChangesPayload | Changes for edits | +| `pull_request` | PullRequest | Pull request info | +| `requested_reviewer` | User | Requested reviewer | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | +| `commit_id` | string | Related commit | +| `review` | ReviewPayload | Review info | + +```json +{ + "action": "review_requested", + "number": 5, + "pull_request": { + "id": 2001, + "number": 5, + "title": "Fix login", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/pulls/5" + }, + "requested_reviewer": { + "id": 3, + "login": "reviewer", + "full_name": "Code Reviewer", + "avatar_url": "https://gitea.example.com/avatars/3", + "username": "reviewer" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "commit_id": "d670460b4b4aece5915caf5c68d12f560a9fe3e4", + "review": { + "type": "approved", + "content": "LGTM" + } +} +``` + +#### WikiPayload (`wiki`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | `created`, `edited`, `deleted` | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | +| `page` | string | Page name | +| `comment` | string | Comment/message | + +```json +{ + "action": "edited", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "page": "Home", + "comment": "Update wiki" +} +``` + +#### RepositoryPayload (`repository`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | `created` or `deleted` | +| `repository` | Repository | Repository info | +| `organization` | User | Organization owner (if any) | +| `sender` | User | Sender | + +```json +{ + "action": "created", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "organization": { + "id": 9, + "username": "octo-org", + "full_name": "Octo Org", + "avatar_url": "https://gitea.example.com/avatars/9" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### ReleasePayload (`release`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | `published`, `updated`, `deleted` | +| `release` | Release | Release info | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | + +```json +{ + "action": "published", + "release": { + "id": 4001, + "tag_name": "v1.0.0", + "name": "v1.0.0", + "body": "First stable release", + "html_url": "https://gitea.example.com/octo/demo/releases/tag/v1.0.0" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### PackagePayload (`package`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | `created` or `deleted` | +| `repository` | Repository | Related repository | +| `package` | Package | Package info | +| `organization` | Organization | Organization owner (if any) | +| `sender` | User | Sender | + +```json +{ + "action": "created", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "package": { + "id": 5001, + "name": "demo", + "version": "1.0.0", + "type": "npm", + "html_url": "https://gitea.example.com/api/packages/octo/demo" + }, + "organization": { + "id": 9, + "username": "octo-org", + "full_name": "Octo Org", + "avatar_url": "https://gitea.example.com/avatars/9" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### CommitStatusPayload (`status`) + +| Field | Type | Description | +| --- | --- | --- | +| `commit` | PayloadCommit | Related commit | +| `context` | string | Status context | +| `created_at` | string | Created time | +| `description` | string | Status description | +| `id` | number | Status ID | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | +| `sha` | string | Commit SHA | +| `state` | string | `pending`, `success`, `error`, `failure` | +| `target_url` | string | Target URL | +| `updated_at` | string | Updated time | + +```json +{ + "commit": { + "id": "bffeb74224043ba2feb48d137756c8a9331c449a", + "message": "Update README", + "url": "https://gitea.example.com/octo/demo/commit/bffeb742", + "author": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "committer": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "timestamp": "2024-03-01T09:10:11Z", + "added": [], + "removed": [], + "modified": [] + }, + "context": "ci/build", + "created_at": "2024-03-01T09:12:00Z", + "description": "Build passed", + "id": 6001, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "sha": "bffeb74224043ba2feb48d137756c8a9331c449a", + "state": "success", + "target_url": "https://ci.example.com/build/1", + "updated_at": "2024-03-01T09:12:05Z" +} +``` + +#### WorkflowRunPayload (`workflow_run`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | Action (e.g. `requested`, `completed`) | +| `workflow` | ActionWorkflow | Workflow definition | +| `workflow_run` | ActionWorkflowRun | Workflow run | +| `pull_request` | PullRequest | Related PR (if any) | +| `organization` | Organization | Organization owner (if any) | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | + +```json +{ + "action": "completed", + "workflow": { + "id": 7001, + "name": "CI", + "path": ".gitea/workflows/ci.yml", + "state": "active", + "html_url": "https://gitea.example.com/octo/demo/actions/workflows/ci.yml" + }, + "workflow_run": { + "id": 8001, + "event": "push", + "status": "completed", + "conclusion": "success", + "head_branch": "main", + "head_sha": "bffeb74224043ba2feb48d137756c8a9331c449a", + "run_number": 3, + "html_url": "https://gitea.example.com/octo/demo/actions/runs/8001" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### WorkflowJobPayload (`workflow_job`) + +| Field | Type | Description | +| --- | --- | --- | +| `action` | string | Action (e.g. `queued`, `in_progress`, `completed`) | +| `workflow_job` | ActionWorkflowJob | Workflow job | +| `pull_request` | PullRequest | Related PR (if any) | +| `organization` | Organization | Organization owner (if any) | +| `repository` | Repository | Repository info | +| `sender` | User | Sender | + +```json +{ + "action": "completed", + "workflow_job": { + "id": 9001, + "name": "build", + "status": "completed", + "conclusion": "success", + "run_id": 8001, + "head_sha": "bffeb74224043ba2feb48d137756c8a9331c449a", + "html_url": "https://gitea.example.com/octo/demo/actions/jobs/9001" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + ### Example This is an example of how to use webhooks to run a php script upon push requests to the repository. diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repository/webhooks.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repository/webhooks.md index 9210f0b5..c130d598 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repository/webhooks.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repository/webhooks.md @@ -108,6 +108,728 @@ X-Gitea-Event: push } ``` +### 支持的事件类型与 Payload + +`X-Gitea-Event` 头会携带事件类型。下面列出当前支持的事件类型和对应的 payload，并按照 Webhook 界面进行分组。`Repository`、`User`、`Issue`、`PullRequest`、`Comment`、`Release`、`Package`、`ActionWorkflow`、`ActionWorkflowRun`、`ActionWorkflowJob` 等对象结构与 API 响应保持一致，以下示例为精简字段，便于快速理解。 + +#### 仓库 + +| 事件类型 | Payload 类型 | 说明 | +| --- | --- | --- | +| `create` | `CreatePayload` | 创建分支/标签 | +| `delete` | `DeletePayload` | 删除分支/标签 | +| `fork` | `ForkPayload` | 仓库被 fork | +| `push` | `PushPayload` | 代码推送 | +| `repository` | `RepositoryPayload` | 仓库事件 | +| `status` | `CommitStatusPayload` | Commit 状态更新 | + +#### Issue + +| 事件类型 | Payload 类型 | 说明 | +| --- | --- | --- | +| `issues` | `IssuePayload` | Issue 事件 | +| `issue_assign` | `IssuePayload` | Issue 分配 | +| `issue_label` | `IssuePayload` | Issue 标签变更 | +| `issue_milestone` | `IssuePayload` | Issue 里程碑变更 | +| `issue_comment` | `IssueCommentPayload` | Issue 评论 | + +#### PR + +| 事件类型 | Payload 类型 | 说明 | +| --- | --- | --- | +| `pull_request` | `PullRequestPayload` | PR 事件 | +| `pull_request_assign` | `PullRequestPayload` | PR 分配 | +| `pull_request_label` | `PullRequestPayload` | PR 标签变更 | +| `pull_request_milestone` | `PullRequestPayload` | PR 里程碑变更 | +| `pull_request_comment` | `IssueCommentPayload` | PR 评论 | +| `pull_request_review_approved` | `PullRequestPayload` | PR 审核通过 | +| `pull_request_review_rejected` | `PullRequestPayload` | PR 审核拒绝 | +| `pull_request_review_comment` | `PullRequestPayload` | PR 审核评论 | +| `pull_request_sync` | `PullRequestPayload` | PR 同步分支 | +| `pull_request_review_request` | `PullRequestPayload` | PR 请求审核 | + +#### Wiki + +| 事件类型 | Payload 类型 | 说明 | +| --- | --- | --- | +| `wiki` | `WikiPayload` | Wiki 变更 | + +#### Release + +| 事件类型 | Payload 类型 | 说明 | +| --- | --- | --- | +| `release` | `ReleasePayload` | Release 事件 | + +#### Package + +| 事件类型 | Payload 类型 | 说明 | +| --- | --- | --- | +| `package` | `PackagePayload` | Package 事件 | + +#### Actions + +| 事件类型 | Payload 类型 | 说明 | +| --- | --- | --- | +| `workflow_run` | `WorkflowRunPayload` | Actions 运行 | +| `workflow_job` | `WorkflowJobPayload` | Actions 任务 | + +#### 通用 payload 对象 + +`PayloadUser` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `name` | string | 提交作者/提交者姓名 | +| `email` | string | 邮箱 | +| `username` | string | 用户名 | + +`PayloadCommitVerification` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `verified` | boolean | 是否校验通过 | +| `reason` | string | 校验原因 | +| `signature` | string | GPG 签名 | +| `signer` | PayloadUser | 签名人 | +| `payload` | string | 签名内容 | + +`PayloadCommit` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `id` | string | Commit SHA | +| `message` | string | Commit 信息 | +| `url` | string | Commit 地址 | +| `author` | PayloadUser | 提交作者 | +| `committer` | PayloadUser | 提交者 | +| `verification` | PayloadCommitVerification | 签名信息 | +| `timestamp` | string | Commit 时间 | +| `added` | string[] | 新增文件列表 | +| `removed` | string[] | 删除文件列表 | +| `modified` | string[] | 修改文件列表 | + +`ChangesFromPayload` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `from` | string | 修改前的值 | + +`ChangesPayload` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `title` | ChangesFromPayload | 标题变更 | +| `body` | ChangesFromPayload | 内容变更 | +| `ref` | ChangesFromPayload | 引用变更 | +| `added_labels` | Label[] | 新增标签 | +| `removed_labels` | Label[] | 移除标签 | + +`ReviewPayload` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `type` | string | 审核类型（例如 `approved`、`rejected`、`comment`） | +| `content` | string | 审核内容 | + +#### CreatePayload（`create`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `sha` | string | 新引用的 SHA | +| `ref` | string | 新引用名称 | +| `ref_type` | string | `branch` 或 `tag` | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | + +```json +{ + "sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4", + "ref": "refs/heads/feature/login", + "ref_type": "branch", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### DeletePayload（`delete`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `ref` | string | 删除的引用名称 | +| `ref_type` | string | `branch` 或 `tag` | +| `pusher_type` | string | 触发类型（目前为 `user`） | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | + +```json +{ + "ref": "refs/tags/v1.0.0", + "ref_type": "tag", + "pusher_type": "user", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### ForkPayload（`fork`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `forkee` | Repository | 新 fork 的仓库 | +| `repository` | Repository | 原仓库 | +| `sender` | User | 触发人 | + +```json +{ + "forkee": { + "id": 10, + "full_name": "octo/demo-fork", + "html_url": "https://gitea.example.com/octo/demo-fork" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### PushPayload（`push`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `ref` | string | 推送引用 | +| `before` | string | 推送前的 SHA | +| `after` | string | 推送后的 SHA | +| `compare_url` | string | 对比链接 | +| `commits` | PayloadCommit[] | Commit 列表 | +| `total_commits` | number | Commit 数量 | +| `head_commit` | PayloadCommit | 最新 Commit | +| `repository` | Repository | 仓库信息 | +| `pusher` | User | 推送人 | +| `sender` | User | 触发人 | + +```json +{ + "ref": "refs/heads/main", + "before": "28e1879d029cb852e4844d9c718537df08844e03", + "after": "bffeb74224043ba2feb48d137756c8a9331c449a", + "compare_url": "https://gitea.example.com/octo/demo/compare/28e1879...bffeb74", + "commits": [ + { + "id": "bffeb74224043ba2feb48d137756c8a9331c449a", + "message": "Update README", + "url": "https://gitea.example.com/octo/demo/commit/bffeb742", + "author": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "committer": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "timestamp": "2024-03-01T09:10:11Z", + "added": ["README.md"], + "removed": [], + "modified": [] + } + ], + "total_commits": 1, + "head_commit": { + "id": "bffeb74224043ba2feb48d137756c8a9331c449a", + "message": "Update README", + "url": "https://gitea.example.com/octo/demo/commit/bffeb742", + "author": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "committer": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "timestamp": "2024-03-01T09:10:11Z", + "added": ["README.md"], + "removed": [], + "modified": [] + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "pusher": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### IssuePayload（`issues`、`issue_assign`、`issue_label`、`issue_milestone`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | 动作（如 `opened`、`closed`、`reopened`、`edited`、`deleted`、`assigned`、`unassigned`、`label_updated`、`label_cleared`、`synchronized`、`milestoned`、`demilestoned`、`reviewed`、`review_requested`、`review_request_removed`） | +| `number` | number | Issue 编号 | +| `changes` | ChangesPayload | 变更内容（编辑时） | +| `issue` | Issue | Issue 信息 | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | +| `commit_id` | string | 关联的提交 | + +```json +{ + "action": "opened", + "number": 12, + "issue": { + "id": 1001, + "number": 12, + "title": "Bug: login failed", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/issues/12" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "commit_id": "" +} +``` + +#### IssueCommentPayload（`issue_comment`、`pull_request_comment`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | `created`、`edited`、`deleted` | +| `issue` | Issue | Issue 信息 | +| `pull_request` | PullRequest | PR 信息（评论在 PR 时） | +| `comment` | Comment | 评论信息 | +| `changes` | ChangesPayload | 变更内容（编辑时） | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | +| `is_pull` | boolean | 是否为 PR 评论 | + +```json +{ + "action": "created", + "issue": { + "id": 1001, + "number": 12, + "title": "Bug: login failed", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/issues/12" + }, + "pull_request": { + "id": 2001, + "number": 5, + "title": "Fix login", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/pulls/5" + }, + "comment": { + "id": 3001, + "body": "Looks good to me!", + "html_url": "https://gitea.example.com/octo/demo/issues/12#issuecomment-3001" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "is_pull": true +} +``` + +#### PullRequestPayload（`pull_request` 系列事件） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | 动作（同 Issue 事件，如 `opened`、`closed`、`edited`、`synchronized`、`reviewed`、`review_requested` 等） | +| `number` | number | PR 编号 | +| `changes` | ChangesPayload | 变更内容（编辑时） | +| `pull_request` | PullRequest | PR 信息 | +| `requested_reviewer` | User | 目标审核人（请求审核时） | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | +| `commit_id` | string | 关联的提交 | +| `review` | ReviewPayload | 审核信息（审核事件时） | + +```json +{ + "action": "review_requested", + "number": 5, + "pull_request": { + "id": 2001, + "number": 5, + "title": "Fix login", + "state": "open", + "html_url": "https://gitea.example.com/octo/demo/pulls/5" + }, + "requested_reviewer": { + "id": 3, + "login": "reviewer", + "full_name": "Code Reviewer", + "avatar_url": "https://gitea.example.com/avatars/3", + "username": "reviewer" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "commit_id": "d670460b4b4aece5915caf5c68d12f560a9fe3e4", + "review": { + "type": "approved", + "content": "LGTM" + } +} +``` + +#### WikiPayload（`wiki`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | `created`、`edited`、`deleted` | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | +| `page` | string | 页面名 | +| `comment` | string | 备注 | + +```json +{ + "action": "edited", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "page": "Home", + "comment": "Update wiki" +} +``` + +#### RepositoryPayload（`repository`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | `created` 或 `deleted` | +| `repository` | Repository | 仓库信息 | +| `organization` | User | 所属组织（如有） | +| `sender` | User | 触发人 | + +```json +{ + "action": "created", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "organization": { + "id": 9, + "username": "octo-org", + "full_name": "Octo Org", + "avatar_url": "https://gitea.example.com/avatars/9" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### ReleasePayload（`release`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | `published`、`updated`、`deleted` | +| `release` | Release | Release 信息 | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | + +```json +{ + "action": "published", + "release": { + "id": 4001, + "tag_name": "v1.0.0", + "name": "v1.0.0", + "body": "First stable release", + "html_url": "https://gitea.example.com/octo/demo/releases/tag/v1.0.0" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### PackagePayload（`package`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | `created` 或 `deleted` | +| `repository` | Repository | 关联仓库 | +| `package` | Package | Package 信息 | +| `organization` | Organization | 所属组织（如有） | +| `sender` | User | 触发人 | + +```json +{ + "action": "created", + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "package": { + "id": 5001, + "name": "demo", + "version": "1.0.0", + "type": "npm", + "html_url": "https://gitea.example.com/api/packages/octo/demo" + }, + "organization": { + "id": 9, + "username": "octo-org", + "full_name": "Octo Org", + "avatar_url": "https://gitea.example.com/avatars/9" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### CommitStatusPayload（`status`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `commit` | PayloadCommit | 关联 Commit | +| `context` | string | 状态上下文 | +| `created_at` | string | 创建时间 | +| `description` | string | 状态描述 | +| `id` | number | 状态 ID | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | +| `sha` | string | Commit SHA | +| `state` | string | `pending`、`success`、`error`、`failure` | +| `target_url` | string | 关联链接 | +| `updated_at` | string | 更新时间 | + +```json +{ + "commit": { + "id": "bffeb74224043ba2feb48d137756c8a9331c449a", + "message": "Update README", + "url": "https://gitea.example.com/octo/demo/commit/bffeb742", + "author": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "committer": { + "name": "Octo Cat", + "email": "octo@example.com", + "username": "octo" + }, + "timestamp": "2024-03-01T09:10:11Z", + "added": [], + "removed": [], + "modified": [] + }, + "context": "ci/build", + "created_at": "2024-03-01T09:12:00Z", + "description": "Build passed", + "id": 6001, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + }, + "sha": "bffeb74224043ba2feb48d137756c8a9331c449a", + "state": "success", + "target_url": "https://ci.example.com/build/1", + "updated_at": "2024-03-01T09:12:05Z" +} +``` + +#### WorkflowRunPayload（`workflow_run`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | 事件动作（如 `requested`、`completed`） | +| `workflow` | ActionWorkflow | Workflow 定义 | +| `workflow_run` | ActionWorkflowRun | Workflow 运行 | +| `pull_request` | PullRequest | 关联 PR（如有） | +| `organization` | Organization | 所属组织（如有） | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | + +```json +{ + "action": "completed", + "workflow": { + "id": 7001, + "name": "CI", + "path": ".gitea/workflows/ci.yml", + "state": "active", + "html_url": "https://gitea.example.com/octo/demo/actions/workflows/ci.yml" + }, + "workflow_run": { + "id": 8001, + "event": "push", + "status": "completed", + "conclusion": "success", + "head_branch": "main", + "head_sha": "bffeb74224043ba2feb48d137756c8a9331c449a", + "run_number": 3, + "html_url": "https://gitea.example.com/octo/demo/actions/runs/8001" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + +#### WorkflowJobPayload（`workflow_job`） + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `action` | string | 事件动作（如 `queued`、`in_progress`、`completed`） | +| `workflow_job` | ActionWorkflowJob | Workflow 任务 | +| `pull_request` | PullRequest | 关联 PR（如有） | +| `organization` | Organization | 所属组织（如有） | +| `repository` | Repository | 仓库信息 | +| `sender` | User | 触发人 | + +```json +{ + "action": "completed", + "workflow_job": { + "id": 9001, + "name": "build", + "status": "completed", + "conclusion": "success", + "run_id": 8001, + "head_sha": "bffeb74224043ba2feb48d137756c8a9331c449a", + "html_url": "https://gitea.example.com/octo/demo/actions/jobs/9001" + }, + "repository": { + "id": 1, + "full_name": "octo/demo", + "html_url": "https://gitea.example.com/octo/demo" + }, + "sender": { + "id": 2, + "login": "octo", + "full_name": "Octo Cat", + "avatar_url": "https://gitea.example.com/avatars/2", + "username": "octo" + } +} +``` + ### 示例 这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。