Flutter GitHub Actions 集成插件 github_actions_toolkit 的使用

github_actions_toolkit 是一个用于 GitHub Actions 的第三方工具包，用 Dart 编写。它受到官方 JavaScript 工具包 actions/toolkit 的启发，并包含类似的命令。

使用指南

日志记录（Logging）

日志命令在 log 下可用。有四个级别的日志：

• error
• warning
• info
• debug

info 级别的日志将直接输出到 stdout，而 debug 级别的日志只有在仓库中设置了名为 ACTIONS_STEP_DEBUG 的秘密且值为 true 时才会显示。

示例代码：

import 'package:github_actions_toolkit/github_actions_toolkit.dart' as gaction;

void main() async {
  const logger = gaction.log;
  
  logger
    ..info('This is just a message')
    ..warning('This is a warning message')
    ..error('This is an error message');

  final message = gaction.isDebug
      ? 'This is a debug message'
      : 'This is a debug message that you will not see';
  logger.debug(message);
}

输入（Inputs）

创建一个 Input 对象来处理每个需要的输入参数，并通过 value getter 获取其值。如果输入是必需的但未提供，则会抛出 ArgumentError。

示例代码：

import 'package:github_actions_toolkit/github_actions_toolkit.dart' as gaction;

void main() async {
  const input = gaction.Input(
    'who-to-greet', // 在 YAML 文件中定义的名字
    isRequired: true,
  );

  gaction.log.info('Hello ${input.value}!');
}

输出（Outputs）

可以使用 setOutput 方法设置输出供后续步骤使用。

子进程（Subprocesses）

使用 exec 函数执行命令行命令。一旦命令终止，它将返回一个包含退出代码和输出的 ExecResult 对象。

示例代码：

import 'package:github_actions_toolkit/github_actions_toolkit.dart' as gaction;

void main() async {
  final process = await gaction.exec('echo', ['Hello world']);

  gaction.log.info("The 'echo' command has terminated with code ${process.exitCode} and has printed ${process.stdout}");
}

完整示例 Demo

以下是一个完整的示例，展示了如何在 GitHub Actions 中使用 github_actions_toolkit：

import 'dart:convert';
import 'dart:io';

import 'package:github_actions_toolkit/github_actions_toolkit.dart' as gaction;

void main() async {
  exitCode = 0;

  // Logging
  const logger = gaction.log;
  logger
    ..info('This is just a message')
    ..warning('This is a warning message')
    ..error('This is an error message');
  if (gaction.isDebug) logger.debug('This is a debug message');

  // Inputs
  const inputWhoToGreet = gaction.Input(
    'who-to-greet',
    isRequired: false,
    canBeEmpty: true,
  );
  logger.info('Hello ${inputWhoToGreet.value ?? 'World'}!');

  // Outputs
  final time = DateTime.now().toString();
  gaction.setOutput('time', time);

  // Environment
  final eventPayload =
      jsonDecode(gaction.env.eventPayload!) as Map<String, dynamic>;
  if (eventPayload.containsKey('pull_request')) {
    logger.info('This pull request has been ${eventPayload['action']}');
  }

  // Subprocesses
  final analyzerResult = await (logger.group(
    'Executing dartanalyzer',
    () async => gaction.exec(
      'dartanalyzer',
      [gaction.env.workspace!.path, '--format', 'machine'],
    ),
  ));

  if (analyzerResult.exitCode != 0) {
    logger.error('Execution of dartanalyzer has failed');
    exit(analyzerResult.exitCode);
  }

  var errorCount = 0;
  for (final line in analyzerResult.stdout.lines) {
    if (line.split('|')[0] == 'ERROR') errorCount += 1;
  }
  if (errorCount > 0) logger.warning('$errorCount have been found!');
}