Process Syntax

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

Processes would usually be stored in a repository's /.svnplace/processes directory. They can be stored elsewhere, but their triggers won't operate - these processes can only be run by starting them using the API or the user interface.

name:

run_title:

triggers:
    start_commit:
    pre_commit:
    post_commit:
    pre_revprop_change:
    post_revprop_change:
    pre_lock:
    post_lock:
    pre_unlock:
    post_unlock:
    time:

args:
argtests:

role:

jobs:
    jobname:
        steps:

results:

name:

optional What the process is called - used in the user interface for selecting a process.

run_title:

optional The title for each run of a process.

triggers:

optional Events which will start the process. Any process can be started using the API, the user interface or by calling them from another process.

args:

optional Values which must be set to start this process.

argtests:

optional A list of tests (python expressions) to check the args are correct.

role:

The permissions given to code running in this process.

jobs:

The code to run. Each job is list of code pieces to run, in order, on a process runner. Different jobs can run at the same time, on the same, or different runners. A process's run finishes once its last job has finished. A job can generate values (files) which will be available to later jobs and as results for the whole process.

results:

optional Values (files) generated by the jobs collated to be the result/output of the process.

name:

optional The name of the process. This is used for choosing a process to run in the user interface, and as the default title for each run of the process.

run_title:

optional The title for each run of the process. This string can have {expression} substitutions. The values which can be used are explained in the values section.

triggers:

optional Which events which trigger this process to be run. To triggers work, your process must be stored in /.svnplace/processes.

triggers:
    start_commit:
    pre_commit:
    post_commit:
    pre_revprop_change:
    post_revprop_change:
    pre_lock:
    post_lock:
    pre_unlock:
    post_unlock:
    time:

These can be given no parameters:

triggers:
    post_commit:

when all of those events will trigger the process. Some triggers, eg time:, have to be given a parameter.

There is a brief style, where one of the event's parameters is given:

triggers:
    post_commit:
        - ~/trunk/index.md

Or they can be given fully:

triggers:
    poat_commit:
        changed:
            - ~/trunk/index.md
        args:
            notify: 'joebloggs'

The details of each type of event are given in the triggers document.

args:

optional Values which are required by the process.

args:
    an_argument:
        name:
        label:
        input_type:
        python_type:
        placeholder:
        tests:
        meta:
    another_argument:
        ...

name:

optional The value's name to use in expressions. The default is to use the argument's key.

label:

optional The input label for this argument when starting the process using the user interface.

input_type:

optional What user interface to present. Options are: checkbox, color, date, email, month, number, password, text default.

python_type:

optional What python type the value should be. Options are: str default, int, float, bool, yaml.

placeholder:

optional What placeholder to show in the start-a-process user interface.

tests:

optional A lists of python expressions, of which must be True to accept the argument. The value value is the argument being tested. Also available are the run values, process, user and repo.

meta:

optional Additional information for the user interface for this field.

Arg meta: kinds

args:
    an_argument:
        meta:
            kind: select
            options:
                -
                    value: The value
                    label: The label for the value
                -
                    value: ...

argtests:

optional A list of tests which must all be True.

argtests:
    -
        check: len(an_argument)>len(another_argument)
        message: an_argument must be longer than another_argument
    -
        check: ...

When a check is not True, the message is used to explain to the user why.

role:

optional the role for all jobs in thie process. This limits what the jobs are allowed to do.

role
    parents:
        - role URN or ID
        - ...
    policies:
        - policy URN or ID
        - ...
    parameters:
        value: expression
        nextvalue: ...

parents:

optional The roles to start from to build this role. If left out, the user's default role is used.

policies:

optional the list of policies to filter down the parents:'s capabilites.

parameters:

optional Any parameters to give to the policies

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 process 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.

jobs:

jobs:
    <jobid>:
        after:
        runs_on:
        role:
        shells:
        mapped_repo:
        steps:
            -
                name:
                condition:
                ignoreerror:
                workingdirectory:
                timeout:
                <shell>:
        results:

jobs.<jobid>

The identifier of this job.

jobs.<jobid>.after:

optional The list of jobs which must finish before this job will start. If this job wants to use the results of another job, you must use after: to ensure that other job is finished first.

jobs.<jobid>.runs_on:

optional The set of tags to identify the runners this job is allowed to run on. By default processes will run on svnplace-hosted runners. You can set your own tags on your oen runners so you can distribute jobs to them as you see fit.

Standard keys for runs_on::

jobs:
    <jobid>:
        runs_on:
            host: svnplace
            platform: linux
            region: eu-west
            host_instance: {repo.primary_host}

jobs.<jobid>.runs_on.host:

The username of the user who ran the runner. provider=svnplace is the default. Your runners will have provider={user.username}

jobs.<jobid>.runs_on.platform:

What kind of machine the runner is running on, eg linux, darwin.

jobs.<jobid>.runs_on.region:

For svnplace runners, this is the AWS region the runner is running on

jobs.<jobid>.runs_on.host_instance:

For svnplace runners, which AWS host is running the runner

Some tags, such as host_instance, are only allowed for svnplace. If you need permission for your process to give these, you will need to contact svnplace to create a role for your process to allow them.

jobs.<jobid>.role:

optional - the job's role. The default is the process's role. The parameters are the same as the process's role.

jobs.<jobid>.shells[name]: str

optional Any new shells or changes to existing shells you would like.

The default set of shells is:

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

{script} is the file name of the script.

jobs.<jobid>.mapped_repo:

optional The URN or API id of a repo which should be mapped in to the job's file system. {} substitutions are allowed. Only svnplace is allowed this, your process would need an svnplace-originated role to be donated to use as a role parent. This is here to support fundamental, site-foundational features like backup & restore. If you find you are unable to do something without it, talk to svnplace - it is more likely the API and/or site will be extended to allow what you need than for this capability to be dontated to your process.

jobs.<jobid>.steps:

An array of steps - the code fragments which will executed.

jobs.<jobid>.steps[].name:

optional When reporting progress, this is what is reported.

jobs.<jobid>.steps[].condition:

optional A Python expression which is checked before this step is run. If True, the step script is run, otherwise the step is skipped.

jobs.<jobid>.steps[].ignoreerror:

optional A python expression which, when True, means script errors are ignored.

jobs.<jobid>.steps[].workingdirectory: optional The working directory when the script is run, default /home/process. {} substitutions are allowed.

jobs.<jobid>.steps[].timeout:

optional A python expression of the number of seconds this script is allowed to execute for. The default, and limit, is 3600.

jobs.<jobid>.script[].<shell>:

The script to run at this step.

Here is an example:

jobs:
    somename:
        steps:
            -
                bash: echo Hello {username}
            -
                python: |
                    print('Hello')
                    print('world')

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

jobs.<jobid>.script[].results:

optional Which values to store as results of the job, and so be available to later jobs or as results for the run.

results:

optional Which values to store as results of the job, and so be available to later jobs or as results for the run. See values for more details.

A dictionary 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 blob directory where run results are stored is Process Results/<run>/results/.... Each variable is a file or tree of files, and is copied to the run's results. The key and the value both allow {...} substitutions.

If you want to change where results are stored, change process.output found in Places, in your, or your repository's Settings.