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

nektos/act

菜单

日志记录与命令处理

相关源文件

目的与范围

本文档详细介绍了 act 项目中的日志记录和命令处理系统。这两个子系统协同工作，为用户提供结构化输出，并处理来自工作流步骤的特殊命令。日志记录系统负责格式化和显示作业及步骤的执行信息，而命令处理系统则负责解释和处理工作流命令，例如设置环境变量或输出。

来源： pkg/runner/logger.go1-4 pkg/runner/command.go1-4

系统概览

来源： pkg/runner/logger.go5-30 pkg/runner/command.go10-17

日志系统

日志记录系统基于 logrus 库构建，提供结构化日志记录，并对工作流执行中的作业和步骤具有上下文感知能力。

日志器上下文层级

来源： pkg/runner/logger.go72-142

关键组件

  1. 日志器工厂：为作业和步骤创建日志器，并提供适当的格式和上下文。

    • WithJobLogger：为特定作业创建日志器，包含作业ID、名称和矩阵值。
    • WithCompositeLogger：为组合操作创建日志器。
    • WithCompositeStepLogger：为组合操作扩展日志上下文，包含步骤信息。
    • withStepLogger：为单个步骤创建日志器，包含步骤ID、名称和阶段。

  2. 格式化器：格式化日志条目以供显示。

    • maskedFormatter：在日志输出中屏蔽敏感值。
    • jobLogFormatter：格式化作业日志，包含颜色（如果支持）和作业/步骤信息。

  3. 敏感信息屏蔽：防止敏感信息在日志中显示。

    • valueMasker：在日志消息中将敏感值替换为 ***。
    • 在上下文中维护要屏蔽的值列表。

来源： pkg/runner/logger.go45-168 pkg/runner/logger.go170-266

日志格式化

系统根据终端功能和配置以不同的方式格式化日志

  • 彩色输出：在终端中运行时，日志会根据作业着色，以区分不同作业的输出。
  • 纯文本输出：不在终端中时，使用基于文本的格式。
  • JSON格式：可选的JSON格式，用于结构化输出（由 JSONLogger 配置控制）。

格式还包括以下特殊前缀：

  • 模拟运行模式：*DRYRUN*
  • 调试消息：[DEBUG]
  • 原始输出：以分隔线格式化

来源： pkg/runner/logger.go179-266

命令处理系统

命令处理系统处理工作流执行期间步骤可以输出的特殊命令指令。这些命令使用GitHub Actions或Azure DevOps识别的特定语法。

命令语法

系统支持两种命令语法：

  1. GitHub Actions：::command [key=value]::argument
  2. Azure DevOps：##[command key=value]argument

示例

  • ::set-env name=PATH::$PATH:/new/path
  • ##[add-path]/new/path

来源： pkg/runner/command.go10-17

命令处理流程

来源： pkg/runner/command.go34-87

支持的命令

命令处理程序支持以下命令：

命令描述实现
set-env设置环境变量setEnv() 将值存储在 Env 和 GlobalEnv 映射中
set-output为步骤设置输出值setOutput() 将值存储在 StepResults[stepID].Outputs 中
add-path向 PATH 添加路径addPath() 将路径添加到 ExtraPath 切片中
add-mask添加要在日志中屏蔽的值添加到敏感信息屏蔽列表
debug记录调试消息以调试级别记录
warning记录警告以警告级别记录
error记录错误以错误级别记录
stop-commands暂时禁用命令处理设置 resumeCommand 令牌
save-state在步骤之间保存状态存储在 IntraActionState 中

来源： pkg/runner/command.go49-78 pkg/runner/command.go84-187

系统间的集成

日志记录和命令处理系统紧密集成：

  1. 敏感信息屏蔽：当 add-mask 命令被处理时，被屏蔽的值会被添加到日志系统将屏蔽的敏感信息列表中。

  2. 命令处理反馈：命令处理程序会记录其处理的命令信息，从而提供对所采取操作的可见性。

  3. 上下文共享：两个系统都使用相同的上下文来维护执行过程中的状态。

来源： pkg/runner/logger.go45-58 pkg/runner/command.go62-64

使用示例

设置命令和处理输出

当一个步骤输出命令指令时：

  1. 命令处理程序会检测到此指令，对其进行处理，并将 MY_VAR=some_value 添加到环境中。
  2. 日志系统会使用适当的样式格式化并显示此操作。
  3. 后续步骤可以从环境中访问 MY_VAR。

屏蔽敏感信息

当一个步骤需要屏蔽敏感信息时：

  1. 命令处理程序会处理此指令，并将“my-secret-token”添加到屏蔽列表中。
  2. 日志系统会在所有后续日志中，将“my-secret-token”的所有实例替换为“***”。
  3. 这可以防止敏感信息在日志输出中意外暴露。

来源： pkg/runner/command_test.go108-175

结论

日志记录和命令处理系统协同工作，为 act 工具的用户提供丰富、交互式的体验。日志系统确保输出可读且信息丰富，而命令处理系统则使工作流能够以符合 GitHub Actions 行为的方式与执行环境进行交互。