act：GitHub Action 本地运行器

jetsung

act：GitHub Action 本地运行器

快速反馈 - 要是你想测试对 .github/workflows/ 文件（或者对嵌入的GitHub操作所做的任何修改）所做的变动，不必每次都提交或推送，用 act 就能在本地运行这些操作。其环境变量以及文件系统的设置，都和GitHub提供的一样。
本地任务运行程序 - 我很喜欢 make 这款工具。不过，我不喜欢做重复的事。有了 act，你就能用 .github/workflows/ 里定义的GitHub操作，来代替 Makefile 了！

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

jetsung

测试

以我自建的项目为例：https://github.com/idev-sig/file-downloader

基础镜像：https://github.com/catthehacker/docker_images/pkgs/container/ubuntu

将下面的内容保存至项目或用户根目录（~/）的 .actrc

-P ubuntu-24.04=ghcr.io/catthehacker/ubuntu:act-latest
-P ubuntu-24.04-arm=ghcr.io/catthehacker/ubuntu:act-latest

-P ubuntu-24.04=ghcr.io/catthehacker/ubuntu:rust-latest

event.json

测试 dev 分支的 .github/workflows/docker-dev.yml

{
  "ref": "refs/heads/dev",
  "before": "0000000000000000000000000000000000000000",
  "after": "1111111111111111111111111111111111111111",
  "event_name": "workflow_dispatch",
  "inputs": {
    "src-image": "idev-sig/file-downloader:latest",
    "dst-image": "ghcr.io/idev-sig/file-downloader:latest"
  },
  "repository": {
    "full_name": "idev-sig/file-downloader"
  },
  "pusher": {
    "name": "jetsung"
  },
  "head_commit": {
    "id": "1111111111111111111111111111111111111111",
    "message": "Test commit",
    "timestamp": "2025-07-31T12:00:00Z",
    "author": {
      "name": "test",
      "email": "test@gmail.com"
    }
  },
  "action": "created",
  "release": {
    "tag_name": "v0.0.99",
    "name": "v0.0.99",
    "draft": false,
    "prerelease": false
  }
}

.secrets 密钥

GITHUB_TOKEN=ghp_aaaaaaaaaaa

.env 环境变量（event.json 中设置的不起作用）

GITHUB_REPOSITORY=idev-sig/file-downloader

执行

act push -e event.json --secret-file .secrets --env-file .env

# 若不设置 .env 则
act push -e event.json --secret-file .secrets --env GITHUB_REPOSITORY=idev-sig/file-downloader

发布发行版，显示编译详情

act release -e event.json --verbose

配置 release.yml

on:
  release:
      types: [created]

配置 event.json

  "action": "created",
  "release": {
    "tag_name": "v0.0.1",
    "name": "v0.0.1",
    "draft": false,
    "prerelease": false
  }

常见问题

[build/build] ❗ ::error::Unable to get the ACTIONS_RUNTIME_TOKEN env variable

act 默认没有启动 artifact server，导致 ACTIONS_RUNTIME_TOKEN / ACTIONS_RUNTIME_URL 等内部变量是空的。解决办法如下：

--artifact-server-path ./.artifacts

调试时报错：ailed to read 'action.yml' from action './.github/actions/install-skopeo' with path '' of step: file does not exist

      - uses: ./.github/actions/install-skopeo

改为

      - name: Checkout
        uses: actions/checkout@v4
      - uses: ./.github/actions/install-skopeo

即，必须包含 actions/checkout@v4 模块

设置密钥时，值要用单引号括起来。如果值是 JSON 的，则需要转义。