Class: Toys::CI::Template

Inherits:
Object
  • Object
show all
Includes:
Template
Defined in:
lib/toys/ci/template.rb

Overview

A template that can be used to implement a CI tool.

This template generates flags and implementation methods in the current tool to implement CI. In particular, it generates the run method itself. If you need more control over the CI tool's implementation, consider using Mixin which provides a lower-level interface.

To implement a CI tool using this template, simply expand the template and provide the necessary configuration, including specifying at least one CI task to run. The generated tool will use Mixin under the hood.

Examples:


# Define the "test" tool
expand :minitest, bundler: true

# Define the "rubocop" tool
expand :rubocop, bundler: true

# Define a "ci" tool that runs both the above, controlled by
# flags "--tests", "--rubocop", and/or "--all".
tool "ci" do
  # Activate the toys-ci gem and expand the template
  load_gem "toys-ci"
  expand Toys::CI::Template do |ci|
    ci.all_flag = true
    ci.tool_job("Tests", ["test"], flag: :tests)
    ci.tool_job("Rubocop", ["rubocop"], flag: :rubocop)
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Template

Create the CI template. This template provides no direct arguments. All configuration of this template should be done by calling methods on the template in the expand block.



49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/toys/ci/template.rb', line 49

def initialize
  @jobs = []
  @collections = []
  @all_flag = nil
  @only_flag = nil
  @jobs_disabled_by_default = nil
  @fail_fast_flag = nil
  @fail_fast_default = false
  @base_ref_flag = nil
  @use_github_base_ref_flag = nil
  @prerun = nil
end

Instance Attribute Details

#fail_fast_default=(value) ⇒ Object

Set the default value of fail-fast. You can also create flags that can override this value using #fail_fast_flag=. Default is false.

Parameters:

  • value (boolean) 


260
261
262
 
# File 'lib/toys/ci/template.rb', line 260

def fail_fast_default=(value)
  @fail_fast_default = value
end

#jobs_disabled_by_default=(value) ⇒ Object

If set to true, all jobs are disabled by default unless explicitly enabled by their individual flags.

This setting is mutually exclusive with #all_flag= and #only_flag=. If you set up one of those flags, the default enabling behavior is also set implicitly.

Parameters:

  • value (boolean) 


237
238
239
 
# File 'lib/toys/ci/template.rb', line 237

def jobs_disabled_by_default=(value)
  @jobs_disabled_by_default = value
end

Instance Method Details

#all_flag=(value) ⇒ Object

Create a flag that will enable all jobs. All jobs will otherwise be disabled by default. This setting is mutually exclusive with #only_flag= and #jobs_disabled_by_default=.

The value can either be the flag key as a symbol, true to use the default (which is :all), or false to disable such a flag. For example, passing true will define the flag --all which will set the context key :all.

Parameters:

  • value (Symbol, boolean) 


207
208
209
 
# File 'lib/toys/ci/template.rb', line 207

def all_flag=(value)
  @all_flag = value
end

#base_ref_flag=(value) ⇒ Object

Create a flag that can be used to specify the base ref for the change directly. This can be used to filter CI jobs based on what has changed.

A change base ref provided in this way will override any obtained from other means, such as from the GitHub environment using #use_github_base_ref_flag=.

Parameters:

  • value (Symbol, boolean) —

    If a symbol, it is used as the flag key for a flag that specifies the base ref. You can also pass true to use the default, :base_ref.



276
277
278
 
# File 'lib/toys/ci/template.rb', line 276

def base_ref_flag=(value)
  @base_ref_flag = value
end

#before_run(&block) ⇒ Object

Provide a block that will be run at the beginning of the CI job. The block will run in the tool execution context, with self set to the Toys::Context.

Parameters:

  • block (Proc) —

    The block to execute.



191
192
193
 
# File 'lib/toys/ci/template.rb', line 191

def before_run(&block)
  @prerun = block
end

#cmd_job(name, cmd, flag: nil, override_flags: nil, trigger_paths: nil, env: nil, chdir: nil) ⇒ Object

