Forge Home


A helper for writing tasks in ruby




30,880 latest version

4.8 quality score

Version information

  • 0.6.0 (latest)
  • 0.5.1
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.0
released Jan 21st 2021
This version is compatible with:
  • Puppet Enterprise 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.7.0 < 8.0.0
  • CentOS

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this declaration to your Puppetfile:

mod 'puppetlabs-ruby_task_helper', '0.6.0'
Learn more about managing modules with a Puppetfile

Add this module to a Bolt project:

bolt module add puppetlabs-ruby_task_helper
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-ruby_task_helper --version 0.6.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



puppetlabs/ruby_task_helper — version 0.6.0 Jan 21st 2021

Ruby Task Helper

A Ruby helper library for writing Puppet tasks. It provides a class that handles error generation, simplifies JSON input and output, and makes testing your task easier. It requires Bolt >= 1.1 or Puppet Enterprise >= 2019.0.

Table of Contents

  1. Description
  2. Requirements
  3. Setup
  4. Usage
  5. Debugging
  6. Testing


This library handles parsing JSON input, serializing the result as JSON output, and producing a formatted error message for errors.


This library works with Ruby 2.3 and later, though is tested using Ruby 2.4 and 2.5.


To use this library, include this module in a Puppetfile:

mod 'puppetlabs-ruby_task_helper'

Add it to your task metadata

  "files": ["ruby_task_helper/files/task_helper.rb"],
  "input_method": "stdin"


When writing your task include the library in your script, extend the TaskHelper module, and write the task() function. The task() function should accept its parameters as symbols, and should return a hash. The following is an example of a task that uses the library. All parameters will be symbolized including nested hash keys and hashes contained in arrays.


#!/usr/bin/env ruby

require_relative "../../ruby_task_helper/files/task_helper.rb"

class MyClass < TaskHelper
  def task(name: nil, **kwargs)
    {greeting: "Hi, my name is #{name}"}

if __FILE__ == $0

You can then run the task like any other Bolt task:

bolt task run mymodule::task -t name="Robert'); DROP TABLE Students;--"

You can additionally provide detailed errors by raising a TaskError, such as

class MyTask < TaskHelper
  def task(**kwargs)
    raise"my task error message",
                               "Additional details")


When writing your task, it can be helpful to write debugging statement to locate the source of any errors. The library includes a debug method that accepts arbitrary values and logs it as a debugging statement. If the task errors, the list of debugging statements will be included in the resulting TaskError.

The list of debugging statements can also be accessed from the task itself by calling the debug_statements method. This can be used to include the debugging statements in a TaskError that you explicitly raise.

Adding a debugging statement:

debug "Result of method call: #{result}

Adding the list of debugging statements to a TaskError:

raise"my task error message",
                            "debug" => debug_statements)


By implementing the task as a method and not executing the task as a script unless it is invoked directly it becomes much easier to write rspec tests for your task. Make sure the task helper repo is checked out next to your module so the relative requires work and you can write simple unit tests for the methods of your task.


require_relative '../tasks/mytask.rb'

describe 'MyTask' do
  let(:params) { { name: 'Lucy' } }
  let(:task) { }

  it 'runs my task' do
    expect(task.task(params)).to eq({greeting: 'Hi, my name is Lucy'})