REST API 现在已版本化。 有关更多信息，请参阅“关于 API 版本控制”。

工作流的 REST API 端点

使用 REST API 与 GitHub Actions 中的工作流交互。

关于 GitHub Actions 中的工作流

您可以使用 REST API 查看 GitHub Actions 中仓库的工作流。工作流使用各种工具和服务来自动化您的软件开发生命周期。有关更多信息，请参阅 GitHub Actions 文档中的“关于工作流”。

列出仓库工作流

列出仓库中的工作流。

任何具有仓库读取权限的用户都可以使用此端点。

OAuth 应用令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点访问私有仓库。

“列出仓库工作流”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “Actions” 仓库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“列出仓库工作流”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必填

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必填

不带 .git 扩展名的仓库名称。名称不区分大小写。

查询参数
per_page 整数

每页结果数（最大 100）。有关更多信息，请参阅“在 REST API 中使用分页”。

默认值： 30

page 整数

要获取的结果的页码。有关更多信息，请参阅“在 REST API 中使用分页”。

默认值： 1

“列出仓库工作流”的 HTTP 响应状态代码

状态代码说明
200

OK

“列出仓库工作流”的代码示例

请求示例

get/repos/{owner}/{repo}/actions/workflows
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/actions/workflows

响应

状态：200
{ "total_count": 2, "workflows": [ { "id": 161335, "node_id": "MDg6V29ya2Zsb3cxNjEzMzU=", "name": "CI", "path": ".github/workflows/blank.yaml", "state": "active", "created_at": "2020-01-08T23:48:37.000-08:00", "updated_at": "2020-01-08T23:50:21.000-08:00", "url": "https://api.github.com/repos/octo-org/octo-repo/actions/workflows/161335", "html_url": "https://github.com/octo-org/octo-repo/blob/master/.github/workflows/161335", "badge_url": "https://github.com/octo-org/octo-repo/workflows/CI/badge.svg" }, { "id": 269289, "node_id": "MDE4OldvcmtmbG93IFNlY29uZGFyeTI2OTI4OQ==", "name": "Linter", "path": ".github/workflows/linter.yaml", "state": "active", "created_at": "2020-01-08T23:48:37.000-08:00", "updated_at": "2020-01-08T23:50:21.000-08:00", "url": "https://api.github.com/repos/octo-org/octo-repo/actions/workflows/269289", "html_url": "https://github.com/octo-org/octo-repo/blob/master/.github/workflows/269289", "badge_url": "https://github.com/octo-org/octo-repo/workflows/Linter/badge.svg" } ] }

获取工作流

获取特定工作流。您可以将 workflow_id 替换为工作流文件名。例如，您可以使用 main.yaml。

任何具有仓库读取权限的用户都可以使用此端点。

OAuth 应用令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点访问私有仓库。

“获取工作流”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “Actions” 仓库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“获取工作流”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必填

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必填

不带 .git 扩展名的仓库名称。名称不区分大小写。

workflow_id 必填

工作流的 ID。您也可以将工作流文件名作为字符串传递。

“获取工作流”的 HTTP 响应状态代码

状态代码说明
200

OK

“获取工作流”的代码示例

请求示例

