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

nektos/act

菜单

工作流模型

相关源文件

本文档解释了 act 如何表示和处理 GitHub Actions 工作流文件。工作流模型是核心数据结构，使 act 能够解析、规划和执行 GitHub Actions 工作流。有关工作流如何执行的信息，请参阅 执行引擎。

核心组件

工作流模型定义了几个关键结构，它们以分层方式表示 GitHub Actions 元素。

来源: pkg/model/workflow.go18-26 pkg/model/workflow.go174-190 pkg/model/workflow.go568-582 pkg/model/workflow.go193-227 pkg/model/workflow.go554-566

工作流结构

Workflow结构是 GitHub Actions 工作流文件的顶层表示。

主要属性

  • File：工作流文件的名称
  • Name：工作流的名称（来自 YAML 或默认为文件名）
  • RawOn：触发工作流的事件
  • Jobs：作业 ID 到作业定义的映射
  • Env：所有作业可用的环境变量
  • Defaults：所有作业和步骤的默认设置

关键方法

  • On()：返回触发此工作流的事件列表
  • WorkflowDispatchConfig()：返回手动工作流触发器的配置
  • WorkflowCallConfig()：返回可重用工作流的配置

来源: pkg/model/workflow.go18-26 pkg/model/workflow.go29-58 pkg/model/workflow.go95-171

作业 (Jobs)

Job结构代表工作流中的单个作业。作业是工作的主要单位。

主要属性

  • Name：作业的显示名称
  • Steps：要执行的步骤列表
  • RawNeeds：对其他作业的依赖关系
  • RawRunsOn：运行器要求
  • Strategy：矩阵策略配置
  • RawContainer：容器配置
  • Uses：用于可重用工作流作业
  • With：可重用工作流作业的输入参数

关键方法

  • Needs()：返回依赖作业列表
  • RunsOn()：返回运行器标签列表
  • Container()：返回容器规范
  • GetMatrixes()：返回用于执行的矩阵组合
  • Type()：返回作业类型（默认、可重用工作流）

来源: pkg/model/workflow.go174-190 pkg/model/workflow.go289-305 pkg/model/workflow.go308-330 pkg/model/workflow.go359-479 pkg/model/workflow.go529-552

步数

一个Step代表作业中的单个工作单元。

主要属性

  • ID：唯一标识符
  • Name：显示名称
  • Uses：Action 引用或容器镜像
  • Run：要执行的命令
  • Shell：要使用的 Shell 解释器
  • WorkingDirectory：将在其中执行的目录
  • Env：特定于步骤的环境变量
  • With：Action 的输入参数

关键方法

  • Environment()：返回环境变量
  • ShellCommand()：返回执行 Shell 的命令
  • Type()：返回步骤类型（run、uses-docker、uses-action）

来源: pkg/model/workflow.go568-582 pkg/model/workflow.go585-595 pkg/model/workflow.go614-642 pkg/model/workflow.go690-711

工作流执行计划

为了执行工作流，模型包含一个规划系统，该系统解析依赖关系并创建结构化的执行计划。

来源: pkg/model/planner.go16-22 pkg/model/planner.go24-38 pkg/model/planner.go200-271 pkg/model/planner.go303-341

规划流程

规划流程涉及多个步骤

  1. 从磁盘加载工作流文件
  2. 将它们解析为 Workflow 对象
  3. 根据事件或作业名称创建执行计划
  4. 解析作业依赖关系以创建阶段
  5. 在每个阶段内，将可以并行运行的作业分组

工作流规划由 WorkflowPlanner 接口处理，具有以下关键方法

  • PlanEvent(eventName)：为特定事件创建执行计划
  • PlanJob(jobName)：为特定作业创建执行计划
  • PlanAll()：创建一个包含所有作业的计划

来源： pkg/model/planner.go16-22 pkg/model/planner.go58-184 pkg/model/planner.go200-271

作业类型与矩阵策略

作业可以有不同的类型，也可以实现矩阵策略来运行多种配置。

作业类型

模型支持不同的作业类型

来源： pkg/model/workflow.go500-527 pkg/model/workflow.go529-552

作业类型包括

  • JobTypeDefault： 标准作业，包含步骤
  • JobTypeReusableWorkflowLocal： 引用本地可重用工作流的作业
  • JobTypeReusableWorkflowRemote： 引用远程可重用工作流的作业

矩阵策略

矩阵策略允许通过改变输入参数来运行具有多个配置的作业

矩阵执行涉及

  1. 解析 strategy.matrix 配置
  2. 计算所有矩阵选项的笛卡尔积
  3. 应用 exclude 规则来移除特定的组合
  4. 应用 include 规则来添加或覆盖组合
  5. 为每个生成的矩阵组合创建作业实例

来源： pkg/model/workflow.go376-479 pkg/model/workflow.go193-227

步骤类型和执行

作业中的步骤可以有不同的类型，并且它们的执行取决于这些类型。

来源： pkg/model/workflow.go644-688 pkg/model/workflow.go690-711

步骤类型包括

  • StepTypeRun： 直接运行命令的步骤
  • StepTypeUsesDockerURL： 使用 Docker 容器镜像的步骤
  • StepTypeUsesActionLocal： 使用本地操作的步骤
  • StepTypeUsesActionRemote： 使用远程 GitHub 操作的步骤
  • StepTypeReusableWorkflowLocal： 使用本地可重用工作流的步骤
  • StepTypeReusableWorkflowRemote： 使用远程可重用工作流的步骤

步骤执行

步骤的执行取决于其类型，并涉及

  1. 设置环境变量
  2. 准备工作目录
  3. 设置用于命令执行的 shell
  4. 对于 run 步骤
    • 创建包含命令内容的脚本文件
    • 使用适当的 shell 执行命令
  5. 对于 action 步骤
    • 获取 action（本地或远程）
    • 设置输入
    • 执行 action

来源： pkg/runner/step_run.go16-225

加载和解析工作流

该模型包含从磁盘读取工作流文件并将其解析到模型结构中的功能。

工作流文件使用 YAML 解析，并在转换为模型对象之前根据模式进行验证。

主要功能

  • ReadWorkflow(in io.Reader)： 从 reader 解析工作流
  • UnmarshalYAML(node *yaml.Node)： 处理 YAML 反序列化和模式验证

来源： pkg/model/workflow.go714-718 pkg/model/workflow.go71-81

工作流规划流程

在规划工作流执行时，act 会遵循以下流程

规划流程

  1. 从指定目录加载工作流文件
  2. 根据触发事件过滤它们
  3. 解析作业依赖关系以确定执行顺序
  4. 创建可以并行运行的作业阶段
  5. 构建完整的执行计划

来源： pkg/model/planner.go58-184 pkg/model/planner.go200-271 pkg/model/planner.go343-399

此执行计划随后将传递给执行引擎以运行工作流。