DOGFILE_SPEC.md

Dogfile Specification

NOTE: This document is a draft and will probably change in the future. Most of its content is still open to discussion.

Dog is the first tool that uses a Dogfile and is developed at the same time as the Dogfile specification itself.

File Format

Dogfiles are YAML files that describe the execution of automated tasks. The root object of a Dogfile is an array of map objects (we call them Tasks). This is an example of a Dogfile with two simple Tasks:

- task: hello
  description: Say Hello
  code: echo hello

- task: bye
  description: Say Good Bye
  code: echo bye

Multiple Dogfiles in the same directory are processed together as a single entity. Although the name dog.yml is recommended, any file with a name that starts with dog and ends with .yml or .yaml is a valid Dogfile as long as it follows this specification.

Task definition

The task map accepts the following directives. Please note that directives marked with an asterisk are not implemented in Dog yet and their definition and behaviour will possibly change in the future.

task

Name of the task. A string that may include lowercase characters (a-z), integers (0-9) and hyphens (-) but should not start or end with a hyphen.

- task: mytask

description

Description of the task. Tasks that avoid this directive are not shown in the task list.

  description: This task does some cool stuff

code

The code that will be executed.

  code: echo 'hello'

Multiline scripts are supported.

  code: |
    echo "This is the Dogfile in your current directory:"

    for dogfile in `ls -1 dog*yml`; do
      cat $dogfile
    done

runner

When this directive is not defined, the default runner is sh. Additional runners are supported if they are present in the system. The following example uses the Bash runner to print 'Hello World'.

- task: bash-loop
  description: For loop ion Bash
  runner: bash
  code: |
    # this code includes a bashism may fail in some
    # systems with a standard implementation of sh
    for ((i=0; i<3; i++)); do
      echo "$i"
    done

The following list of runners are supported:

• sh
• bash

pre

Pre-hooks execute other tasks before starting the current one.

  pre: test

Multiple consecutive tasks can be executed as pre-hooks. The tasks defined in the following array will be executed in order, one by one.

  pre:
    - get-dependencies
    - compile
    - package

post

Post-hooks are analog to pre-hooks but they are executed after current task finishes its execution.

  post: clean

Arrays are also accepted for multi task post-hooks.

  post:
    - compress
    - upload

workdir

Sets the working directory for the task. Relative paths are considered relative to the location of the Dogfile. The default workdir is the Dogfile location.

  workdir: ./app/

tags*

When listing tasks, the ones with the same tag will be shown together. This directive is optional but useful on projects including lots of tasks.

  tags: dev

Multiple tags are allowed.

  tags:
    - build
    - dev

env

Default values for environment variables can be provided in the Dogfile. They can be modified at execution time.

  env: ANIMAL=Dog

Arrays are also supported.

  env:
   - CITY=Barcelona
   - ANIMAL=Dog

When multiple methods are used to define the same environment variable, the precedence is as follows (with the last listed methods winning prioritization):

• Default value declared using the env directive
• Environment variable coming from the system
• Environment variable coming from a register (read below)

register

Registers store the output of tasks as environment variables so other tasks can get their value later if they are part of the same task-chain execution. Tasks storing their output in a register are silent and won't show any output when they run.

- task: get-dog-version
  code: dog --version | awk '{print $3}'
  register: DOG_VERSION

- task: print-dog-version
  description: Print Dog version
  pre: get-dog-version
  code: echo "I am running Dog $DOG_VERSION"

Dogfiles don't have global variables, use registers instead.

params*

Additional parameters can be provided to the task that will be executed. All parameters are required at runtime.

- task: who-am-i
  description: Print my location and who am I
  params:
    # Required parameter without default value
    - name: city

    # Parameter with default value
    - name: planet
      default: Earth

    # Parameter with an array of allowed choices
    - name: animal
      choices:
        - dog
        - cat
        - human

    # Parameter with regular expression validation
    - name: age
      regex: ^\d+$

  code: echo "Hello, I'm in the city of $1, planet $2. I am a $3 and I'm $4 years old"

The regex option and the choices option are mutually exclusive.

timeout*

Timeout specifies the maximum amount of seconds a task is allowed to spend running. Once that time is reached execution stops and an error is returned.

- task: example
  desctiption: This task can not run for more than 60 seconds
  timeout: 60 # always use seconds
  code: ./some-script.sh

Non standard directives*

Tools using Dogfiles and having special requirements can define their own directives. The only requirement for a non standard directive is that its name starts with x_. These directives are optional and can be safely ignored by other tools.

- task: clear-cache
  description: Clear the cache
  x_path: /task/clear-cache
  x_tls_required: true
  code: ./scripts/cache-clear.sh

(*) Not implemented yet