在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

nektos/act

菜单

Act 简介

相关源文件

Act 是一个命令行工具，使开发者能够在本地运行 GitHub Actions 工作流。本文档概述了 Act、其目的、核心功能以及它如何融入 GitHub Actions 生态系统。要更详细地了解 Act 的架构，请参阅架构概述。

Act 的目的

Act 解决了开发者在使用 GitHub Actions 时面临的两个主要挑战：

  1. 快速反馈周期：Act 允许开发者在本地测试工作流，而不是通过提交和推送更改来触发 GitHub Actions 工作流，从而显著加快了开发过程。

  2. 本地任务运行器：Act 可以作为一个本地任务运行器，让您能够利用现有的 GitHub Actions 工作流来替代传统的构建工具，如 Make。

该工具的座右铭“Think globally, act locally”（全局思考，本地行动）概括了其目的——使开发者无需离开本地环境即可构建和测试 GitHub Actions 工作流。

来源： README.md5-10

Act 的工作原理

Act 的核心是读取您的 GitHub Actions 工作流文件（.github/workflows/），并使用模拟 GitHub Actions 运行时环境的 Docker 容器执行它们。

当您运行 Act 时：

  1. 它从您的仓库读取工作流文件
  2. 它确定需要执行哪些操作
  3. 它使用 Docker 拉取或构建必要的容器镜像
  4. 它为每个操作创建并运行容器，并对其进行配置以匹配 GitHub 的环境
  5. 它捕获并显示与您在 GitHub 上看到的相似的输出

来源： README.md16-18 cmd/root.go387-704

关键组件

Act 由几个核心组件组成，它们协同工作以在本地执行工作流：

主要组件

  1. CLI 接口：用户入口点，通过 .actrc 等文件处理命令行参数和配置

  2. 运行器系统：协调工作流的执行并管理执行上下文

  3. 工作流规划器：解析工作流文件并创建执行计划

  4. 运行上下文：提供作业执行的上下文，包括环境变量、秘密和 GitHub 上下文

  5. Docker 集成：处理运行操作的容器操作

来源： cmd/root.go46-132 pkg/runner/runner.go16-255

配置和选项

Act 提供了丰富的配置选项以自定义其行为：

  • 事件选择：选择哪个事件触发工作流（例如，push、pull_request）
  • 作业选择：运行工作流中的特定作业
  • 环境变量：为操作设置自定义环境变量
  • 秘密管理：安全地向操作提供秘密
  • 平台配置：配置不同 GitHub 托管运行器平台要使用的 Docker 镜像
  • 制品和缓存管理：控制制品和缓存的处理方式

配置可以通过命令行标志、环境变量或配置文件（.actrc）指定。

来源： cmd/root.go68-130 cmd/input.go9-65

使用示例

Act 的基本用法很简单——在包含 GitHub Actions 工作流的仓库中运行 act 命令，将在本地执行这些工作流。默认情况下，如果未指定事件，Act 将模拟 push 事件。

对于更具体的用例：

  • 运行特定事件：act pull_request
  • 运行特定作业：act -j build
  • 使用特定秘密：act -s SECRET_NAME=value
  • 列出可用工作流：act -l

与 Docker 集成

Act 严重依赖 Docker 来创建类似于 GitHub 运行器的环境。它提供了以下选项：

  • 为不同平台指定自定义 Docker 镜像
  • 控制容器网络
  • 挂载卷或绑定本地目录
  • 配置容器权限和功能

Docker 镜像的选择基于工作流文件中的 runs-on 参数，Act 为常见平台提供了默认镜像。

来源： cmd/root.go76-96 pkg/runner/runner.go36-63

总结

Act 通过以下方式为 GitHub Actions 提供了强大的本地开发环境：

  • 实现在本地测试工作流而无需推送到 GitHub
  • 准确模拟 GitHub Actions 环境
  • 提供丰富的配置选项
  • 与 Docker 集成以进行容器化执行

该工具通过缩短反馈循环并允许开发者立即在其本地机器上测试更改，显著改善了 GitHub Actions 的开发体验。

来源： README.md5-22 pkg/runner/runner.go16-24