carbonnexus/act-images

act-images 镜像文档

镜像概述和主要用途

act-images 是基于 nektos/act 官方镜像（如 catthehacker 系列）构建的自定义 Docker 镜像，与 nektos/act 工具完全兼容。该镜像预安装了 yq（数据处理工具）和 gomplate（模板渲染工具），旨在帮助开发者在本地使用 nektos/act 运行 GitHub Actions 工作流时，无需在工作流中额外配置工具安装步骤，直接使用预配置环境，简化流程并提升执行效率。

核心功能和特性

兼容性

• 与 nektos/act 工具无缝兼容，支持使用 act 在本地模拟和执行 GitHub Actions 工作流。

预装工具

• yq：轻量级命令行工具，支持 YAML、JSON 等数据格式的查询、修改和转换（项目地址：https://github.com/mikefarah/yq%EF%BC%89%E3%80%82
• gomplate：模板渲染工具，支持整合 JSON、YAML、环境变量等数据源生成动态内容（项目地址：https://github.com/hairyhenderson/gomplate%EF%BC%89%E3%80%82

可靠基础

• 基于 nektos/act 官方维护的基础镜像构建，确保底层环境与官方标准一致，降低兼容性风险。

使用场景和适用范围

适用场景

• 使用 nektos/act 在本地调试或运行 GitHub Actions 工作流，且工作流中依赖 yq 或 gomplate 工具的场景。
• 需要简化工作流配置，减少工具安装步骤（如 apt install、brew install 等）的场景。
• 对工作流执行效率有要求，希望避免重复安装工具的场景。

适用人群

• 开发人员：本地调试 GitHub Actions 工作流时使用。
• CI/CD 工程师：优化工作流配置，提升本地测试效率。

使用方法和配置说明

前提条件

• 已安装 Docker 环境。
• 已安装 nektos/act 工具（安装指南：https://github.com/nektos/act#installation%EF%BC%89%E3%80%82

拉取镜像

从 GitHub 仓库拉取 act-images 镜像（具体标签需根据基础镜像版本选择，如对应 Ubuntu 版本）：

bash
docker pull ghcr.io/carbon-nexus/act-images:<镜像标签>
# 示例：拉取基于 ubuntu-latest 的镜像
docker pull ghcr.io/carbon-nexus/act-images:ubuntu-latest

注：完整镜像标签列表请参考 GitHub 仓库：https://github.com/carbon-nexus/act-images%E3%80%82

在 nektos/act 中使用

运行 act 时，通过 -P 参数指定使用 act-images 镜像作为工作流执行环境：

bash
# 基本用法：指定镜像运行工作流（以 ubuntu-latest 为例）
act -P ubuntu-latest=ghcr.io/carbon-nexus/act-images:ubuntu-latest

# 运行特定工作流文件
act -P ubuntu-latest=ghcr.io/carbon-nexus/act-images:ubuntu-latest -W .github/workflows/my-workflow.yml

# 传递环境变量并运行
act -P ubuntu-latest=ghcr.io/carbon-nexus/act-images:ubuntu-latest -e .env

验证工具安装

可通过以下命令验证镜像中工具是否正常工作：

bash
# 验证 yq 版本
docker run --rm ghcr.io/carbon-nexus/act-images:latest yq --version

# 验证 gomplate 版本
docker run --rm ghcr.io/carbon-nexus/act-images:latest gomplate --version

注意事项

• 镜像标签需与 nektos/act 官方镜像标签对应（如 ubuntu-20.04、ubuntu-22.04 等），确保与工作流中指定的 runs-on 环境匹配。
• 镜像更新频率与 nektos/act 官方基础镜像同步，建议定期拉取最新版本以获取工具更新和安全补丁。
• 详细使用示例和问题反馈请参考 GitHub 仓库：https://github.com/carbon-nexus/act-images%E3%80%82