前言

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 。

创建 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 结尾加入相应的请求指令即可。具体就不做赘述了,相信看到这里的小伙伴都应该已经了解该如何去做了。

尾巴

Star 方式简单易用,学习成本低,相当于直接给 GitHub Actions 增加了一个触发按钮,但对于大的项目仓库并不适用。 Webhook 方式灵活多变,可控性强,对于高阶用户来说是一个利器,甚至可以自己写一个触发脚本、网页或者浏览器插件来实现更高级的功能。而对于其它的触发方式,博主后续也将继续学习研究,带来 GitHub Actions 更多的玩法。


相关 TG 频道:GitHub Actions Channel

相关 TG 群组:GitHub Actions Group


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

参考资料

Setting up Webhooks for Github Actions

GitHub Actions Docs: External events: repository_dispatch

GitHub API Docs: Create a repository dispatch event