Triggering on Webhooks

Use a webhook to trigger a pipeline.

In order to programmatically trigger pipelines, you can send a POST call to Spinnaker at a preconfigured endpoint. You can use this to trigger pipelines when a CI job finishes, from the command line, or from a third-party system. The payload, whether it is one you are able to write or it is provided for you, will be available in the Pipeline’s execution.

Note: You can configure multiple pipelines to trigger off of a single webhook.

If you’re triggering from a GitHub webhook, see the instructions here to set up that webhook.

If you’re triggering to a Spinnaker with authentication, see the instructions here to set up the automated trigger.

Prerequisites

• Artifact support enabled .

Adding a webhook trigger to a pipeline

Assuming you’ve created a pipeline, under Configuration, select Add Trigger and make its type selector Webhook.

To assign an endpoint that must be hit, you can provide a value to the Source field as shown here:

Notice that in the above image below the Type dropdown, the webhook configuration points out that we can hit http://localhost:8084/webhooks/webhook/demo to trigger the pipeline. The endpoint depends on how you’ve configured your Spinnaker endpoints – if you’re running on a different endpoint, for example https://api.spinnaker-prod.net, that’ll be shown instead.

Keeping track of that endpoint as $ENDPOINT (it will depend on where Spinnaker is installed), save that pipeline, and run:

curl $ENDPOINT -X POST -H "content-type: application/json" -d "{ }"

Payload constraints

If you want to ensure that a webhook only triggers when a certain payload arrives, you can provide Payload Constraints in the trigger. These are key/value pairs where the key must be found in the incoming payload, and the value must match using regex.

For example, if we configured:

For clarity, the constraints are mykey = myvalue and bing = b.*p.

The following payload would be accepted:

{
  "mykey": "myvalue",
  "bing": "boooop",
  "x": ["1", "2", "3"]
}

But this payload would be rejected (pipeline would not trigger):

{
  "mykey": "myvalue",
  "x": ["1", "2", "3"]
}

Passing parameters

Say your pipeline accepted some parameters (for example, the desired stack to deploy to), you can make this explicit by adding a pipeline parameter on the same configuration screen as the webhook trigger:

For more information on how to use pipeline parameters, see the pipeline expressions guide.

Warning: there are several reserved parameter keys (names) that cause unexpected behavior and failures if overwritten by a pipeline parameter definition. See the list of reserved parameter and evaluate variable key names .

If you were to manually execute this pipeline, you would be prompted with the following dialogue:

If instead you were to trigger this pipeline with a Webhook, you could supply each parameter a value inside a key/value map called parameters. Take the following payload for example:

{
  "parameters": {
    "stack": "prod"
  }
}

Note: If you select the Required checkbox for a parameter without providing a default, the pipeline does not trigger if a parameter is not present. The difference between this and the preconditions covered earlier is that when a precondition isn’t met, Spinnaker doesn’t even try to run the pipeline. However, when a required parameter doesn’t exist, Spinnaker tries and fails to run a pipeline, surfacing a “Failed Execution” in the UI.

Passing artifacts

If your pipeline requires artifacts (for example, a Kubernetes manifest file stored in GCS), you can make this explicit by defining an Expected Artifact and assigning it to the Webhook as shown below:

In order to run this pipeline, you will need to supply the required artifact in your payload under a list of artifacts:

{
  "artifacts": [
    {
      "type": "gcs/object",
      "name": "manifest.yml",
      "reference": "gs://lw-artifacts/manifest.yml"
    }
  ]
}

Last modified May 7, 2021: docs(migration): fix imgs and links (9a18ce6)