在jbranchaud/til项目中通过API调用触发工作流-优快云博客

在jbranchaud/til项目中通过API调用触发工作流

til :memo: Today I Learned 项目地址: https://gitcode.com/gh_mirrors/ti/til

在现代软件开发中，自动化工作流已成为提高效率的关键。本文将详细介绍如何在项目中通过API调用触发自动化工作流，这是一种灵活且强大的方式，可以实现远程控制工作流的执行。

工作流触发机制概述

自动化工作流通常由特定事件触发执行，例如代码推送或合并请求。但有时我们需要更灵活的控制方式，比如在特定时间或条件下手动触发工作流。这正是API触发机制的价值所在。

配置工作流接收API触发

要使工作流能够通过API触发，首先需要在工作流定义文件中添加workflow_dispatch事件触发器：

on:
  workflow_dispatch:

这个简单的配置就为工作流添加了API触发的能力。值得注意的是，这种配置方式不仅支持API触发，还会在自动化平台的用户界面中显示手动触发按钮，为开发者提供双重触发选择。

创建访问凭证

为了安全地通过API触发工作流，我们需要创建一个具有特定权限的访问凭证。这个凭证需要具备以下权限：

工作流调度权限
仅限于必要的仓库访问范围

创建凭证时应当遵循最小权限原则，只授予必要的权限以减少安全风险。

构建API请求

准备好凭证后，我们可以构建API请求来触发工作流。以下是使用cURL工具的示例：

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <你的凭证>" \
  -H "X-API-Version: 2022-11-28" \
  https://api.example.com/repos/项目所有者/仓库名称/actions/workflows/工作流ID/dispatches \
  -d '{"ref":"目标分支","inputs":{"参数1":"值1","参数2":"值2"}}'

请求中需要注意几个关键部分：

认证头：包含我们创建的访问凭证
端点URL：需要替换为实际的仓库信息和工作流标识
请求体：可以指定目标分支和输入参数

工作流标识的获取方式

工作流ID可以是工作流定义文件的文件名（如deploy.yml），也可以是工作流的数字ID。数字ID可以通过API查询获取，而文件名则更为直观易用。

传递输入参数

API触发的一个强大功能是可以向工作流传递输入参数。在工作流定义中，我们可以这样接收参数：

on:
  workflow_dispatch:
    inputs:
      name:
        description: '用户名'
        required: true
        type: string
      home:
        description: '所在地'
        required: false
        type: string

这些参数可以在工作流的后续步骤中使用，为工作流提供动态配置能力。