Specification

Humanitec Pipelines are defined through a YAML structure uploaded through the Humanitec UI, API, or the Terraform Provider.

The structure contains three required components:

• The name of the Pipeline
• The triggers it accepts including definitions of inputs
• One or more Jobs containing one or more Steps

The structure of the syntax is similar to that of GitHub Actions and defined in detail below. The schema of the structure is available as a json-schema document through the Humanitec API. This is the latest schema active in the Organization:

humctl api GET "/orgs/${HUMANITEC_ORG}/pipeline-schemas/latest"

Root #

The top-level structure is a map of properties.

on #

Each key in the map is a supported trigger and provides a different set of inputs to the Pipeline Run as it executes. A Pipeline must support at least one trigger.

deployment_request #

This is triggered when there is a deployment request and a Pipeline Criteria exists that maps to this Pipeline.

For more information, see Deployment Pipelines.

No properties are configurable.

The deployment_request trigger provides fixed inputs to the Pipeline Run:

artefact #

This is triggered when new artefact versions are uploaded to the Organization that match the criteria within the trigger definition. This trigger supports both container and workload (Score) artefact types.

For more information, see Artefact Automation.

The following options can be configured:

When triggered, this will start a new Pipeline Run with the following inputs provided:

pipeline_call #

This is triggered by an API request to create a new Pipeline Run. If a Pipeline does not define this trigger, these requests will be rejected.

For more information, see API Triggered Pipelines.

The trigger definition defines the inputs that can be passed to the Pipeline.

Each value in the inputs map can further define:

Permissions #

The permissions configuration indicates the set of Roles to delegate to this Pipeline as it executes. These Roles will impact what kinds of Platform Orchestrator operations can be performed.

The default permissions configuration is:

permissions:
  run-as: inherit

Pipelines that define an artefact trigger must replace this with a declaration of which roles are delegated to the Pipeline when it runs. For example, the following configuration restricts the Pipeline to just deployment-related activities:

permissions:
  application: developer
  env-types:
    development: deployer

Alternatively, an Organization admin can create a service user and specify the user id to run as:

permissions:
  run-as: s-01234567-89ab-cdef-0123-456789abcdef

Jobs #

This is a map of job id to job definition. The job id must be a valid identifier of A-z, 0-9, -, and _ less than 100 characters.

Jobs execute in parallel by default unless there are dependencies between them via the needs property. Any dependency cycles will cause Jobs to fail or not execute.

Each Job contains the following properties:

Steps #

Each Step defines a sequential execution within the Job and supports the following properties.

Note that a Step does not have an explicit outputs property. Step outputs are defined through the definition of the Action being used.

Concurrency #

By default, each Pipeline is limited to a maximum of ten concurrent Runs. The concurrency section can be used to further define locks and limit the number of Pipeline Runs.

Expressions #

Humanitec Pipelines support an expressions syntax that provides interpolation and transformation functionality in supported fields:

• concurrency.group
• jobs.*.if
• jobs.*.outputs
• jobs.*.steps.*.if
• jobs.*.steps.*.with.*

A supported field can contain one or more expressions delineated by a ${{ prefix and }} suffix. Each expression evaluates to a typed value which is coerced to a string if necessary.

• ${{ 'hello' }} -> "hello"
• ${{ 42 }} -> 42
• My name is ${{ 'bob' }} -> "My name is bob"
• Most ${{ 'cars' }} have ${{ 4 }} wheels -> "Most cars have 4 wheels"

Literals #

Expressions support null, booleans, integers, floating point, hexadecimal, and string literals.

• ${{ true }} and ${{ false }} evaluate to the boolean value
• ${{ null }} evaluates to a null value
• Signed 64-bit integer literals are supported through ${{ 123 }} and in hexadecimal like ${{ 0xFF }}
• Floating point numbers can be expressed as ${{ 0.5 }} and as exponentials like ${{ 2.1e5 }}
• Strings are encoded using single-quotes as ${{ 'something' }} and single quotes inside a string are encoded using double-single-quotes: ${{ 'it''s easy' }}.

Literal objects and arrays are not supported. If these are required, use fromJson to decode them from a json string literal. For example: ${{ fromJSON('{"key": "value"}') }}. This reduces the chance of errors.

Logical not operator #

The only unary operator supported is “not” via the ! symbol. This operator will evaluate to false if the input value is “truthy”. Examples of “truthy” values are “true”, non-empty strings, and non-zero numbers. Objects and arrays are always truthy.

