local-action-verification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Local Action Verification with act

使用act进行本地Action验证

You are setting up a repository so that Jules (or any agent) can run GitHub Actions workflows locally using act to verify code changes pass CI before pushing.

你正在搭建一个代码仓库，以便Jules（或任何Agent）能够使用act在本地运行GitHub Actions工作流，从而在推送代码前验证代码变更能否通过CI流程。

What You're Setting Up

搭建内容

Two scripts and an agents.md section that enable local CI verification:

install-act.sh — Installs
```
act
```
if missing (platform-aware, sudo fallback)
run-act.sh — Runs
```
act
```
in the background with log polling to avoid agent timeouts
AGENTS.md section — Instructions Jules reads to know how to use these scripts

两个脚本和AGENTS.md中的一个章节，用于实现本地CI验证：

install-act.sh — 当未安装
```
act
```
时自动安装（适配不同平台，支持sudo降级处理）
run-act.sh — 在后台运行
```
act
```
并轮询日志，避免Agent超时
AGENTS.md章节 — Jules需要阅读的使用说明，了解如何使用这些脚本

Setup Steps

搭建步骤

Step 1: Copy scripts to the repository

步骤1：将脚本复制到代码仓库

Copy the

scripts/

directory from this skill into the target repository at

scripts/act/

Target structure:
scripts/act/
├── install-act.sh
└── run-act.sh

Make sure the scripts are executable:

bash

chmod +x scripts/act/install-act.sh scripts/act/run-act.sh

将本技能中的

scripts/

目录复制到目标代码仓库的

scripts/act/

路径下：

目标结构：
scripts/act/
├── install-act.sh
└── run-act.sh

确保脚本具备可执行权限：

bash

chmod +x scripts/act/install-act.sh scripts/act/run-act.sh

Step 2: Add instructions to AGENTS.md

步骤2：向AGENTS.md添加说明

Append the following section to the repository's

AGENTS.md

file (create it if it doesn't exist). This is how Jules discovers the local verification capability:

markdown

undefined

将以下章节追加到仓库的

AGENTS.md

文件中（如果文件不存在则创建）。Jules会通过该内容了解本地验证功能：

markdown

undefined

Local CI Verification

本地CI验证

Before pushing code or opening a PR, verify changes pass CI locally using

act

在推送代码或创建PR前，使用

act

在本地验证变更能否通过CI流程。

Prerequisites

前置条件

Docker must be running
If
```
act
```
is not installed, run:
```
bash scripts/act/install-act.sh
```

Docker必须处于运行状态
如果未安装
```
act
```
，执行：
```
bash scripts/act/install-act.sh
```

How to Verify

验证步骤

Read
```
.github/workflows/
```
to find the CI workflow and identify the job ID

Run the verification script:

bash

bash scripts/act/run-act.sh "push -j <JOB_ID>"

With matrix:

bash scripts/act/run-act.sh "push -j <JOB_ID> --matrix <KEY>:<VALUE>"

If the run fails, read the log output, fix the code, and re-run

After verification, clean up:

bash

rm -f act_output.log
git checkout <any unintended file changes>

查看
```
.github/workflows/
```
目录找到CI工作流，并确定作业ID（JOB_ID）

运行验证脚本：

bash

bash scripts/act/run-act.sh "push -j <JOB_ID>"

针对矩阵作业：

bash scripts/act/run-act.sh "push -j <JOB_ID> --matrix <KEY>:<VALUE>"

如果运行失败，查看日志输出，修复代码后重新运行

验证完成后，清理环境：

bash

rm -f act_output.log
git checkout <任何意外的文件变更>

Configuration

配置项

Timeout:

ACT_TIMEOUT=900 bash scripts/act/run-act.sh "..."

(default: 600s)

Poll interval:

ACT_POLL=15 bash scripts/act/run-act.sh "..."

(default: 10s)

Custom image: pass
```
-P ubuntu-latest=node:20-bookworm
```
in the arguments for faster pulls

undefined

超时时间：

ACT_TIMEOUT=900 bash scripts/act/run-act.sh "..."

（默认：600秒）

轮询间隔：

ACT_POLL=15 bash scripts/act/run-act.sh "..."

（默认：10秒）

自定义镜像：在参数中传入
```
-P ubuntu-latest=node:20-bookworm
```
以加快拉取速度

undefined

Step 3: Update .gitignore

步骤3：更新.gitignore

Append these entries to

.gitignore

if they don't already exist:

undefined

如果以下条目尚未存在，将其追加到

.gitignore

中：

undefined

act artifacts

act生成的文件

act_output.log .secrets

undefined

act_output.log .secrets

undefined

Step 4: Print next steps for the user

步骤4：告知用户后续操作

Tell the user:

Docker must be installed and running on any machine (or Jules VM) where verification runs
```
act
```
will be auto-installed on first use via
```
scripts/act/install-act.sh
```
If workflows require secrets, create a
```
.secrets
```
file (KEY=VALUE format) — never commit it
Commit all generated files

告知用户：

任何运行验证的机器（或Jules虚拟机）都必须安装并运行Docker
首次使用时，
```
act
```
会通过
```
scripts/act/install-act.sh
```
自动安装
如果工作流需要密钥，创建
```
.secrets
```
文件（采用KEY=VALUE格式）—— 请勿提交该文件
提交所有生成的文件

Troubleshooting

故障排除

Docker not running:
```
act
```
requires Docker. Ensure the Docker daemon is started.
Image pull slow: First run downloads ~2GB+. Use
```
-P ubuntu-latest=node:20-bookworm
```
for faster pulls.
ARM64 issues: On Apple Silicon, add
```
--container-architecture linux/amd64
```
to act arguments.
Secrets required: Create a
```
.secrets
```
file and pass
```
--secret-file .secrets
```
in the act arguments.

Timeout: Increase with

ACT_TIMEOUT=1200 bash scripts/act/run-act.sh "..."

Docker未运行：
```
act
```
依赖Docker，请确保Docker守护进程已启动。
镜像拉取缓慢：首次运行会下载约2GB的内容。使用
```
-P ubuntu-latest=node:20-bookworm
```
可加快拉取速度。
ARM64架构问题：在Apple Silicon设备上，向act参数中添加
```
--container-architecture linux/amd64
```
。
需要密钥：创建
```
.secrets
```
文件，并在act参数中传入
```
--secret-file .secrets
```
。

超时问题：通过

ACT_TIMEOUT=1200 bash scripts/act/run-act.sh "..."

增加超时时间。

Resource References

资源参考

Troubleshooting Guide — Detailed solutions for common issues

故障排除指南 — 常见问题的详细解决方案