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

nektos/act

菜单

执行引擎

相关源文件

执行引擎是 act 系统中的核心组件，负责协调 GitHub Actions 工作流的执行。它为运行作业和步骤、管理容器以及根据条件和依赖项控制执行流程提供了底层框架。

有关特定实现（如步骤或操作）的信息，请参阅 步骤系统 和 操作。有关更高级别的协调，请参阅 运行器系统。

核心执行模式

在 act 中，执行引擎基于函数组合模式构建，使用一个简单而强大的执行器接口，可以实现复杂的执行流程。

来源：pkg/common/executor.go29-84 pkg/common/executor.go93-132 pkg/common/executor.go140-241

执行器接口

执行引擎的基本构建块是 Executor 类型，它是一个接受上下文并返回错误的函数

这个简单的接口允许通过 Then、OnError 和 Finally 等组合子进行强大的组合，从而能够清晰简洁地表达复杂的执行流程。

来源：pkg/common/executor.go29-31

核心执行器类型

执行引擎为不同的执行模式提供了几种执行器工厂

  1. 管道执行器：按顺序执行一系列步骤，在第一个错误处中止
  2. 并行执行器：以可配置的并发限制并行执行多个步骤
  3. 条件执行器：根据条件执行不同的步骤
  4. 错误执行器：始终返回错误（用于失败情况）
  5. 字段执行器：在执行期间为日志记录器添加字段

来源：pkg/common/executor.go53-69 pkg/common/executor.go72-85 pkg/common/executor.go87-92 pkg/common/executor.go95-132 pkg/common/executor.go134-138

执行上下文

执行引擎通过 RunContext 结构体来维护状态，该结构体包含执行作业所需的所有信息。

来源：pkg/runner/run_context.go31-56 pkg/runner/run_context.go246-591 pkg/runner/run_context.go850-973

环境管理

RunContext 负责：

  1. 环境变量：管理作业和步骤的环境变量
  2. 容器配置：设置作业容器和服务容器
  3. GitHub 上下文：提供 GitHub 特定的上下文（存储库、事件等）
  4. 执行状态：跟踪步骤结果和作业状态

来源：pkg/runner/run_context.go78-90 pkg/runner/run_context.go246-591 pkg/runner/run_context.go850-973

容器管理

执行引擎可以在 Docker 容器中或直接在主机上运行作业

来源：pkg/runner/run_context.go655-670 pkg/runner/run_context.go178-245 pkg/runner/run_context.go246-429

作业执行

作业执行器协调作业中所有步骤的执行，负责预步骤、主步骤和后步骤。

来源：pkg/runner/job_executor.go22-155 pkg/runner/job_executor.go157-198

作业执行器实现

newJobExecutor 函数创建一个执行器，该执行器：

  1. 设置作业容器
  2. 执行作业中的所有步骤（预、主、后）
  3. 处理错误和取消
  4. 清理容器
  5. 设置作业结果

步骤按以下顺序执行

  1. 所有步骤的预步骤（按定义顺序）
  2. 主步骤（按定义顺序）
  3. 所有步骤的后步骤（按定义顺序的倒序）

来源：pkg/runner/job_executor.go22-155 pkg/runner/job_executor.go157-198

步骤执行流程

作业中的每个步骤最多经历三个执行阶段

来源：pkg/runner/job_executor.go80-102 pkg/runner/job_executor.go138-154

错误处理和流程控制

执行引擎提供了错误处理和控制执行流程的机制。

条件执行

作业和步骤可以使用 if 字段进行条件执行。执行引擎使用表达式评估器评估这些条件，并在条件评估为 false 时跳过步骤/作业。

来源：pkg/runner/run_context.go784-816

错误处理

执行引擎在多个级别处理错误

  1. 步骤级别：每个步骤都可以指定 continue-on-error 以防止作业失败
  2. 作业级别：作业失败会传播到工作流
  3. 执行器级别：OnError 和 Finally 等组合子提供了错误处理钩子

Finally 组合子确保即使执行失败也能执行清理操作，而 OnError 则允许进行特定的错误处理逻辑。

来源： pkg/common/executor.go159-195 pkg/common/executor.go225-234 pkg/runner/job_executor.go56-64

服务容器支持

执行引擎支持与作业容器一起运行服务容器，这对于作业所需的数据库、缓存或其他依赖项非常有用。

服务容器是

  1. 在作业容器之前启动
  2. 连接到与作业容器相同的网络
  3. 可以通过其服务名称访问
  4. 监控健康状态
  5. 作业完成后被清理

来源： pkg/runner/run_context.go103-106 pkg/runner/run_context.go285-304 pkg/runner/run_context.go553-618

矩阵执行

执行引擎支持矩阵执行，即作业根据参数矩阵以不同的配置运行多次。

对于每个矩阵值的组合

  1. 创建一个新的运行上下文，包含特定的矩阵值
  2. 使用这些值执行作业
  3. 聚合结果

来源： pkg/runner/runner_test.go765-790 pkg/runner/job_executor.go29-34 pkg/runner/run_context.go685-687

总结

act 中的执行引擎提供了一个灵活强大的框架来运行 GitHub Actions 工作流。它使用函数组合模式来清晰地表达复杂的执行流程，并处理容器、步骤和作业的生命周期。

此设计的关键优势包括

  1. 可组合性：简单的组件组合以表达复杂的行为
  2. 关注点分离：每个组件都有清晰、集中的职责
  3. 灵活性：支持不同的执行环境（Docker、主机）
  4. 错误处理：用于处理和从错误中恢复的强大机制

来源： pkg/common/executor.go29-31 pkg/runner/job_executor.go22-155 pkg/runner/run_context.go31-56