• ${{ ! true }} -> false
• ${{ ! '' }} -> true
• ${{ ! ! 0 }} -> false

Note that !! can be used as shorthand to convert a value into its boolean truthy or falsey.

Logical and operator #

The && operator evaluates two arguments and returns whether both values are “truthy”. This returns the 1st value if it is falsey, and the 2nd value in any other case.

• ${{ true && false }} -> false
• ${{ false && true }} -> false
• ${{ true && true }} -> true
• ${{ true && 0 }} -> 0
• ${{ '' && true }} -> ""

Since expressions are parsed from left to right, more terms can be added for more complex expressions:

• ${{ true && 0 && true }} -> 0

Logical or operator #

The || operator evaluates two arguments and returns whether either value is “truthy”. This returns the 1st value if it is truthy, and the 2nd value in any other case.

• ${{ true || false }} -> true
• ${{ false || true }} -> true
• ${{ false || 0 }} -> 0
• ${{ true || 0 }} -> true

This is often used to provide a default value for an expression:

• ${{ some-value || 'default' }}

Comparison operators #

The syntax supports comparison operators <, <=, >, >=, ==, and !=. Values are comparable if they can be coerced to either strings or numbers. The output is boolean. Strings are compared lexicographically.

Arithmetic operators #

Arithmetic operators like “+” and “*” are not supported at this time.

Nested expressions #

For readability and to manipulate evaluation order, expressions can be nested using parentheses.

• ${{ ( true ) }} -> true
• ${{ (1 == 0) || 1 }} -> 1
• ${{ 1 == (0 || 1) }} -> true

Object indexing #

When a value is known to be an object with string keys mapping to values, they can be accessed by “.” or “[..]”. Unknown keys map to a null value.

Assuming an object “foo” exists as {"outer":{"inner": "hello"}}

• ${{ foo.outer.inner }} -> "hello"
• ${{ foo.other }} -> null
• ${{ foo.outer }} -> {"inner":"hello"}
• ${{ foo.outer['inner'] }} -> "hello"

Array Indexing #

When a value is known to be an array, its items can be accessed by integer keys using “[..]”. Unknown items map to a null value.

Assuming an object “foo” exists as ["cat", "dog"]

• ${{ foo[0] }} -> "cat"
• ${{ foo[1] }} -> "dog"
• ${{ foo[2] }} -> null

Context Variables #

Different context variables exist depending on where an expression is evaluated and what Jobs or Steps have completed within the Pipeline.

All expressions have access to the “pipeline” and “inputs” contexts.

• pipeline.org.id -> the Organization id
• pipeline.app.id -> the Application id
• pipeline.id -> the Pipeline id
• pipeline.run.id -> the Pipeline Run id
• pipeline.run.status -> the current status of the Pipeline Run
• pipeline.run.trigger -> the event that triggered this Pipeline. (e.g. “pipeline_call”)
• pipeline.run.run_as -> the user id that this Pipeline Run is executing as
• inputs -> the map of inputs to the Pipeline Run

Expressions executing in the context of a Job (such as jobs.*.if, jobs.*.steps.*.if or jobs.*.steps.*.with) will additionally have access to variables regarding the Job and dependent Jobs, as well as the Steps within the current Job.

• job.id -> the Job id
• job.name -> the Job name or id if name is not set
• job.status -> The current status of the Job. This could be executing, succeeded, failed, or cancelled.
• steps.<id>.status -> The status of a previous Step with the given id within the Job. This could be skipped, succeeded, failed, or cancelled.
• steps.<id>.outputs -> the map of outputs produced by the Step with the given id
• needs.<id>.name -> the name of the Job with the given id
• needs.<id>.status -> The status of the Job with the given id. This could be succeeded, or failed.
• needs.<id>.outputs -> the outputs of a previous Job with the given id that this Job depended on

Expressions in the Job will also have access to Application values and secrets through the “app” context.

• app.values.MY_KEY -> "my-value"
• app.values.MY_SECRET -> sensitive("my password")

Secrets will return sensitive values that will be masked out of any log output and cannot pass between steps and jobs. Secrets are only available if the Application has the Humanitec secret store configured as its primary secret store.

Built-in functions #

Various built-in functions are available.

The map, filter, and group functions take in an inline function which can be written using a variable => expression syntax. For example:

filter(fromJSON('[1, 2, 3, 4, 5, 6]'), i => i > 3)  ==  [4, 5, 6]