---
url: /zh/develops/openapi-event.md
description: |
  介绍 CNB 仓库动态 API，包括各类仓库事件类型 （push、PR、issue 等）及按时间查询仓库操作记录的接口使用方法。
---
## 概述

仓库动态记录 CNB 上触发的各类仓库事件。
每个事件包含通用属性及由事件类型决定的 payload 对象。

仓库动态以小时为最小分片单位记录所有操作，目前支持的动态类型有：

* CreateEvent
* DeleteEvent
* ForkEvent
* IssueCommentEvent
* IssueEvent
* MemberEvent
* PublicEvent
* PullRequestEvent
* PullRequestReviewEvent
* PullRequestReviewCommentEvent
* PushEvent
* ReleaseEvent
* WatchEvent

## API 接口

### 获取仓库指定时间内的动态

* 接口地址：`/events/{repo_path}/-/{date}`
* 请求方法：`GET`
* 输入参数：
  * `repo_path`：仓库完整路径，例如 `cnb/test`
  * `date`：时间区间，支持按小时或天查询。
    **注意：按天查询存在一天的数据滞后性，当天只能查询到前一天的聚合数据**
    * 按小时查询：`yy-mm-dd-h`，例如 `2025-09-11-7`，表示 2025 年 9 月 11 日 07:00:00～07:59:59
    * 按天查询：`yy-mm-dd`，例如 `2025-09-11`，表示 2025 年 9 月 11 日 00:00:00～23:59:59
* 返回：仓库动态列表，结构因事件类型不同而有所差异，但都包含通用属性
  * `eventObject`：动态事件结构，由动态通用属性 + payload 组成

#### 请求与返回示例

以 curl 查询仓库 `cnb/test` 在 `2025-09-11` 07:00–07:59 内的动态为例：

```shell
curl -X "GET" \
  -H "accept: application/json" \
  -H "Authorization: Bearer 1Z00000000000000000000000vA" \
  "https://api.cnbprod.alpha.qq.com/events/cnb/test/-/2025-09-11-7"
```

