作业与矩阵

相关源文件

• pkg/common/executor.go
• pkg/common/executor_test.go
• pkg/model/workflow.go
• pkg/model/workflow_test.go
• pkg/runner/job_executor.go
• pkg/runner/job_executor_test.go
• pkg/runner/step_docker_test.go
• pkg/runner/step_run.go
• pkg/runner/step_run_test.go
• pkg/runner/testdata/action-cache-v2-fetch-failure-is-job-error/push.yml

本文档解释了 Act 如何处理 GitHub Actions 作业定义和矩阵配置。它涵盖了 Act 代码库中的作业结构、矩阵扩展和执行流程。有关作业中所含步骤的信息，请参阅步骤系统。

作业结构和模型

作业是 GitHub Actions 工作流的核心，包含步骤、容器配置和策略定义。在 Act 中，作业由工作流模型中的Job结构体表示。

来源：pkg/model/workflow.go174-191 pkg/model/workflow.go554-566

作业有几个关键组成部分：

1. 基本元数据：名称、步骤和环境变量
2. 容器配置：运行时环境设置
3. 执行策略：矩阵配置和故障处理选项
4. 条件执行：通过If表达式
5. 资源要求：通过runs-on属性

作业模型支持不同类型，通过Type()方法识别

来源：pkg/model/workflow.go500-552 pkg/model/workflow_test.go176-260

矩阵构建

矩阵构建允许使用不同的配置多次运行作业。Act 处理矩阵以生成具有不同输入参数组合的作业变体。

矩阵定义和扩展

矩阵在作业的strategy部分定义

来源：pkg/model/workflow.go380-479 pkg/model/workflow_test.go329-395

GetMatrixes()方法按照以下步骤处理矩阵扩展：

1. 从作业策略中提取矩阵值
2. 识别包含和排除条目
3. 计算所有维度值的笛卡尔积
4. 过滤掉与排除模式匹配的组合
5. 添加或合并包含组合
6. 返回最终的矩阵组合集

如果处理后矩阵为空，则返回一个空的矩阵条目，以确保作业至少运行一次。

矩阵配置选项

策略部分支持两个关键设置来控制矩阵执行：

1. fail-fast（默认值：true）：当设置为true时，如果任何矩阵作业失败，则取消所有正在进行的作业
2. max-parallel（默认值：4）：控制可并行运行的矩阵作业的最大数量

来源：pkg/model/workflow.go193-200 pkg/model/workflow.go214-241

作业执行

Act 中的作业执行涉及使用每个矩阵组合运行作业。jobExecutor负责作业的设置、运行和清理。

作业执行流程

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

作业执行器：

1. 如果作业使用矩阵策略，则显示矩阵信息
2. 初始化作业容器和环境
3. 评估环境变量，插值 GitHub 变量
4. 按顺序执行每个步骤（前置、主、后置阶段）
5. 处理清理和结果报告

矩阵作业结果处理

当作业具有矩阵时，需要特殊处理结果状态：

来源：pkg/runner/job_executor.go157-183

对于矩阵作业，Act 会保留矩阵组合之间的现有结果状态。这确保了如果任何矩阵作业失败，整个作业都会被标记为失败。

并行执行

矩阵作业可以并行运行以提高执行速度。max-parallel设置控制此行为，Act 使用并行执行器实现它。

并行执行模型

来源：pkg/common/executor.go94-132 pkg/common/executor_test.go77-114

并行执行系统：

1. 创建一个工作池，其大小受max-parallel限制
2. 将所有矩阵作业变体排队等待执行
3. 工作器从队列中取出作业并执行它们
4. 收集结果，并返回遇到的第一个错误
5. 如果fail-fast为 true，则在发生错误时取消其他作业

默认值和行为

Act 为矩阵执行设置了合理的默认值：

• fail-fast：如果未指定，默认值为true
• max-parallel：如果未指定，默认值为4
• 如果矩阵为空，仍然会执行一个带有空矩阵上下文的作业

来源：pkg/model/workflow.go214-241 pkg/model/workflow.go466-476

矩阵值访问

在作业执行期间，矩阵值可在上下文中访问，并可在表达式和命令中引用

来源：pkg/runner/job_executor.go28-34

矩阵值：

1. 作为matrix.<key>添加到作业的上下文中
2. 在每个作业开始时显示在日志中
3. 可用于表达式中的插值，例如${{ matrix.node-version }}
4. 在评估环境变量、条件和命令时使用

矩阵配置示例

以下是矩阵如何在工作流文件中定义以及 Act 如何处理它们的示例：

这将在 Act 中生成 5 个作业变体：

1. node-version: 12.x, os: windows
2. node-version: 14.x, os: windows
3. node-version: 10.x, os: ubuntu
4. node-version: 12.x, os: ubuntu
5. node-version: 14.x, os: ubuntu
6. node-version: 15.x, os: ubuntu, experimental: true

这些将根据max-parallel设置以最多 2 个并行运行。

来源：pkg/model/workflow_test.go329-395