Syntax

Manifest file

gilbert.yaml it’s a yaml file that contains all information about your tasks and tells Gilbert what to do when you try to run specific task.

This file should be located at the root folder of your codebase, or at least at the same location where you call gilbert command.

To create a sample file, use gilbert init command.

Structure

gilbert.yaml consists of tasks, and tasks include a list of jobs to be done and rules.

Here is an annotated example of gilbert.yaml file.

version: 1.0
imports:
  - ./misc/mixins.yaml
vars:
  appVersion: 1.0.0
tasks:
  build:
  - description: Build project
    action: build
  clean:
  - if: file ./vendor
    description: Remove vendor files
    action: shell
    params:
      command: rm -rf ./vendor

Sections:

• version - file schema version
• imports - list of files to import. Imported files should share the same syntax as gilbert.yaml file.
• vars - list of global variables that available for all tasks and jobs
• mixins - mixins. See mixins for more info
• tasks - contains a list of tasks. Task can be called by gilbert run task_name

Variables

Gilbert allows to keep variables in the manifest file and use them in tasks and jobs.

There are 2 type of variables:

• Global - defined in vars section in root. Available everythere.
• Local - defined in specific job and visible only in scope of job.

Tip: variable values could be set or changed using command flags

Prefefined variables

By default, there are a few predefined variables in global scope:

• PROJECT - Path to the folder where gilbert.yaml is located.
• BUILD - Alias to ${PROJECT}/build, can be useful as default build output directory.
• GOPATH - Go path environment variable

String templates

All variable values and some other params can contain not only static value, but also template expression.
String template can contain a value of any variable ({{ var_name }}) or a value of some shell command ({% whoami %}) or both.

Example:

version: 1.0
vars:
    foo: “{% go version %} is installed on {{ GOROOT }}”
    

The value of variable foo will be:
go version go1.10.1 linux/amd64 is installed on /usr/local/go

Tasks

Each task is located in tasks section and contains from a sequence of jobs that should be ran when task was called.

Job definiton

Each job should, contains action to execure, variables and action arguments.
Here is a full example of task with a few jobs. Most of parameters are optional.

tasks:
    build_project:
    - action: build                     # name of action to perform, required!
      description: "build the project"  # step description, optional
      delay: 500                        # delay before step start in milliseconds, optional
      vars:
        commit: "{% git log --format=%H -n 1 %}"     # Variables for current step, optional
        foo: "bar"
      params:                                           # Arguments for action.
        variables:                                      # Those values are specific
            'main.version': "{{ commit }}"              # to each action.
            'main.stable': 'true'
    # Additional task:
    - if: 'uname -a'    # Condition for step run, contains a shell command, optional
      action: shell
      params:
        command: 'echo I am running on Unix machine'

Job fields

Param name	Type	Description
if	boolean	Contains conditional shell command. If command returns non-zero exit code, step will be skipped
description	string	Contains step description and makes your job run status more informative
action	string	Name of action to execute. See built-in actions for more info
mixin	string	Name of the mixin to be called. Cannot be together with action in the same job.
async	boolean	Run job asynchronously. Useful for executing programs like web-servers, etc.
delay	int	Delay before step start in milliseconds
deadline	int	Job execution deadline in milliseconds
vars	dict	List of local variables for the step, work the same as global vars section.
params	dict	Contains arguments for the action. See action docs for more info

- Required parameter
- Optional parameter but depends on action

Mixins

Mixin is a set of jobs that can be included into task and used to reduce boilerplate code in gilbert.yaml file.
Also, one of the biggest differences that most of values can contain template expressions.

Declaration

Each mixin should be declared in mixins section and have the same syntax as regular jobs in tasks section:

  version: 1.0
  mixins:
    hello-world:
      - action: shell
        params:
          command: 'echo "hello world"'
      - action: build

Calling a mixin

Mixins are called by tasks and use job variables as parameters.
The same mixin can be called several times with different parameters in the same job.

Example:

version: 1.0
mixins:
  platform-build:
  - action: build
    description: 'build for {{os}} {{arch}}'
      vars:
        extension: '' # variable default value
      params:
        outputPath: '{{buildDir}}/myproject_{{os}}-{{arch}}{{extension}}'
        target:
          os: '{{os}}'
          arch: '{{arch}}'
  - if: 'type md5sum'
    description: 'generate checksum for {{buildDir}}/myproject_{{os}}-{{arch}}{{extension}}'
    action: shell
    vars:
      fileName: 'myproject_{{os}}-{{arch}}{{extension}}'
    params:
      workDir: '{{buildDir}}'
      command: 'md5sum {{fileName}} > {{fileName}}.md5'

tasks:
  release:
  - mixin: platform-build
    vars:
      os: windows
      arch: amd64
      ext: .exe
  - mixin: platform-build
    if: '[ $(uname -s) == "Darwin" ]'
    vars:
      os: darwin
      arch: amd64

In example above, task release calls mixin platform-release and passes variables os, arch and ext to the mixin.

Advanced examples

You can find a good use-case example in this demo project.
That repo demonstrates usage of mixins and a few built-in actions for a real-world web-server example.