返回为该时间区间内的仓库动态列表。各事件的 `payload` 结构不同，
但都会包含上文的[动态通用属性](#动态通用属性)。下面以一次 `PushEvent` 为例：

```json
[
  {
    "id": 2100000000000000001,
    "type": "PushEvent",
    "actor": {
      "id": 1816756487609032700,
      "username": "cnb",
      "nickname": "CNB"
    },
    "repo": {
      "id": 1816756487609032701,
      "path": "cnb/test"
    },
    "created_at": "2025-09-11T07:30:00Z",
    "push_id": "2100000000000000002",
    "distinct_size": 1,
    "ref": "refs/heads/main",
    "head": "9f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a",
    "before": "0d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e",
    "commits": [
      {
        "sha": "9f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a",
        "message": "feat: add badge",
        "author": {
          "name": "cnb",
          "email": "cnb@example.com"
        },
        "distinct": true
      }
    ]
  }
]
```

#### 动态通用属性

* id: int，动态 ID，全局唯一。
* type: string，动态类型，见上方「概述」部分。
* actor: object，动态触发人。
  * id: int, 用户 id。
  * username: string, 用户名。
  * nickname: string, 用户昵称。
  * url: string, 查询用户的 OPENAPI 地址，其中包括额外的用户详情。
  * avatar\_url: string, 用户头像地址。
* repo: object, 动态所属仓库详情。
  * id: int, 仓库 id。
  * path: string, 仓库全路径。
  * url: string, 查询仓库的 OPENAPI 地址。
* created\_at: string，动态触发时间，ISO 8601 格式。

#### Payload

##### CreateEvent

记录仓库、分支、标签的创建动态。

* ref: string, git ref 资源，当 ref\_type 为 repository 时，ref 为空字符串。
* ref\_type: string, git ref 对象类型，包含 branch、tag、repository。
* master\_branch: string, 仓库主干分支。
* description: string, 仓库描述。
* pusher\_type: string, 推送者类型，定值 "user"。

##### DeleteEvent

记录分支、标签的删除动态。

* ref: string, git ref 资源。
* ref\_type: string, git ref 对象类型，包含 branch、tag。

##### ForkEvent

记录仓库 fork 动态。

* forkee: *repo* object, fork 的仓库资源。
  * id: int, 仓库 id。
  * name: string, 仓库名。
  * full\_name: string, 仓库全路径。
  * owner: *user* object, 仓库创建用户详情。
    * id: int, 创建者 id。
    * username: string, 用户名。
    * url: string, 查询用户的 OPENAPI 地址，其中包括额外的用户详情。
    * avatar\_url: string, 用户头像地址。
    * html\_url: string, 用户主页地址。
    * followers\_url: string, 用户粉丝列表地址。
    * following\_url: string, 用户关注列表地址。
    * starred\_url: string, 用户关注列表地址。
    * organizations\_url: string, 用户组织列表地址。
    * repos\_url: string, 用户仓库列表地址。
    * type: string, 用户类型，包含 "wechat\_user" - 微信用户，"robot\_user" - 机器人。
  * private: bool, 是否为私有仓库。
  * html\_url: string, 仓库 CNB 地址。
  * description: string, 仓库简介。
  * fork: bool, 是否为 fork 创建。
  * url: string, 仓库详情查询 OPENAPI 地址。
  * branches\_url: string, OPENAPI 地址，仓库分支列表查询。
  * collaborators\_url: string, OPENAPI 地址，仓库成员列表查询。
  * compare\_url: string, OPENAPI 地址，分支差异比较。
  * contents\_url: string, OPENAPI 地址，仓库文件查询。
  * contributors\_url: string, OPENAPI 地址，仓库成员列表查询。
  * forks\_url: string, OPENAPI 地址，仓库 fork 列表查询。
  * git\_commits\_url: string, OPENAPI 地址，查询指定提交详情。
  * git\_tags\_url: string, OPENAPI 地址，查询指定标签详情。
  * issue\_comment\_url: string, OPENAPI 地址，查询 issue 评论列表。
  * issues\_url: string, OPENAPI 地址，查询 issue 列表。
  * labels\_url: string, OPENAPI 地址，查询 issue 标签列表。
  * pulls\_url: string, OPENAPI 地址，查询 pr 列表。
  * releases\_url: string, OPENAPI 地址，查询 release 列表。
  * stargazers\_url: string, OPENAPI 地址，查询 star 仓库的用户列表。
  * tags\_url: string, OPENAPI 地址，查询标签列表。
  * clone\_url: string, 仓库 clone 地址。
  * homepage: string, 仓库主页。
  * language: string, 仓库主语言。
  * forks\_count: int, 仓库被 fork 的次数。
  * stargazers\_count: int, 仓库被 star 的次数。
  * size: int, 仓库存储大小。
  * default\_branch: string, 仓库默认分支。
  * open\_issues\_count: int, 仓库开启状态的 issue 数。
  * topics: string list, 仓库标签列表。
  * has\_issues: bool, 仓库是否有 issue。
  * archived: bool, 仓库是否归档。
  * disabled: bool, 仓库是否不可用。
  * visibility: string, 仓库可见性。
  * pushed\_at: string, 仓库最近一次 push 的时间。
  * created\_at: string, 仓库创建时间。
  * updated\_at: string, 仓库更新时间。
  * license: string, 仓库许可证。

##### IssueCommentEvent

记录 issue 评论动态。

* action: string, 评论操作，包括 created, edited, deleted。
* issue: *issue* object, 评论所属 issue 详情。
  * id: int, issue id。
  * url: string, OPENAPI 地址，查询指定 issue 详情。
  * repository\_url: string, OPENAPI 地址，查询 issue 所在仓库详情。
  * labels\_url: string, OPENAPI 地址，查询 issue 的标签列表。
  * comments\_url: string, OPENAPI 地址，查询 issue 的评论。
  * html\_url: string, issue 的 CNB 地址。
  * number: int, issue 的仓库序列号。
  * state: string, issue 状态。
  * title: string, issue 标题。
  * labels: *label* object list, issue 标签列表。
    * name: string, 标签名。
    * description: string, 标签简介。
    * color: string, 标签颜色。
  * assignees: *user* object list, issue 处理人，对象结构同 *ForkEvent* *user* object。
  * comments: int, issue 评论数。
  * closed\_at: string, issue 关闭时间。
  * created\_at: string, issue 创建时间。
  * updated\_at: string, issue 更新时间。
* comment: *comment* object, 评论详情。
  * id: int, 评论 id
  * url: string, OPENAPI 地址，查询评论详情。
  * html\_url: string, 评论 CNB 地址。
  * body: string, 评论内容。
  * user: *user* object, 评论人，对象结构同 *ForkEvent* *user* object。
  * created\_at: string, 评论创建时间。
  * updated\_at: string, 评论更新时间。
  * issue\_url: string, OPENAPI 地址，查询评论所在 issue 详情。

##### IssueEvent

记录 issue 动态。

* action: string, issue 操作，包括 opened, edited, closed, reopened, assigned, unassigned, labeled, unlabeled。
* issue: *issue* object, issue 详情，对象结构同 *IssueCommentEvent* *issue* object。
* assignees: *user* object, 处理人，对象结构同 *ForkEvent* *user* object。
* labels: *label* object, issue 标签，对象结构同 *IssueCommentEvent* *label* object。

##### MemberEvent

记录添加仓库成员动态。

* action: string, 成员操作，包括 added。
* member: *user* object, 新增成员，对象结构同 *ForkEvent* *user* object。

##### PublicEvent

记录私有仓库转变为公仓的动态。

##### PullRequestEvent

记录 pr 动态。

* action: string, pr 操作，包括 opened, closed, reopened, edited。
* number: int, pr 的仓库序列号。
* pull\_request: *pull\_request* object, pr 详情。
  * id: int, pr id。
  * url: string, OPENAPI 地址，查询 pr 详情。
  * html\_url: string, pr CNB 地址。
  * diff\_url: string, pr diff CNB 地址。
  * commits\_url: string, pr CNB 提交详情地址。
  * number: int, pr 仓库序列号。
  * state: string, pr 状态。
  * title: string, pr 标题。
  * user: *user* object, pr 创建人，对象结构同 *ForkEvent* *user* object。
  * body: string, pr 详情。
  * labels: *label* object list, pr 标签列表，对象结构同 *IssueCommentEvent* *label* object。
  * created\_at: string, pr 创建时间。
  * updated\_at: string, pr 更新时间。
  * closed\_at: string, pr 关闭时间。
  * merged\_at: string, pr merge 时间。
  * assignees: *user* object list, 处理人列表，对象结构同 *ForkEvent* *user* object。
  * requested\_reviewers: *user* object list, 评审人列表，对象结构同 *ForkEvent* *user* object。
  * head: *branch* object, 源分支。
    * ref: string, 分支名。
    * repo: *repo* object, 分支所属仓库，对象结构同 *ForkEvent* *repo* object。
  * base: *branch* object, 目标分支，结构同上。
  * mergeable\_state: string, pr 的合并状态。
  * comments: int, pr 的评论数。

##### PullRequestReviewEvent

记录 pr 的评审动态。

* action: string, pr 评审操作，包括 created。
* pull\_request: *pull\_request* object, pr 详情，对象结构同 *PullRequestEvent* *pull\_request* object。

##### PullRequestReviewCommentEvent

记录 pr 的评审评论。

* action: string, pr 评审操作，包括 opened, edited, deleted。
* pull\_request: *pull\_request* object, pr 详情，对象结构同 *PullRequestEvent* *pull\_request* object。
* comment: *comment* object, 评论详情，对象结构同 *IssueCommentEvent* *comment* object。

##### PushEvent

记录仓库 push 动态。

* push\_id: string, 推送 id。
* distinct\_size: int, 提交去重后的推送大小。
* ref: string, 推送 ref 名。
* head: string, 推送后最近一次提交 sha。
* before: string, 推送前最近一次提交 sha。
* commits: *commit* object list, 提交详情列表。
  * sha: string, 提交 sha。
  * message: string, 提交信息。
  * url: string, OPENAPI 地址，查询指定提交详情。
  * author: *author* object, 提交人。
    * name: string, 提交人名称。
    * email: string, 提交人邮箱。
  * distinct: bool, 是否为新提交。

##### ReleaseEvent

记录仓库 release 动态。

* action: string, release 操作，包括 published, edited, deleted。
* release: *release* object, release 详情。
  * id: int, release id。
  * url: string, OPENAPI 地址，查询指定 release 详情。
  * html\_url: string, release CNB 地址。
  * assets\_url: string, OPENAPI 地址，查询 release 附件。
  * tag\_name: string, 标签名。
  * target\_commitish: string, release 截止提交 sha。
  * name: string, release 名。
  * body: string, release 详情。
  * draft: bool, 是否为草稿。
  * prerelease: bool, 是否为最新的 release。
  * created\_at: string, release 创建时间。
  * published\_at: string, release 发布时间。
  * author: *user* object, 创建人，对象结构同 *ForkEvent* *user* object。
  * assets: *release\_asset* object list, release 附件。
    * id: int, 附件 id。
    * name: string, 附件名。
    * url: string, OPENAPI 地址，查询指定附件详情。
    * label: string, 附件标签。
    * state: string, 附件状态。
    * content\_type: string, 附件文本类型。
    * size: int, 附件大小。
    * digest: string, 附件摘要哈希值。
    * download\_count: int, 附件下载次数。
    * created\_at: string, 附件创建时间。
    * updated\_at: string, 附件更新时间。

##### WatchEvent

记录仓库 star 动态。

* action: string, star 操作，包含 started。