API-triggered Pipelines

What are API-triggered Pipelines?

A Pipeline having pipeline_call among its triggers is considered an API-triggered Pipeline.

name: Example API-triggered Pipeline
on:
  pipeline_call: {}
jobs:
   ...

The pipeline_call trigger allows a Pipeline to be triggered on demand by users or incoming API requests. This trigger type supports fully specified custom input fields with basic validation of types and required fields. There are no standard inputs like in Deployment Pipelines or Artefact Automation Pipelines.

on:
  pipeline_call:
    inputs:
      myInput:
        type: string
        required: true
        description: The description my input

jobs:
  job-1:
    steps:
      - uses: actions/humanitec/log@v1
        with:
          message: "The value of the input was ${{ inputs.myInput }}"

API-triggered Pipelines can be used to implement any particular automation requirements you might have, using the Available Actions.

Triggering an API-triggered Pipeline

The API operation corresponding to this event is the “Create Pipeline Run” API request. If successful, this will return an HTTP 201 response with the Run details. This command triggers the example pipeline above, supplying the required input in the payload:

humctl api POST "/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/pipelines/${PIPELINE_ID}/runs" \
  -d '
{
  "inputs": {
    "myInput": "hello"
  }
}'

When running an API-triggered Pipeline via the Web UI, you will be prompted for the values of all inputs.

Permissions

By default, an API-triggered Pipeline executes with the permissions of the user who triggered it. This can be overridden by providing a different service user id in the run-as field:

on:
  pipeline_call: {}
permissions:
  run-as: s-012343567-89ab-cdef-0123-456789abcdef

or by customizing the roles delegated to the Pipeline:

on:
  pipeline_call: {}
permissions:
  application: viewer
  env-types:
    development: deployer

The active run-as user of any resulting Pipeline runs reports this run-as user id or the user id of the Pipelines System User if delegated roles are defined. Further permission restrictions apply as noted in the pipeline_call trigger specification to prevent privilege escalation.

Examples

See the API-triggered Pipelines examples page for a collection of examples.

Artefact Automation Pipelines

Specification