使用 Act 本地运行 GitHub Actions

简介

GitHub Actions 为仓库开发者提供了执行定制化 Job 的能力，开发者可以使用各种 Job 基于代码仓库运行测试、构建、发布等操作，实现 CI/CD 等工作流。

这些 Job 默认运行在 GitHub 提供的 runner 中，但是由于仓库众多，配置了 actions 的代码仓库未必能得到足够的资源 (runner) 来快速、高效的运行代码仓库的 Actions。

一个可行的方式是绑定自己的私有 runner 到代码仓库，这样每次执行 Job 时都会在自己的 runner 上，详情见 self-hosted runners^[1]。

另一个方案就是 act^[2], 可以在电脑上，在代码仓库目录下，直接本地运行 Actions 中的 Job。方便开发者快递本地迭代和测试，确认没问题了再更新到主仓库，减少主仓库执行 Actions 的次数。

act 安装

act 使用 go 语言开发，可以直接下载编译好的二进制文件，或者使用 go install 安装。

1. 下载二进制文件

进入 act 的 releases^[3] 页面找到最新版，笔者这里是 v0.2.63

选择对应平台的文件，笔者这里是 Mac M 芯片，选择act_Darwin_arm64.tar.gz, 下载解压后，移动到 PATH 目录即可。

1. go install 安装

首先下载代码仓库

git clone https://github.com/nektos/act.git

进入到 act 目录，运行 go install

$ go install
go: downloading github.com/spf13/cobra v1.8.1
go: downloading golang.org/x/term v0.21.0
go: downloading google.golang.org/protobuf v1.34.2
go: downloading github.com/docker/cli v26.1.4+incompatible
go: downloading golang.org/x/sys v0.21.0

go 会自动构建二进制文件，并把构建好的二进制文件放到 gopath 中，这时查看 act 版本：

$ act --version
act version 0.2.63

act 使用

1. 触发条件

# 运行 push 触发的 action
act push

# 运行 pull_request 触发的 action
act pull_request

1. 运行指定 Job

# -j, --job 后面跟 job id
act -j 'test'

1. 变量与机密内容

# 通过 --var 指定单个 var
act --var VARIABLE=somevalue
# 通过 --var-file 指定文件中的多个变量
act --var-file my.variables

# 通过 -s 指定单个保密值
act -s MY_SECRET=somevalue
# 通过 --secret-file 指定文件中的多个保密值
act --secret-file my.secrets

act runner

act 同样有 runner 的概念，支持在容器和宿主机两个平台作为 runner 运行 Actions Job。在容器中运行需要指定容器镜像，默认镜像是 catthehacker/ubuntu:act-latest。宿主机支持 Mac、Linux 和 Windows。需要注意，容器的指令集架构要和宿主机架构一致，如果宿主机是 Windows 系统 Intel amd64 架构，那么镜像也应该是 amd64 架构。

如果 act 默认提供的镜像不满足自己的需求，可以自己构建一个 runner 镜像，在运行 act 时通过 -P或者 --platform 指定镜像：

act -P ubuntu-latest=adolphlwq/act-runner-ubuntu:22.04

act 中的 runner 和 GitHub Runners 一致（表格来自 Standard GitHub-hosted runners for Public repositories^[4]）：

Virtual Machine	Processor (CPU)	Memory (RAM)	Storage (SSD)	Workflow label	Notes
Linux	4	16GB	14GB	ubuntu-latest, ubuntu-24.04 [Beta], ubuntu-22.04, ubuntu-20.04	The ubuntu-latest label currently uses the Ubuntu 22.04 runner image.
Windows	4	16GB	14GB	windows-latest, windows-2022, windows-2019	The windows-latest label currently uses the Windows 2022 runner image.
macOS	3	14GB	14GB	macos-12 or macos-11	The macos-11 label has been deprecated and will no longer be available after 28 June 2024.
macOS	4	14GB	14GB	macos-13	NA
macOS	3(M1)	7GB	14GB	macos-latest or macos-14	The macos-latest label currently uses the macOS 14 runner image.

**Workflow label **指定不同平台的 Runner，act 中通过 -P label=image 来指定不同平台使用什么容器镜像运行。如果没有镜像，则可以通过 -P label=self-hosted表示 act 直接在宿主机运行 Actions^[5]。

act -P ubuntu-latest=-self-hosted
act -P windows-latest=-self-hosted
act -P macos-latest=-self-hosted

