github_actions_toolkit 0.0.4

  • Readme
  • Changelog
  • Example
  • Installing
  • 69

github_actions_toolkit #

A third-party toolkit for GitHub Actions coded in Dart. It is inspired by the official Javascript actions/toolkit and contains similar commands.

Check out this "Hello World" Action for a complete example of a Dart GitHub Action.

Usage #

Logging #

Logging commands are available under log.

There are four levels:

  • error
  • warning
  • info
  • debug

Logs with info level will have no particular emphasis and be directly transmitted to stdout.

Logs with debug level will only appear if the secret ACTIONS_STEP_DEBUG has been created in the repository with the value true (see "Creating and using encrypted secrets").

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

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');

  // [isDebug] is true iff the secret `ACTIONS_STEP_DEBUG` has been configured
  final message = gaction.isDebug
      ? 'This is a debug message'
      : 'This is a debug message that you will not see';
  logger.debug(message);
}

Inputs #

Create an Input object for each input that your action needs, and retrieve their value with the value getter.

This getter will throw an ArgumentError if the input had been set as required and is missing.

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

main() async {
  const input = gaction.Input(
    'who-to-greet', // name defined in the YAML file
    isRequired: true,
  );

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

Outputs #

Set an output for subsequent steps with setOutput.

Subprocesses #

Execute a command in the shell with the exec function. It will return an ExecResult object once the command has terminated with its exit code and its outputs.

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

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}");
}

Features and bugs #

Please file feature requests and bugs at the issue tracker.

Changelog #

0.0.4 #

  • Rename workDir argument by workingDirectory for exec and execInParallel functions.
  • exec and execInParallel now return a ProcessResult.
  • exec and execInParallel don't block stdout and stderr StreamConsumers anymore.

0.0.3 #

  • The exec function can now be unawaited.
  • New function execInParallel.
  • More documentation.

0.0.2 #

  • Newly created environment variables and paths are accessible to the running action.
  • Incorrect workflow command parameters fixed.
  • New getters isDebug and getState.
  • New getters for the default environment under env.
  • setErrorMessage, setWarningMessage and setDebugMessage replaced by log.error, log.warning and log.debug
  • group, startGroup and endGroup moved under log.

0.0.1 #

  • Initial version, created by Stagehand

example/main.dart

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

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

extension on String {
  List<String> get lines {
    const ls = LineSplitter();
    return ls.convert(this);
  }
}

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!');
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  github_actions_toolkit: ^0.0.4

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:github_actions_toolkit/github_actions_toolkit.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
43
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
69
Learn more about scoring.

We analyzed this package on Jul 9, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.14

Analysis suggestions

Package not compatible with runtime flutter-web on web

Because:

  • package:github_actions_toolkit/github_actions_toolkit.dart that imports:
  • package:github_actions_toolkit/src/workflow_commands.dart that imports:
  • dart:io

Package not compatible with runtime js

Because:

  • package:github_actions_toolkit/github_actions_toolkit.dart that imports:
  • package:github_actions_toolkit/src/workflow_commands.dart that imports:
  • dart:io

Maintenance suggestions

Package is pre-v0.1 release. (-10 points)

While nothing is inherently wrong with versions of 0.0.*, it might mean that the author is still experimenting with the general direction of the API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
meta ^1.1.8 1.2.2 1.3.0-nullsafety
synchronized ^2.2.0 2.2.0+1
Dev dependencies
pedantic ^1.8.0