Artefact Automation Pipelines

What are Artefact Automation Pipelines?

A Pipeline having artefact among its triggers is considered an Artefact Automation Pipeline.

name: Example Artefact Automation Pipeline
on:
  artefact:
  ...
jobs:
  ...

When new Workload or container artefact versions are added to the Humanitec Platform Orchestrator, events are broadcast that can be used to trigger Pipelines. These events can be used to automatically deploy new container image versions or new Workload artefacts as they are built by developers or CI processes.

“Workload” artefacts contain a Score Workload specification which includes all the details required to launch your service including aspects such as images, environment variables, attached volumes and files, and exposed ports. Uploaded Workload artefacts can be deployed directly into Environments via an Artefact Automation pipeline using the create-delta action as shown below. See Add new Workload artefacts for details on notifying the Platform Orchestrator about new Workload specification versions.

“Container” artefacts contain only a reference to a container image and version. These can be used to roll out new versions of existing workloads that have already been deployed. See Add new image sources for details on notifying the Platform Orchestrator about new artefact versions.

An artefact push, which happens on the Organization level, can trigger multiple Artefact Automation Pipelines across the Organization, and in different Applications.

The artefact trigger

At the core of artefact automations using Pipelines is the artefact trigger definition. The type field indicates whether this Pipeline is triggered by either workload or container artefacts. At least one include pattern is required to specify the artefact names to match.

name: Example Artefact Pipeline
on:
  artefact:
    type: container
  include:
  - registry.humanitec.io/my-org/service-.*

The artefacts matched by the trigger may be fine-tuned using the include, exclude, match-ref, and exclude-ref properties which all accept regular expressions. The example below deploys two workload artefacts that have been tagged with the default branch.

on:
  artefact:
    type: workload
    include:
    - github.com/example.org/example/webservice
    - github.com/example.org/example/webworker
    match-ref: refs/heads/main

To read more about the supported fields, see the Pipeline Specification.

Pipeline inputs

When an Artefact Automation Automation Pipeline is triggered, it receives the following inputs:

  • workload_artefacts - a list of workload artefact versions that were matched
  • container_artefacts - a list of container image versions that were matched

The lists contain the most recent version of each artefact.

Using the create-delta action

Humanitec Pipelines provide the “actions/humanitec/create-delta” action which can correctly apply the workloads and images received as inputs to an existing Environment to create a Deployment Delta.

This works in the following way:

  1. Apply all input Workloads to the target Environment. If the Workloads already exist, only update the changed fields.
  2. For each input container image, update the container image tag for any Workloads that use a different version of the same container image.

The output Delta can then be deployed to the target Environments using the apply action (to create a Deployment Set) and deploy action (to deploy the Set).

name: Deploying an artefact
permissions:
  application: developer
  env-types:
    development: deployer
on:
  artefact:
    type: workload
    include: [".*"]
jobs:
  main:
    steps:
    - uses: actions/humanitec/create-delta@v1
      id: create
      with:
        env_id: development
        workload_artefacts: ${{ inputs.workload_artefacts }}
    - uses: actions/humanitec/apply@v1
      id: apply
      with:
        env_id: development
        delta_id: ${{ steps.create.outputs.delta_id }}
    - uses: actions/humanitec/deploy@v1
      with:
        env_id: development
        set_id: ${{ steps.apply.outputs.set_id }}
        comment: Deploying workload artefacts

Permissions

The “artefact” trigger is notable because it is triggered by automated actions and cannot inherit permissions from a user directly triggering it. This means that a permissions block must be specified. This can specify either a pre-existing service user:

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

Or delegate permissions to the Pipelines System User:

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

Note that the “Deployer” role must be granted for each environment type the Pipeline will deploy to.

Examples

See the Artefact Automation Pipelines examples page for a collection of examples.

Deployment Pipelines

API-triggered Pipelines