前言

GitHub Actions 是 Microsoft 收购 GitHub 后推荐的一款 CI/CD 工具。早期可能是处于初级开发阶段,它的功能非常原生,甚至没有直接提供一个手动触发按钮。一般的触发方式为代码变动(pushpull_request),发布文件(release)或者定时(schedule)等,这些属于自动触发方式。如果我们需要在 GitHub 仓库没有任何变动的情况下手动触发就需要使用一些奇技淫巧。经历了漫长的功能迭代,官方最终正式带来了手动触发按钮功能,这也宣告了一个瞎折腾时代的结束,一个崭新的折腾时代开始。

Star

本博客早前的文章《使用 GitHub Actions 云编译 OpenWrt》中曾介绍过这种触发方式,点击仓库上的 Star 按钮即可触发 GitHub Actions 的工作流程。这是最容易实现的方式,只要 workflow 文件中存在如下字段:

on:
  watch:
    types: started

为了避免被其他人点击 Star 导致的不必要的麻烦,还需要在 workflow 文件中加上if: github.event.repository.owner.id == github.event.sender.id字段,这样只有仓库所有者,也就是你自己点 Star 才有效。

jobs:
  build:
    runs-on: ubuntu-latest
    if: github.event.repository.owner.id == github.event.sender.id

点击 Star 触发方式的 workflow 文件示例:

name: Test

on:
  watch:
    types: started

jobs:
  build:
    runs-on: ubuntu-latest
    if: github.event.repository.owner.id == github.event.sender.id

    steps:
       - name: Checkout
         uses: actions/checkout@v2
# ...

虽然其他人点击不再会触发,但是在 Actions 页面还是会出现一个记录,所以这种手动触发方式并不完美。对于比较大的项目仓库使用可能会因为 Star 太多导致产生很多无意义的 Actions 记录从而影响正常查看 Actions 记录,所以这种方式只适合私有仓库、公开的测试仓库或者不起眼的小项目仓库。

Webhook

给 GitHub API 发送一个repository dispatch event(仓库调度事件)请求,当 API 接收到请求后就会触发相应的 workflow 。Webhook 方式灵活多变,可控性强,对于高阶用户来说是一个利器,甚至可以自己写一个触发脚本、网页或者浏览器插件来实现更高级的功能。

创建 token

首先需要创建 Personal access token,权限为repo即可。如果你不知道怎么做,可以查看官方文档中的相关介绍。token 会用在 webhook 的请求标头中,用于身份验证。

编写 Workflow 文件

在 workflow 文件中设置repository_dispatch触发事件,以便 GitHub Actions 能接收这个触发事件,这是一个最简单的 Workflow 文件示例:

on: repository_dispatch

jobs:
  run:
    runs-on: ubuntu-latest

    steps:
    - name: Hello World
      run: |
        echo My name is P3TERX.
        echo Hello World!

发送请求

通过 webhook 来触发 GitHub Actions,以下是一个使用 cURL 发送请求的例子:

curl -X POST https://api.github.com/repos/:owner/:repo/dispatches \
    -H "Accept: application/vnd.github.everest-preview+json" \
    -H "Authorization: token ACTIONS_TRIGGER_TOKEN" \
    --data '{"event_type": "TRIGGER_KEYWORDS"}'

需要要替换的值:

  • :owner - 用户名
  • :repo - 需要触发的 Github Action 所在的仓库名称
  • ACTIONS_TRIGGER_TOKEN - 带有 repo 权限的 Personal access token
  • TRIGGER_KEYWORDS - 自定义 Webhook 事件名称,可以为任意值,Actions 列表中会显示此名称,更多信息请参见下文。

进阶使用

在 webhook 请求中需要发送一个event_type属性的 json 有效负载,前面例子中的TRIGGER_KEYWORDS就是所发送的有效负载,官方将它称之为“自定义 Webhook 事件名称”,为了方便理解下文将它称之为“触发关键词”。因为没有做任何限制设置,所以可以为任意值,这是最基础的使用方式。有时一个仓库可能不止一个 workflow ,所以我们就可能需要对触发关键词进行限制,使用不同的关键词来触发不同的 workflow 。

设置repository_dispatch下的types字段的值可以限制触发关键词,下面的例子将设置helloworld这个触发关键词,只有当请求中的关键词为helloworld才会触发。

on:
  repository_dispatch:
    types: helloworld

还可以给每一个步骤设置运行条件,在运行条件中github.event.action等于触发关键词,通过判断给定的值是否与github.event.action相同来判断该步骤是否需要执行。比如下面例子中只有当触发关键词为helloworld时才会执行这个步骤。

    steps:
    - name: Hello World
      if: github.event.action == 'helloworld'
      run: |
        echo My name is P3TERX.
        echo Hello World!

通过判断github.event.action是否包含给定的值来判断该步骤是否需要执行。比如下面例子中当关键词包含hello这个步骤就会执行。

    steps:
    - name: Hello World
      if: contains(github.event.action, 'hello')
      run: |
        echo My name is P3TERX.
        echo Hello World!

触发关键词也可以是多个,比如像下面这个例子。当触发关键词为helloworld时,只有Hello World步骤会运行;当触发关键词为test时,只有TEST步骤会运行;当触发关键词为none时,虽然 Actions 会触发,但没有步骤运行。而发送其他关键词并不会触发这个 workflow 。

name: Webhook Test

on: 
  repository_dispatch:
    types: [helloworld, test, none]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Hello World
      if: contains(github.event.action, 'hello')
      run: |
        echo My name is P3TERX.
        echo Hello World!

    - name: TEST
      if: github.event.action == 'test'
      run: |
        echo test

甚至还可以在一个 workflow 完成后调用另一个 workflow ,只需要在 workflow 结尾加入相应的请求指令即可。具体就不做赘述了,相信看到这里的小伙伴都应该已经了解该如何去做了。

手动触发按钮

在时隔多年后 GitHub Actions 终于引入了一个手动触发的按钮,不过默认是不开启的,需要在 workflow 文件中设置workflow_dispatch触发事件。一个最简单的例子:

on: 
  workflow_dispatch:

设置好触发事件后就能在相关 workflow 的页面下看到Run workflow按钮.

更复杂一点还可以实现在手动触发时填写参数,控制不同的工作流程或者直接改写某个环境变量等操作。目前官方文档已经相当完善,所以博主就不赘述了,感兴趣的小伙伴可以去参考官方文档中的相关章节

尾巴

从最初的只能选择 Star ,到后来深入了解研究了 webhook 触发方式自己写脚本、网页去触发,GitHub Actions 促使我学习了很多新的东西。如果当初 GitHub 直接给了一个触发按钮,也许就不会去折腾了,也少了很多乐趣。这是 GitHub Actions 的进化史,也是我自己的进化史。


相关 TG 群组:GitHub Actions Group

相关 TG 频道:GitHub Actions Channel


本博客已开设 Telegram 频道,欢迎小伙伴们订阅关注。

参考资料

Setting up Webhooks for Github Actions

GitHub Actions Docs: External events: repository_dispatch

GitHub API Docs: Create a repository dispatch event

GitHub Actions: Manual triggers with workflow_dispatch