Deployment Pipelines

Looking for examples? See the Deployment Pipelines examples page .

What are Deployment Pipelines? #

A Pipeline with a deployment_request among its triggers is considered a Deployment Pipeline.

name: Example Deployment Pipeline
on:
  deployment_request: {}
jobs:
   ...

Deployment Pipelines handle the deployment of a Delta or Set , or the redeployment of a previous Deployment to the Environment.

Pipeline Inputs #

When a Deployment Pipeline is triggered, it receives the following inputs:

• env_id - the target Environment of the Deployment
• set_id - (optional) a Deployment Set to deploy into the Environment. If not specified, a delta_id will be defined
• delta_id - (optional) a Deployment Delta to apply to the Environment
• value_set_version_id - (optional) A value set version to deploy with. Defaults to the latest version or the version extracted from the source Deployment
• comment - (optional) a Deployment comment

Triggering Deployment Pipelines #

Deployments can be triggered in the Humanitec Platform Orchestrator in multiple ways:

1. Clicking “Deploy” or “Re-deploy” in the Platform Orchestrator UI
2. Using the Humanitec CLI (humctl) to deploy a Delta
3. Issuing API requests to the /orgs/{orgId}/apps/{appId}/pipeline-runs endpoint with the trigger set to "deployment_request"
4. Issuing API requests to the /orgs/{orgId}/apps/{appId}/envs/{envId}/deploys endpoint
   • The score-humanitec delta --deploy CLI command calls this endpoint (deprecated)
5. Using existing container image automation rules

When any of these actions are performed, the Platform Orchestrator collects the input arguments into a Deployment Request and triggers a matching Pipeline through the use of Pipeline Criteria.

Pipeline Matching Criteria #

A Pipeline can match the Deployment Request using any of the following criteria attributes:

• env_type: A specific environment type which the Pipeline will match, or "*" for any environment type.
• app_id: This is defaulted to the Application of the Pipeline.
• env_id: A specific environment id within the current Application, or "*" to match any environment.
• deployment_type: either "deploy" or "re-deploy", depending on whether a delta_id, set_id, or deployment_id are provided in the request. The type will be "re-deploy" if a deployment_id is provided, or will be "deploy" in any other case.

These criteria fields match from most to least specific by adding together the preferences for env_type (1), app_id (2), env_id (4), and deployment_type (8). For example, a combination of app_id and env_id is preferred over a combination of env_type and env_id because 6 is greater than 5.

Pipeline Matching Criteria must be unique so that the link between a deployment request and a Pipeline is deterministic.

Unlike Matching Criteria for Resource Definitions , Pipeline Matching Criteria cannot include an Application ID other than the Pipeline’s parent Application. Pipelines are declared on the Application level, so they will never match a Deployment in another Application. In contrast, Resource Definitions are applicable across Applications.

Follow these example instructions to define Pipeline Matching Criteria. Set all ${ENVIRONMENT_VARIABLES} as required. See here how to obtain a HUMANITEC_TOKEN.

The example matching criteria shown below will cause this Pipeline to be used for any Delta Deployments to a development type Environment, but it won’t be used for re-deployments or for other Environments.

• Web UI
• API
• CLI
• Terraform

curl https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/pipelines/${PIPELINE_ID}/criteria \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
-d '{
  "env_type": "development",
  "deployment_type": "deploy",
  "trigger": "deployment_request"
}'

humctl api post /orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/pipelines/${PIPELINE_ID}/criteria \
-d '{
  "env_type": "development",
  "deployment_type": "deploy",
  "trigger": "deployment_request"
}'

resource "humanitec_pipeline_criteria" "example" {
  app_id      = humanitec_application.example.id
  pipeline_id = humanitec_pipeline.example.id
  deployment_request = {
    env_type        = "development"
    deployment_type = "deploy"
  }
}

The default Deployment Pipeline #

If no custom Pipelines have been created or none match the target environment of a deployment, then the request uses a default Humanitec-managed Pipeline to perform the deployment. This “default” Pipeline is immutable and is automatically created when needed.

The resulting Pipeline run has the following inputs:

• "env_id": the target environment id
• "delta_id": if the deployment request contained a Deployment Delta id
• "set_id": if the deployment request contained a Deployment Set or a Deployment id (both will be mapped to this input)
• "value_set_version_id": if the deployment request contained a value set version or a deployment id
• "comment": if the deployment request contained a comment

The implementation of a Deployment Pipeline is expected to validate and service the deployment request by deploying the target change to the target environment. A custom deployment Pipeline may contain additional steps such as validations of the content, cloning the change to one or more other environments, or triggering external side effects such as integration tests or manual approvals. See for implementing those steps.

Triggering a Deployment request through the API #

Set the following variables for use with the humctl CLI : HUMANITEC_TOKEN, HUMANITEC_ORG, HUMANITEC_APP, HUMANITEC_ENV.

Let’s consider a request to deploy a Deployment Delta that has already been prepared.

The following request can be made with the humctl CLI:

humctl api POST "/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/pipeline-runs" \
  -d '
{
  "trigger": "deployment_request",
  "env_id": "'${HUMANITEC_ENV}'",
  "delta_id": "replace-with-your-delta-id"
}'

This command returns an executing Pipeline Run for the Pipeline that has been matched to this request based on its Matching Criteria.

Also, consider a request to re-deploy a previous Deployment that ran in the past.

The following request can be made with the humctl CLI:

humctl api POST "/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/pipeline-runs" \
  -d '
{
  "trigger": "deployment_request",
  "env_id": "'${HUMANITEC_ENV}'",
  "deployment_id": "replace-with-your-deployment-id"
}'

This returns an executing Pipeline Run to redeploy the Deployment Set from the given Deployment.

Example Deployment Pipeline and criteria #

As an example, consider the following use case: An application owner wants to make an outgoing HTTP request after successful deployments to their production environment.

The following Pipeline is the same as the default Humanitec-managed Pipeline but with one additional step:

name: Example Pipeline With API Request
on:
  deployment_request: {}
jobs:
  Deployment:
    steps:
    - if: ${{ ! inputs.set_id }}
      name: Create Deployment Set
      id: create-deployment-set
      uses: actions/humanitec/apply@v1
      with:
        delta_id: ${{ inputs.delta_id }}
        env_id: ${{ inputs.env_id }}
    - name: "Deploy delta to environment"
      uses: actions/humanitec/deploy@v1
      with:
        set_id: ${{ inputs.set_id || steps.create-deployment-set.outputs.set_id }}
        value_set_version_id: ${{ inputs.value_set_version_id }}
        env_id: ${{ inputs.env_id }}
        message: ${{ inputs.comment }}
    - name: Custom Step
      uses: actions/humanitec/http@v1
      with: 
        url: https://api.mytestserver.com/some/parameters
        method: POST

You can then create a Matching Criteria for this pipeline with “env_id” set to “development”. All Delta or Set deployments for this Environment will now go through this Pipeline.

Examples #

See the Deployment Pipelines examples page for a collection of examples.