- Home
- Integration and extensions
- Humanitec Pipelines
- API-triggered Pipelines
-
- Overview
-
- Overview
- Deploy your Application
- Manage your Java application
- Migrate an Application
- Provision Amazon S3 Buckets
- Deploy an Amazon S3 Resource to production
- Scaffold a new Workload and create staging and prod Environments
- Update Resource Definitions for related Applications
- Use existing Terraform modules
- Provision a Redis cluster on AWS using Terraform
- Perform daily developer activities (debug, rollback, diffs, logs)
- Deploy ephemeral Environments
-
-
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.