get/repos/{owner}/{repo}/actions/workflows/{workflow_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID

响应

状态：200
{ "id": 161335, "node_id": "MDg6V29ya2Zsb3cxNjEzMzU=", "name": "CI", "path": ".github/workflows/blank.yaml", "state": "active", "created_at": "2020-01-08T23:48:37.000-08:00", "updated_at": "2020-01-08T23:50:21.000-08:00", "url": "https://api.github.com/repos/octo-org/octo-repo/actions/workflows/161335", "html_url": "https://github.com/octo-org/octo-repo/blob/master/.github/workflows/161335", "badge_url": "https://github.com/octo-org/octo-repo/workflows/CI/badge.svg" }

禁用工作流

禁用工作流并将工作流的 state 设置为 disabled_manually。您可以将 workflow_id 替换为工作流文件名。例如，您可以使用 main.yaml。

OAuth 令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点。

“禁用工作流”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “Actions” 仓库权限（写入）

“禁用工作流”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必填

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必填

不带 .git 扩展名的仓库名称。名称不区分大小写。

workflow_id 必填

工作流的 ID。您也可以将工作流文件名作为字符串传递。

“禁用工作流”的 HTTP 响应状态代码

状态代码说明
204

无内容

“禁用工作流”的代码示例

请求示例

put/repos/{owner}/{repo}/actions/workflows/{workflow_id}/disable
curl -L \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/disable

响应

状态：204

创建工作流调度事件

您可以使用此端点手动触发 GitHub Actions 工作流运行。您可以将 workflow_id 替换为工作流文件名。例如，您可以使用 main.yaml。

您必须将 GitHub Actions 工作流配置为在 workflow_dispatch webhook 事件发生时运行。inputs 在工作流文件中配置。有关如何在工作流文件中配置 workflow_dispatch 事件的更多信息，请参阅“触发工作流的事件”。

OAuth 令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点。

“创建工作流调度事件”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “Actions” 仓库权限（写入）

“创建工作流调度事件”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必填

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必填

不带 .git 扩展名的仓库名称。名称不区分大小写。

workflow_id 必填

工作流的 ID。您也可以将工作流文件名作为字符串传递。

主体参数
ref 字符串 必填

工作流的 Git 引用。引用可以是分支或标签名称。

inputs 对象

在工作流文件中配置的输入键和值。属性的最大数量为 10。省略 inputs 时，将使用工作流文件中配置的任何默认属性。

“创建工作流调度事件”的 HTTP 响应状态代码

状态代码说明
204

无内容

“创建工作流调度事件”的代码示例

请求示例

post/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \ -d '{"ref":"topic-branch","inputs":{"name":"Mona the Octocat","home":"San Francisco, CA"}}'

响应

状态：204

启用工作流

启用工作流并将工作流的 state 设置为 active。您可以将 workflow_id 替换为工作流文件名。例如，您可以使用 main.yaml。

OAuth 令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点。

“启用工作流”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “Actions” 仓库权限（写入）

“启用工作流”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必填

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必填

不带 .git 扩展名的仓库名称。名称不区分大小写。

workflow_id 必填

工作流的 ID。您也可以将工作流文件名作为字符串传递。

“启用工作流”的 HTTP 响应状态代码

状态代码说明
204

无内容

“启用工作流”的代码示例

请求示例

启用/repos/{owner}/{repo}/actions/workflows/{workflow_id}/enable
curl -L \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/enable

响应

状态：204

获取工作流使用情况

获取特定工作流在当前计费周期内使用的可计费分钟数。可计费分钟数仅适用于使用 GitHub 托管运行器的私有存储库中的工作流。每个 GitHub 托管运行器操作系统以毫秒为单位列出使用情况。任何作业重新运行也包含在使用情况中。使用情况不包括 macOS 和 Windows 运行器的乘数，也不会四舍五入到最接近的整分钟。有关更多信息，请参阅“管理 GitHub Actions 的计费”。

您可以将 workflow_id 替换为工作流文件名。例如，您可以使用 main.yaml。

任何具有仓库读取权限的用户都可以使用此端点。

OAuth 应用令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点访问私有仓库。

“获取工作流使用情况”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “Actions” 仓库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“获取工作流使用情况”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必填

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必填

不带 .git 扩展名的仓库名称。名称不区分大小写。

workflow_id 必填

工作流的 ID。您也可以将工作流文件名作为字符串传递。

“获取工作流使用情况”的 HTTP 响应状态代码

状态代码说明
200

OK

“获取工作流使用情况”的代码示例

请求示例

获取/repos/{owner}/{repo}/actions/workflows/{workflow_id}/timing
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/timing

响应

状态：200
{ "billable": { "UBUNTU": { "total_ms": 180000 }, "MACOS": { "total_ms": 240000 }, "WINDOWS": { "total_ms": 300000 } } }