This document is a reference for the Razorops YAML configuration keys that are used in the razorops.yml file.

tasks

The main objects of the configuration file are the tasks key. Each task has a name, so will sometimes be referred to as a "named task". Tasks will run sequentially in the order they are defined. tasks must have a name that is unique within the .razorops.yml file.

This section defines a list of steps that allow you to build, test and deploy your code. Steps are (by default) executed sequentially, in the order in which they are defined. If a step returns a non-zero exit code, the pipeline immediately aborts and returns a failure status.

TIP

Note: Tasks have a maximum runtime of 1 hour. If your jobs are timing out, consider running some of them in parallel.

Here is an example -

tasks:
    build-image:
        type: build
        ....
    unit-tests:
        type: docker
        ...
    deploy:
        type: deploy
        ...

Each job consists of the tasks's name as a key and a map as a value. A name should be unique within a current tasks list. Razorops has several inbuilt tasks that can be included in your workflow:

Type Description
build Will build and optionally push your Docker image
push Will push your Docker image to private/public registries
docker Run commands in a new container created from a Docker image
deploy Will deploy your service(s) to a cluster
restore Will restore build artificates
rebuild Will rebuild build artifacts from files/directories

Conditional Tasks

You can filter the execution of each task by using the when configuration in the YAML file. This can be done with an expression, as you can see in the following sample configuration:

tasks:
    build-image:
        type: build
        ...
        when: branch == 'master'

The expression has access to the workflow related context objects branch, tag, and event.

Build

Before deploying anything, you will most of the time want Razorops to build your Docker images. For this you need to use the build task, which is one of the inbuilt tasks.

The only mandatory parameter of build is the image you want to build:

tasks:
    build-image:
        type: build
        image: gcr.io/razorops/docs
        push: true
        tags: ["${CI_COMMIT_SHA}", "latest"]
        dockerfile: Dockerfile
        context: .
        args:
            - API_TOKEN=foobar

build task allows following parameters -

key Type Default Description
image * String The name of docker image to build
tags Array ["latest"] The list of tags for docker images
push Boolean false push the Docker image
args Array Docker build arguments (--build-args)
args-env Array Docker build arguments to be used from secrets configured in Dashboard
dockerfile String ./Dockerfile Path of dockerfile relative to root of your source repo
context String . Docker context (directory)
target String target stage in a multistage build (build will run until this stage)

TIP

Always think carefully before pushing your images to a public Docker repository. If you are using a private Git repository or your build contains secrets (e.g. Github token, database passwords) then you need to ensure that you use a private Docker repository. Docker Hub and Quay.io both offer private repositories as part of their subscription plans.

Freestyle

The Freestyle step is designed so you can execute a series of commands in a container. Select an image to start a container, then you can specify a working directory, and commands. If you do not specify a working directory or commands, the step runs the organic commands specified by the image. Razorops supports any valid image from any compatible Docker registry, including private registries.

tasks:
    unit-tests:
        image: ruby:2.6
        commands:
            - bundle install
            - bundle exec rspec
        environment:
            RACK_ENV: test

If the image does not exist, Razorops instructs Docker to pull it. If the image is private you will need to configure registry credentials in "Integration" tab.

You can additionally specify backing services using services key. Razorops will start those containers in background and setup networking between them. For example -

tasks:
    unit-tests:
        ...
        services:
            db:
                image: mysql:5.6
                environment:
                    - MYSQL_ROOT_HOST=%

It will start a container for mysql and your code can connect to the host db on standard port 3306.

docker (Freestyle) task supports following parameters:

Key Type Default Description
image * string Docker image (public or private)
commands array List of commands to execute
environment map environment variables to be injected in the container
services map tasks dependencies (subset of docker-compose service spec)
when string conditional expression

Push

Push a built image to a remote Docker registry with one or more tags. It supports standard Docker registries and ECR.

push task supports following parameters:

Key Type Default Description
image * string Docker image (public or private)
tags array Multiple tags under which to push the image
when string conditional expression

TIP

You can optionally push docker image with build task as well with push: true

Rebuild

Generates and stores a cache of a file or directory of files such as dependencies or source code in our object storage. Later jobs can restore this cache.

The cache for a specific key is immutable and cannot be changed once written.

Key Type Description
type * string Task type
key * string Unique identifier for the cache
paths * array List of folders or files to cache
when string Conditional expression

Here is an example -




 



tasks:
    save-npm:
        type: rebuild
        key: npm-cache-[[ checksum "package-lock.json" ]]
        paths:
            - node_modules

Restore

It restores a previously saved cache based on a key. Cache needs to have been saved first for this key using save_npm task.

Key Type Description
type * string Task type
key * string Unique identifier of cached artifact
when string Conditional expression

Here is an example -




 



tasks:
    restore-npm:
        type: restore
        keys: 
            - npm-cache-[[ checksum "package-lock.json" ]]
            - npm-cache-

We welcome suggested changes to this document.