act runner 的局限

act runner 不是万能的。首先表示 runner 的平台标签 (ubuntu-latest 等）要和宿主机的指令架构一致。比如在 M 芯片的 苹果机器上，是不能运行

# Apple M 芯片不能运行 amd 64 芯片镜像的
$ act -P ubuntu-latest=adolphlwq/act-runner-ubuntu:22.04
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠
INFO[0000] Start server on http://192.168.6.234:34567
[release/generate-windows-rocm] 🚧  Skipping unsupported platform -- Try running with `-P windows=...`
[release/build-linux-arm64    ] 🚧  Skipping unsupported platform -- Try running with `-P linux-arm64=...`
[release/build-darwin         ] 🚧  Skipping unsupported platform -- Try running with `-P macos-12=...`
[release/generate-windows-cpu ] 🚧  Skipping unsupported platform -- Try running with `-P windows=...`
[release/generate-windows-cuda] 🚧  Skipping unsupported platform -- Try running with `-P windows=...`
[release/build-linux-amd64    ] 🚧  Skipping unsupported platform -- Try running with `-P linux=...`

报错** Skipping unsupported platform**

上面的命令在 intel amd64 架构的 Apple 笔记本上是能正确运行的：

# Apple amd64 架构 芯片能运行 amd 64 芯片镜像
$ act -j 'test' pull_request
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock'
INFO[0000] Start server on http://192.168.6.199:34567
[test/test-1] 🚀  Start image=adolphlwq/act-runner-ubuntu:22.04
[test/test-3] 🚀  Start image=adolphlwq/act-runner-ubuntu:22.04
[test/test-2] 🚧  Skipping unsupported platform -- Try running with `-P macos-latest=...`
[test/test-1]   🐳  docker pull image=adolphlwq/act-runner-ubuntu:22.04 platform= username= forcePull=true
[test/test-3]   🐳  docker pull image=adolphlwq/act-runner-ubuntu:22.04 platform= username= forcePull=true
[test/test-1]   🐳  docker create image=adolphlwq/act-runner-ubuntu:22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[test/test-3]   🐳  docker create image=adolphlwq/act-runner-ubuntu:22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[test/test-1]   🐳  docker run image=adolphlwq/act-runner-ubuntu:22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[test/test-3]   🐳  docker run image=adolphlwq/act-runner-ubuntu:22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[test/test-1]   ☁  git clone 'https://github.com/actions/setup-go' # ref=v5
[test/test-3]   ☁  git clone 'https://github.com/actions/setup-go' # ref=v5
[test/test-1] Non-terminating error while running 'git clone': some refs were not updated
[test/test-1]   ☁  git clone 'https://github.com/actions/upload-artifact' # ref=v4
[test/test-3] Non-terminating error while running 'git clone': some refs were not updated
[test/test-3]   ☁  git clone 'https://github.com/actions/upload-artifact' # ref=v4
^C[test/test-1] Cleaning up container for job test
[test/test-1] 🏁  Job succeeded
[test/test-3] Cleaning up container for job test
[test/test-3] 🏁  Job succeeded
Error: context canceled

对于像 windows 和 mac 这样的平台，镜像不好运行，可以通过 -P windows-latest=-self-hosted和-P macos-latest=-self-hosted 直接在宿主机上运行。

act -P windows-latest=-self-hosted
act -P macos-latest=-self-hosted

.actrc 文件

act 命令的参数过多时，可以放到 .actrc 文件中，act 运行时，会自动寻找当前目录的 .actrc 文件，找到后会把其中的内容解析出来作为 act 的参数。

-P ubuntu-latest=adolphlwq/act-runner-ubuntu:22.04
-P linux=adolphlwq/act-runner-ubuntu:22.04
-P macos-12=-self-hosted
--artifact-server-path /tmp/artifacts

上面的 act 文件，等同于下面的命令：

act -P ubuntu-latest=adolphlwq/act-runner-ubuntu:22.04 -P linux=adolphlwq/act-runner-ubuntu:22.04 -P macos-12=-self-hosted --artifact-server-path /tmp/artifacts

参考资料

[1]

self-hosted runners: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners

[2]

act: https://github.com/nektos/act

[3]

releases: https://github.com/nektos/act/releases

[4]

Standard GitHub-hosted runners for Public repositories: https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories

[5]

act 直接在宿主机运行 Actions: https://nektosact.com/usage/runners.html