Process Syntax

Process files use YAML. You can find out about YAML here.

When you store process files in /.svnplace/processes/ in your repository they will be automatically found and activate.

Example

triggers:
    post_commit:
        changed:
            - -/tags/**
jobs:
    report-tag-deletion:
        steps:
            -
                name: Report the deletion
                bash: Echo {trigger.username} has deleted something in tags.

YAML

triggers:
    post-commit:
        changed:
            - +~/.svnplace/process/**
            - -/tags/**
jobs:
    my_job:
        after:
            - a_job_which_comes_first
            - another_job_which_needs_to_be_done_first
        shells:
            perl: perl -f {script}
        steps:
            -
                name: my_job's name
                condition: context.variable != ''
                ignoreerror: True
                workingdirectory: /home/process/{stage}
                timeout: 10*60
                bash: echo Hello
            -
                perl:
                    print "Hello World"

triggers:

post_commit:

Triggered by the post-commit hook.

changed[]:

optional - any change triggers

When the changed[]: is mnissing, post-commit always triggers the process.

triggers:
    post_commit:
    ...

When present, changed[]: is a list of path wildcards:

triggers:
    post_commit:
        changed:
            - +~/.svnplace/process/**
            - -/tags/**

The process will trigger when any change in a checkin which matches one of these.

Each path needs to start with one of more of +, - or ~:

+ added

- deleted

~ modified

The path itself wildmatches the same as .gitignore.

Examples:

  • +~/.svnplace/process/** anything in /.svnplace/process added or modified

  • -/tags/** anything in /tags deleted

results:

optional - results to record against the run

A dirctionary of strings:

results:
    compile_time: job.build.results.time
    objects: job.build.results.objects
    link_time: job.link.results.time
    exes: job.link.results.exes

The default place to store run results is Process Results/<run>/results/.... Each variable (single value/file or tree of files), is copied to the run's results. The key and the value both allow {...} substitutions.

If you want to change where results are stored, this is set in Settings->Processes.

jobs[name]:

A description of a job.

after[]:

optional - []

A list of jobs which must be successfully completed before this job starts.

shells[name]: str

optional

Any new shells or changes to existing shells you would like. The starting set is:

shells:
    bash: bash --noprofile --norc -eo pipefail {script}
    python: python {script}
    sh: sh -e {script}

role[]:

optional - the job's role

The role available to your scripts. See Role Descriptions later.

policies[]:

The names of any policies to apply

parameters:

optional - A string of json giving the parameters to the policies

parents[]:

optional - list of role ids.

By default the job's role has the user's default role as its parent and, using the listed policies, filter down what is alloweds. You can, instead, give a process your own list of parent roles and in this way your can be given enhanced permissions which the user running it would not normally be allowed. It's a bit like the 'S' bit on linux executables. The role owner needs to give permission for their role to be used by a process, and this is done in Settings->Processes.

runs_on{}:

optional - a dictionary of strings. This allows you to narrow down which runners can run your process. The values can have subsitutions.

runs_on:
    provider: svnplace
    platform: linux
    host_instance: {args.repo.primary_host}

If not given, provider=svnplace is the default. Your runners will have provider={user.name}

These settings match the runner's tags. As you can set your own runners' tags you can distribute jobs to them as you see fit.

Some tags, such as 'host_instance', are sensitive on svnplace hosts, and so your process will need permission to be able to use them.

steps[]:

An array of steps to complete the job.

name:

optional - the shell script

When reporting progress, this is what is reported.

condition: expr

optional - True

A Python expression which is checked before this step is run.

ignoreerror: expr

optional - False

A Python expression which is checked to see whether errors from this step should be ignored.

workingdirectory: str

optional - /home/process

What working directory to use.

timeout: expr

optional - 3600

The time allowed, in seconds for this step. This is a Python expression.

<shell>: str

The script to run at this step.

bash: echo Hello {username}

The text is transfered to a file, which is passed to the matching shell. Python substitutions are allowed.

role:

optional - the user's default role

The role available to this process. This defaults to the default role of the user triggering the process. For hook-triggered processes this is the repository's owner.

See Role Descriptions later.

results:

optional - results to record against the job

The default place to store job results is Process Results/<run>/job/<job>/.... Each variable, single value/file or tree of files, is copied to the job's results.

Role Descriptions

policies[]: str

The list of policies making up this role.

parameters:

optional

Any parameters to give to the role.

parents[]: str

optional

The list of parent policies to give to the role.