Pipelines 201

Dashboard

Permissions

Pipelines may be public or private. Furthermore, a user must be assigned to a pipeline in order to perform certain actions with it. Anonymous users are users not logged in on the dashboard. Please see the table below for more complete details.

	Anonymous/Unassigned	Assigned
Have the pipeline listed	Yes*	Yes
See recent runs	Yes*	Yes
See run logs	Yes*	Yes
Download run archive	Yes*	Yes
See visibility	Yes*	Yes
See the trigger URL	No	Yes
See the pipeline config	No	Yes
Edit the pipeline config	No	Yes
Run the pipeline	No	Yes

* Only for public pipelines.

Pipelines

Environment Variables

Similar to the script array, an array of environment variables can be provided:

stages:
  - name: Echo
    image: alpine
    environment:
      - "FOO=BAR"
      - "BAZ"
    script:
      - 'echo "${FOO} ${BAZ}"'

In this example, the logs will show:

**************** [1/1] ****************
BAR BAZ
Process exited with status code 0

Environment variables will split at the first =. If this is not provided or nothing comes after it, the value will default to the key as shown in the example above.

Custom Runtimes

It is possible to run each container with a custom runtime:

stages:
  - name: Echo
    image: alpine
    runtime: sysbox
    script:
      - 'echo "Hello, sysbox!"'

This will run the stage's container with the sysbox container runtime. A custom runtime is required in order to be able to achieve functionality such as Docker inside Docker. The runtime must be available to the runner. If not, the pipeline will error.

Triggers

A pipeline is triggered by sending a POST request to /trigger/:token, where :token is the token of the pipeline. Every pipeline has its own token, which should be kept private. In fact, the only thing stopping someone from running a pipeline is them not knowing the token!

In order to run a pipelin e.g. whenever code is pushed, just configure an outgoing webhook to the trigger URL. The trigger URL accepts POST only.

There is planned support for integrations for different trigger sources. For example, /trigger/:token/github will integrate the pipeline run with GitHub. More information on this will be provided when the feature is ready.

Trigger Constraints

Sometimes, it is not possible to completely finetune outgoing webhooks (for example, to only send when event X happens on branch Y). In order to provide flexibility, trigger constraints can be provided in the config. If a constraint is not met, then the trigger will simply be ignored (and result in HTTP status 204).

Header Constraints

Header constraints require a certain header to be present in the request to the trigger URL:

constrainHeaders:
  Authorization: "Bearer foo"
  X-Some-Event:
  - bar
  - baz
stages:
  - name: Echo
    image: alpine
    script:
      - 'echo "Only sometimes invoked"'

Here, the pipeline will only run if the Authorization header is present and set to Bearer foo, and X-Some-Event is either bar or baz. Header names are case insensitive, in compliance with the HTTP protocol.

Body Constraints

Body constraints require the body to contain specific information. JSPath is used to access a specific part of the body, and then this is compared to the value.

Given the following config:

constrainBody:
  ".foo.bar": ["baz"]
stages:
  - name: Echo
    image: alpine
    script:
      - 'echo "Only sometimes invoked!"'

The pipeline will run with this body:

{
  "foo": {
    "bar": "baz"
  }
}

But not this body:

{
  "foo": "bar",
  "cow": "moo"
}

The value to compare to can be arbitrary (not just a string), as long as it is supported by YAML and convertible to JSON. Please note that JSPath usually returns an array, even when querying for a single element. For more information, refer to the JSPath documentation.

Parameters

Pipelines support parameters, which are like placeholders. If a parameter foo exists, then %foo% will be replaced in all stage names, images, runtimes, environment variables and scripts. Parameters must match [a-zA-Z_-]+.

Parameters are specified in the config:

parameters:
  foo: ".abc.xyz"
  bar: null
stages:
  - name: "Echo"
    image: "alpine"
    script:
      - 'echo "Foo: %foo%; Bar: %bar%"'

Parameters can be JSPaths, such that they will be extracted from the trigger body. The first element of the JSPath array (if it exists) will be selected, and converted to a string before replacement.

Parameters can be set to null such that they need to be manually specified. This can be done through running the pipeline on the dashboard, or the trigger URL.

Parameters can be passed as URL encoded query strings of the trigger URL. If a parameter value is both extracted from the URL and from the body, the URL one takes precedence.