注意
问题状态处于 预览,并且仅适用于在预览版中注册的帐户。 Webhook 有效负载和 status_changed 活动类型可能会更改。
关于状态更改事件
当问题的状态发生更改时,GitHub使用status_changed操作发送 issues Webhook 事件。 每个 issues 操作的有效负载还包括问题的 issue.status当前状态。 可以使用这些事件使其他工具与问题保持同步,或者在问题达到特定状态时运行 GitHub Actions 工作流。
仅针对使用问题状态的存储库中的问题包含状态。 对于其他问题,负载不包括 issue.status,GitHub 也不会发送 status_changed。
有关完整有效负载架构,请参阅 Webhook 事件和有效负载。
状态对象
Webhook 有效负载使用具有三个属性的对象来描述每个状态。
| Property | 类型 | Description |
|---|---|---|
id | Integer | 状态的标识符。 |
name | String | 状态的显示名称,例如 In progress。 名称可以更改。 |
category | String | 状态的类别,例如backlog、planned、started、completed或not_planned``duplicate。 将来可能会添加更多类别。 |
多个状态可以属于同一类别。 例如,“正在进行”和“审核中”都属于 started 类别。 若要匹配代码或工作流中的一个状态,请使用其id。 若要匹配类别中的每个状态,请使用其 category。 不匹配 name。
issue.status 是在问题没有状态时 null。 例如,在其仓库支持状态之前创建的问题,在有人设置状态之前,或者在该问题被关闭或重新打开之前,都没有状态。
status_changed有效负载
除了issue、repository、sender以及每个issues有效负载包含的其他属性外,status_changed有效负载还包括以下属性。 对于此操作, sender 是更改状态的人员或应用。
| Property | Description |
|---|---|
status | 问题更改为的状态。 |
changes.status.from | 问题在更改之前的状态,如果之前没有状态,则为 null。 |
changes.state.from | 问题的上一个 state,即 open 或 closed。 仅当状态更改也关闭或重新打开问题时才包含。 |
changes.state_reason.from | 问题之前的 state_reason。 仅当状态更改也更改状态原因(例如关闭或重新打开问题或更改关闭原因)时才包含。 |
当问题没有状态原因时,例如第一次关闭时,就是null。 |
捕获的值和当前议题
属性 status 和 changes 描述保存时的更改。 该 issue 属性(包括 issue.status)描述生成传递时的问题,与所有其他 issues 操作相同。 如果问题在此之前再次发生更改,issue.status 则可能与 status 不同。 例如,如果有人将问题从“进行中”移到“审阅中”,然后又很快移到“完成”,则第一次更改的交付中的 issue.status 可能为“完成”。
若要了解特定更改做了什么,请使用 status 和 changes。 延迟、重试或重新传送的有效负载可能已过时,因此 issue.status 可能不是问题的最新状态。 有关详细信息,请参阅本文后面的 “交付”。
何时发送 status_changed
GitHub 每次问题状态更改时发送 status_changed ,包括 GitHub 创建、关闭或重新打开问题时所做的更改。
- 设置状态:有人为问题选择其他状态。
- 创建问题:新问题会获得积压工作状态,除非创建该问题的人员选择其他状态。
changes.status.from是null。 GitHub 发送opened和status_changed。 - 设置第一个状态:没有状态的现有问题将得到一个。
changes.status.from是null。 - 关闭或重新打开问题:将问题作为已完成关闭会设置“完成”状态,将其作为未计划关闭会设置“未计划”,将其作为重复项关闭会设置“重复项”。 重新打开问题而不选择状态会将其设为“积压工作”。
GitHub 发送
closed或reopened,以及status_changed。 - 链接拉取请求:将打开的拉取请求链接到没有状态或具有积压工作或待办事项状态的打开问题,将问题移动到正在进行中。
sender是链接拉取请求的人员或应用。 如果他们无法为问题选择状态,则状态不会更改。
GitHub 在这些情况下不会发送 status_changed :
- 状态不会更改,例如,当有人选择问题已有的状态时。
- 问题将转移到另一个仓库。 新问题保留其状态,该状态包含在
changes.new_issue.status中的transferred负载里。
关闭或重新打开问题的状态更改
处于completed、not_planned和duplicate类别中的状态适用于已关闭的问题。 为打开的问题选择其中一种状态会关闭该问题,并为已关闭的问题选择任何其他类别中的状态会重新打开它。
当状态更改关闭或重新打开问题时,GitHub会发送两个交付:status_changed,以及 closed 或 reopened。 这两个交付可以按任一顺序到达。
将已关闭的问题更改为具有不同关闭原因的状态(例如,从“完成”更改为“未计划”)会发送status_changed,其中包含changes.state_reason,但不包含changes.state。
GitHub 还会发送另一个带有新 state_reason 的 closed 交付。
如果您的集成处理 status_changed、closed 或 reopened,请确保它可以处理两个交付报告的同一更改。
交付
GitHub 以与其他 Webhook 事件相同的方式传递 status_changed。 交付是尽力而为。
GitHub 不保证每个更改都恰好交付一次,或者交付会按更改发生的顺序到达。
- 传递失败:传递可能会失败,例如,如果服务器不可用。 GitHub 不会自动重新传送失败的传送,但您可以重新传送它们。 有关详细信息,请参阅“处理失败的 Webhook 交付”。
- 重复交付:可以多次接收相同的交付,例如重新传送时。 重新投递的标头与原始投递具有相同的
X-GitHub-Delivery标头,因此可以使用该标头跳过已处理的投递。 - 订单:交付可以无序到达,延迟、重试或重新交付的有效负载可能已过时,包括
issue.status。 不要使用交付到达的顺序来确定问题的最新状态。
若要获取问题的最新状态,请使用 REST API 获取该问题。 有关详细信息,请参阅“适用于问题的 REST API 终结点”。 在组织拥有的存储库中,响应包括 status 任何经过身份验证的请求,包括作为 GitHub App 安装和工作流中使用的 GITHUB_TOKEN 请求进行身份验证的请求。
预览在个人帐户拥有的存储库中,响应仅当代表有权访问预览的用户发出请求时才包含status。 如果响应不包括 status,请谨慎使用交付状态,因为以后到达的交付可以携带较旧的状态。
谁可以更改状态
对存储库具有分流访问权限或更高权限的人员可以选择其问题的状态。 其他权限规则适用于自定义角色、应用、工作流和个人帐户:
- 自定义存储库角色:在组织拥有的存储库中,拥有继承分类、写入或维护角色的自定义角色的人员可以选择状态。 具有继承 Read 角色的自定义角色的人员无法选择状态,即使该角色可以设置问题类型。
- 应用和工作流:在组织拥有的存储库中,拥有“问题”存储库权限写入权限的 GitHub Apps 也可以选择状态,包括使用具有
issues: write权限的GITHUB_TOKEN的工作流。 - 个人帐户:在 预览个人帐户拥有的存储库中,只有有权访问预览的人员才能选择状态。
选择关闭或重新打开问题的状态还需要有权关闭或重新打开问题。 更改关闭问题的原因(例如,从“完成”更改为“未计划”)需要同时关闭并重新打开它的权限。
无法选择状态的人员仍可以通过关闭或重新打开问题来更改状态。 例如,问题的作者可以在拥有对仓库的读取权限时关闭并重新打开问题,这会设置新状态的默认状态值。 这些更改也会触发 status_changed,并且 sender 是关闭或重新打开问题的人员。
状态更改时运行工作流
若要在问题状态发生更改时运行 GitHub Actions 工作流,请使用 status_changed 事件的活动类型 issues 。 每当问题的状态发生更改时,工作流都运行。 在工作流中,github.event 上下文的以下属性描述了这一更改。
github.event.status包含问题更改后的状态。github.event.changes.status.from包含之前的状态,或者如果该问题之前没有先前状态,则为null。github.event.issue.status包含生成有效负载时问题的状态。 每个issues活动类型的有效负载包括此属性。
重要
使用status_changed事件但不使用types的工作流也会针对issues运行。 每当有人更改问题的状态时,这些工作流就会运行,并在创建、关闭或重新打开问题时运行额外的时间,因为 GitHub 发送 status_changed 以及 opened, closed或 reopened。 若要避免意外运行,请列出工作流所需的活动类型。
在 预览 期间,验证工作流文件的编辑器(如 GitHub 上的工作流编辑器)可能会报告 status_changed 为无效的活动类型。 可以忽略此错误。
有关按其 ID 和类别中的每个状态匹配状态的示例工作流,请参阅 触发工作流的事件。
示例数据负载
以下摘录显示了描述更改的 status_changed 负载的属性。 完整有效负载还包括完整的 issue、repository 和 sender 对象,以及其他属性。
创建议题
当某人在不选择状态的情况下创建问题时,该问题将被设为“Backlog”状态。
changes.status.from是null,且changes不包含state或state_reason。
{
"action": "status_changed",
"issue": {
"number": 1347,
"state": "open",
"state_reason": null,
"status": {
"id": 2,
"name": "Backlog",
"category": "backlog"
}
},
"status": {
"id": 2,
"name": "Backlog",
"category": "backlog"
},
"changes": {
"status": {
"from": null
}
}
}
更改为同一类别中的状态
将问题从“正在进行”移动到“正在审阅”不会更改其状态或类别,因此 changes 仅包括 status。
{
"action": "status_changed",
"issue": {
"number": 1347,
"state": "open",
"state_reason": null,
"status": {
"id": 8,
"name": "In review",
"category": "started"
}
},
"status": {
"id": 8,
"name": "In review",
"category": "started"
},
"changes": {
"status": {
"from": {
"id": 4,
"name": "In progress",
"category": "started"
}
}
}
}
通过更改问题状态来关闭问题
将问题从“正在审阅”移动到“完成”将问题关闭。
changes.state.from是open,changes.state_reason.from是null,因为该问题之前没有状态原因。
GitHub 还会发送此更改的 closed 投递。
{
"action": "status_changed",
"issue": {
"number": 1347,
"state": "closed",
"state_reason": "completed",
"status": {
"id": 5,
"name": "Done",
"category": "completed"
}
},
"status": {
"id": 5,
"name": "Done",
"category": "completed"
},
"changes": {
"status": {
"from": {
"id": 8,
"name": "In review",
"category": "started"
}
},
"state": {
"from": "open"
},
"state_reason": {
"from": null
}
}
}