• Config
  • Config file formats
• Global
  • Version
  • Runs
    • Run
      • Task
        • Depend
        • Step
          • clone
          • run
          • save_to_workspace
          • restore_workspace
          • save_cache
          • restore_cache
      • Runtime
        • Container
          • Volume
          • TmpFS Volume
  • Additional types
    • When
      • Example
    • Value
      • As a string
      • As a project variable
    • Docker Registry Auth
• Examples
  • yaml config
  • jsonnet config

Config

This is the reference of the agola config file format.

Config file formats

The accepted syntaxes are (checked in this order):

• jsonnet (.agola/config.jsonnet)
• yaml (.agola/config.yml)
• json (.agola/config.json)

The config file is quite simple with just some syntactic sugar for easier definitions of some task steps.

For basic configs you would prefer to use the yml syntax but for more complex configs we suggest to use the jsonnet syntax (see the examples).

Instead of adding some templating facilities to yaml that will always leave some open unsupported cases and add much more complexity we choosed to push the use of jsonnet .

jsonnet helps writing a parametrizable and easy to maintain config. See the below matrix build example.

Generating a config with jsonnet keeps the principle of reproducible runs since a jsonnet file will always produce the same output.

You’re also free to use you own way to generate the config file. Just commit the final result to git.

Global

Version

The config file version. Currently only v0.

Runs

Run

Task

Depend

It’s also available a short form for specifying a dependency (simpler when using yaml):

  depends:
    - task 01 # depends on task 01 with default condition on_success 
    - task 02: # depends on task 02 with conditions on_failure, on_skipped 
      - on_failure
      - on_skipped

Step

There are different types of steps:

• clone: clones and checkouts (to the right commit sha) code
• run: executes e command
• save_to_workspace: save in the run workspace the specified files/dirs
• restore_workspace: restores the run workspace in the specified dir
• save_cache: save some contents in a project cache key.
• restore_cache: restores contents from a project cache.

Every step can have a short form (simpler when using yaml) or a normal form:

• Short form:

   $stepname: $stepdefinition

Examples:

   run:
     name: "run step"
     command: "echo something"

• Normal form:

   type: $steptype
   $otherstep fields

Examples:

   type: run
   name: "run step"
   command: "echo something"

clone

• Short form:

clone:

clone clones and checkouts (to the right commit sha) code.

• Long form:

run

• Short form:

run: command

The command must be a one line command In this case the run step name will be the same of the command trimmed at the maximum name size.

• Long form:

save_to_workspace

content

restore_workspace

save_cache

content

restore_cache

Runtime

Container

Volume

Containers can mount one or more volumes (currently only tmpfs is supported).

Example of single volume with size limit:

  - image: image01
    volumes:
      - path: /mnt/tmpfs
        tmpfs:
          size: 1Gi

Example with two volumes, the former with a size limit and the latter without:

  - image: image01
    volumes:
      - path: /mnt/vol1
        tmpfs:
          size: 512Mi
      - path: /mnt/vol2
        tmpfs: {}

TmpFS Volume

Additional types

When

When represent a set of conditions to match

The value provided to branch/tag/ref can be different:

• A string
• A list of strings
• A map with keys include and exclude and values string or list of string (like above). In this way the branch/ref/tag must be included and not excluded

The provided strings can be a simple string (the value must match that string) or a regular expression (when enclosed in / or #)

Example

  runs:
    - name: run01
      tasks:
        - name: task01
          when:
            branch: master
            tag:
              - v1.0
              - /v1\..*/
            ref:
              include: master
              exclude: [ '#/refs/pull/.*#' , /refs/heads/branch01 ]

The task task01 will be executed only if:

• we are on a branch with value master
• we are on a tag with value v1.0 or that matches the regexp v1\..* (i.e v1.0, v1.2 but not v10 or v2)
• we are on a ref that match the regexp /refs/pull/.* or the value “/refs/heads/branch01`

Value

A value that can be defined as a string or from a project variable

As a string

password: yoursecretpassword

As a project variable

password:
  from_variable: yoursecretpassword

Docker Registry Auth

Examples

yaml config

version: v0
runs:
  - name: agola example go run
    tasks:
      - name: build go 1.12
        runtime:
          type: pod
          arch: amd64
          containers:
            - image: golang:1.12-stretch
        environment:
          GO111MODULE: "on"
        steps:
          - clone:
          - restore_cache:
              keys:
                - cache-sum-{{ md5sum "go.sum" }}
                - cache-date-
              ## golang image sets GOPATH to /go
              dest_dir: /go/pkg/mod/cache
          ## This will create a binary called `agola-example-go` under ./bin
          - run:
              name: build the program
              command: go build .
          ## Copy the built binary to the workspace
          - save_to_workspace:
              contents:
                - source_dir: .
                  dest_dir: /bin/
                  paths:
                    - agola-example-go
          - save_cache:
              key: cache-sum-{{ md5sum "go.sum" }}
              contents:
                - source_dir: /go/pkg/mod/cache
          - save_cache:
              key: cache-date-{{ year }}-{{ month }}-{{ day }}
              contents:
                - source_dir: /go/pkg/mod/cache
      - name: run
        ## This task will run the built binary in the parent task and leverages the workspace capabilities
        runtime:
          type: pod
          arch: amd64
          containers:
            - image: debian:stretch
        steps:
          - restore_workspace:
              dest_dir: .
          - run: ./bin/agola-example-go
        depends:
          - build go 1.12

jsonnet config

This is an example jsonnet config the creates a build matrix between go version and architecture.

It generates 4 “go build” with the different combinations.

local go_runtime(version, arch) = {
  type: 'pod',
  arch: arch,
  containers: [
    { image: 'golang:' + version + '-stretch' },
  ],
};
local task_build_go(version, arch) = {
  name: 'build go ' + version + ' ' + arch,
  runtime: go_runtime(version, arch),
  working_dir: '/go/src/github.com/sorintlab/agola',
  environment: {
    GO111MODULE: 'on',
  },
  steps: [
    { type: 'clone' },
    { type: 'restore_cache', keys: ['cache-sum-{{ md5sum "go.sum" }}', 'cache-date-'], dest_dir: '/go/pkg/mod/cache' },
    { type: 'run', name: 'build the program', command: 'go build .' },
    { type: 'save_to_workspace', contents: [{ source_dir: '.', dest_dir: '/bin/', paths: ['agola-example-go'] }] },
    { type: 'save_cache', key: 'cache-sum-{{ md5sum "go.sum" }}', contents: [{ source_dir: '/go/pkg/mod/cache' }] },
    { type: 'save_cache', key: 'cache-date-{{ year }}-{{ month }}-{{ day }}', contents: [{ source_dir: '/go/pkg/mod/cache' }] },
  ],
};
{
  runs: [
    {
      name: 'agola build/test',
      tasks: [
        task_build_go(version, arch)
        for version in ['1.11', '1.12']
        for arch in ['amd64', 'arm64']
      ] + [
        {
          name: 'run',
          runtime: {
            type: 'pod',
            arch: 'amd64',
            containers: [
              { image: 'debian:stretch' },
            ],
          },
          steps: [
            { type: 'restore_workspace', dest_dir: '.' },
            { type: 'run', command: './bin/agola-example-go' },
          ],
          depends: [
            'build go 1.12 amd64',
          ],
        },
      ],
    },
  ],
}