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

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) 


241
242
243
 
# File 'lib/toys/ci/template.rb', line 241

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) 


218
219
220
 
# File 'lib/toys/ci/template.rb', line 218

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) 


188
189
190
 
# File 'lib/toys/ci/template.rb', line 188

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.



257
258
259
 
# File 'lib/toys/ci/template.rb', line 257

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.



172
173
174
 
# File 'lib/toys/ci/template.rb', line 172

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.



99
100
101
102
103
104
105
 
# File 'lib/toys/ci/template.rb', line 99

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.



157
158
159
160
161
162
163
 
# File 'lib/toys/ci/template.rb', line 157

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) 


231
232
233
 
# File 'lib/toys/ci/template.rb', line 231

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.



132
133
134
135
136
137
138
 
# File 'lib/toys/ci/template.rb', line 132

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) 


204
205
206
 
# File 'lib/toys/ci/template.rb', line 204

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.



67
68
69
70
71
72
73
 
# File 'lib/toys/ci/template.rb', line 67

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) 


272
273
274
 
# File 'lib/toys/ci/template.rb', line 272

def use_github_base_ref_flag=(value)
  @use_github_base_ref_flag = value
end