Add a job implemented by an external process.

Parameters:

  • name (String) —

    A user-visible name for the job. Required.

  • cmd (Array<String>) —

    The command to run. Required.

  • flag (Symbol) (defaults to: nil) —

    A flag key to control whether the job will run. If provided, it will be used to generate two flags that can be passed to the CI job. For example, passing :unit_tests will generate the flags --unit-tests and --no-unit-tests and set the context value :unit_tests. If not provided, no flag is generated and runnability will be determined by the "all" or "only" flag.

  • override_flags (String, Array<String>, nil) (defaults to: nil) —

    Generated flags to use instead of the ones implied by the :flag argument. These must be specified without the leading --, and will automatically have --[no-] prepended. Optional. If not specified or nil, the flags fall back to those implied by the :flag argument.

  • trigger_paths (Array<String>, String, nil) (defaults to: nil) —

    An array of file or directory paths, relative to the repo root, that must have changes in order to trigger the job. If not specified, the job is always triggered.

  • env (Hash{String=>String}) (defaults to: nil) —

    Environment variables to set during the run. Optional.

  • chdir (String) (defaults to: nil) —

    The working directory for the run. Optional.



118
119
120
121
122
123
124
 
# File 'lib/toys/ci/template.rb', line 118

def cmd_job(name, cmd, flag: nil, override_flags: nil, trigger_paths: nil, env: nil, chdir: nil)
  if override_flags && !flag
    raise ::Toys::ToolDefinitionError, "override_flags is meaningless without a flag"
  end
  @jobs << CmdJob.new(name, flag, Array(override_flags), trigger_paths, cmd, env, chdir)
  self
end

#collection(name, flag, job_flags, override_flags: nil) ⇒ Object

Define a collection of jobs that can be enabled/disabled as a group.

Parameters:

  • name (String) —

    A user-visible name for the collection. Required.

  • flag (Symbol) —

    A flag key to control the collection. Required. Used to define two flags that can be passed to the CI job. For example, passing :unit_tests will generate the flags --unit-tests and --no-unit-tests and set the context value :unit_tests.

  • override_flags (String, Array<String>, nil) (defaults to: nil) —

    Generated flags to use instead of the ones implied by the :flag argument. These must be specified without the leading --, and will automatically have --[no-] prepended. Optional. If not specified or nil, the flags fall back to those implied by the :flag argument.

  • job_flags (Array<Symbol>) —

    The individual job flags that will be controlled as a group by this collection. Must be nonempty.



176
177
178
179
180
181
182
 
# File 'lib/toys/ci/template.rb', line 176

def collection(name, flag, job_flags, override_flags: nil)
  if job_flags.empty?
    raise ::Toys::ToolDefinitionError, "You must provide at least one entry in job_flags"
  end
  @collections << Collection.new(name, flag, Array(override_flags), job_flags)
  self
end

#fail_fast_flag=(value) ⇒ Object

Create flags that will enable and disable fail-fast. The flag should be specified by symbol, and the actual flag will be set accordingly. You can also use the value true which will set the default :fail_fast. For example, passing true will define the flags --fail-fast and --no-fail-fast.

Parameters:

  • value (Symbol, boolean) 


250
251
252
 
# File 'lib/toys/ci/template.rb', line 250

def fail_fast_flag=(value)
  @fail_fast_flag = value
end

#job(name, flag: nil, override_flags: nil, trigger_paths: nil, &block) ⇒ Object

Add a job implemented by a block.

The block should perform a CI job and return a boolean indicating whether or not the job succeeded. It will execute in the tool execution context, with self set to the Toys::Context.

