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.
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.
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.
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 of the task. Tasks that avoid this directive are not shown in the task list.
description: This task does some cool stuff
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
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-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-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
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/
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
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)
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.
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 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
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