Parameters:

  • name (String) —

    A user-visible name for the job. Required.

  • block (Proc) —

    A block that runs this job. Required.

  • flag (Symbol, nil) (defaults to: nil) —

    A flag key to control whether the job will run. If provided, it will be used to generate two flags that can be passed to the CI job. For example, passing :unit_tests will generate the flags --unit-tests and --no-unit-tests and set the context value :unit_tests. If not provided, no flag is generated and runnability will be determined by the "all" or "only" flag.

  • override_flags (String, Array<String>, nil) (defaults to: nil) —

    Generated flags to use instead of the ones implied by the :flag argument. These must be specified without the leading --, and will automatically have --[no-] prepended. Optional. If not specified or nil, the flags fall back to those implied by the :flag argument.

  • trigger_paths (Array<String>, String, nil) (defaults to: nil) —

    An array of file or directory paths, relative to the repo root, that must have changes in order to trigger the job. If not specified, the job is always triggered.



151
152
153
154
155
156
157
 
# File 'lib/toys/ci/template.rb', line 151

def job(name, flag: nil, override_flags: nil, trigger_paths: nil, &block)
  if override_flags && !flag
    raise ::Toys::ToolDefinitionError, "override_flags is meaningless without a flag"
  end
  @jobs << BlockJob.new(name, flag, Array(override_flags), trigger_paths, block)
  self
end

#only_flag=(value) ⇒ Object

Create a flag that will disable all jobs. All jobs will otherwise be enabled by default. This setting is mutually exclusive with #all_flag= and #jobs_disabled_by_default=.

The value can either be the flag key as a symbol, true to use the default (which is :only), or false to disable such a flag. For example, passing true will define the flag --only which will set the context key :only.

Parameters:

  • value (Symbol, boolean) 


223
224
225
 
# File 'lib/toys/ci/template.rb', line 223

def only_flag=(value)
  @only_flag = value
end

#tool_job(name, tool, flag: nil, override_flags: nil, trigger_paths: nil, env: nil, chdir: nil) ⇒ Object

Add a job implemented by a tool call.

Parameters:

  • name (String) —

    A user-visible name for the job. Required.

  • tool (Array<String>) —

    The Toys tool to run. Required.

  • flag (Symbol) (defaults to: nil) —

    A flag key to control whether the job will run. If provided, it will be used to generate two flags that can be passed to the CI job. For example, passing :unit_tests will generate the flags --unit-tests and --no-unit-tests and set the context value :unit_tests. If not provided, no flag is generated and runnability will be determined by the "all" or "only" flag.

  • override_flags (String, Array<String>, nil) (defaults to: nil) —

    Generated flags to use instead of the ones implied by the :flag argument. These must be specified without the leading --, and will automatically have --[no-] prepended. Optional. If not specified or nil, the flags fall back to those implied by the :flag argument.

  • trigger_paths (Array<String>, String, nil) (defaults to: nil) —

    An array of file or directory paths, relative to the repo root, that must have changes in order to trigger the job. If not specified, the job is always triggered.

  • env (Hash{String=>String}) (defaults to: nil) —

    Environment variables to set during the run. Optional.

  • chdir (String) (defaults to: nil) —

    The working directory for the run. Optional.



86
87
88
89
90
91
92
 
# File 'lib/toys/ci/template.rb', line 86

def tool_job(name, tool, flag: nil, override_flags: nil, trigger_paths: nil, env: nil, chdir: nil)
  if override_flags && !flag
    raise ::Toys::ToolDefinitionError, "override_flags is meaningless without a flag"
  end
  @jobs << ToolJob.new(name, flag, Array(override_flags), trigger_paths, tool, env, chdir)
  self
end

#use_github_base_ref_flag=(value) ⇒ Object

Create a flag that enables obtaining the change base ref from the GitHub workflow environment. This can be used to filter CI jobs based on what has changed in a GitHub Actions workflow. The flag should be specified by symbol, and the actual flag will be set accordingly. You can also use the value true which will set the default :use_github_base_ref. For example, passing true will define the flags --use-github-base-ref and --no-use-github-base-ref.

Parameters:

  • value (Symbol, boolean) 


291
292
293
 
# File 'lib/toys/ci/template.rb', line 291

def use_github_base_ref_flag=(value)
  @use_github_base_ref_flag = value
end