Custom Webhook Stages

Custom webhook stages provide a simple, yet powerful, way of adding custom stages to Spinnaker.

Custom webhook stages provide a simple, yet powerful, way of adding custom stages to Spinnaker. These stages are typically used to make quick API calls to an external system as part of a pipeline. Instead of extending the various components through code, users can simply add configuration to Orca for these stages. They appear in the UI as if they were a native stage.

Creating a custom webhook stage

To create a custom webhook stage, you’ll need to add configuration for the stage in orca-local.yml. The webhook.preconfigured property supports configuring multiple webhook stages.

  1. webhook:
  2.   preconfigured:
  3.   - label: Github - Github Commit Status
  4.     type: githubStatus
  5.     enabled: true
  6.     description: Update a Github Commit Status
  7.     method: GET
  8.     url: https://api.example.com

Custom webhook stages support a variety of options, most of which are available via the UI when using the vanilla Webhook stage. Once a property is set within a custom webhook stage, users will not be allowed to override that settings via the UI. The following basic properties can be set within your configuration. More advanced properties will be covered in other sections.

  • enabled - whether the stage will appear in the UI
  • label - the human readable name of the stage
  • description - a human readable description of what the stage is used for
  • type - a unique key used to identifty the stage type within a pipeline
  • url - the url for the webhook
  • customHeaders - any headers needed for your webhook’s http request. ex. API tokens.
  • method - HTTP method used for the webhook.
  • payload - the JSON payload

Configuring parameters for custom webhook stages

Custom webhook parameters allow for variables to be used within your stages. These parameters are rendered in the UI and let users of your stage set them as necessary. When the stage executes, the values of these parameters are evaluated using SpEL which means that they can be dynamic in nature. To configure webhook parameters, you can use the following configuration within your webhook stage:

  1. parameters:
  2. - label: Git Commit
  3.   name: gitCommit
  4.   description: The Git commit of your application
  5.   defaultValue: ''
  6.   type: string

Currently, the only supported type is string, however, we imagine more advanced types will be supported in the future.

The value of these properties can be accessed via SpEL within various attributes of the webhook configuration. For example, if we built a stage for updating Github statuses of a commit, we could use the above property and reference it’s value by using SPeL within our webhook URL.

  1. url: https://api.github.com/repos/spinnaker/my-repo/statuses/${parameterValues['gitCommit']}

Webhook properties are rendered in the UI as input fields.

Using a custom webhook stage

Custom webhook stages will be added to the list of stages within the Pipeline editor. You can add these stages as you would any other stage.

Custom Webhook Stages - 图1

If you’ve specified any parameters, they will be rendered and editable as part of the stage configuration. You can also use SPEL as a way of setting these values dynamically during pipeline execution.

Custom Webhook Stages - 图2

Useful custom webhook stages

Update Github commit status

  1. label: Github - Github Commit Status
  2. type: githubStatus
  3. enabled: true
  4. description: Update a Github Commit Status
  5. method: POST
  6. customHeaders:
  7.   Authorization:
  8.     - token MY_API_TOKEN
  9. url: https://api.github.com/repos/ethanfrogers/spinnaker/statuses/${parameterValues['gitCommit']}
  10. payload: |-
  11.   {
  12.     "state": "${parameterValues['status']}",
  13.     "target_url": "${parameterValues['targetUrl']}",
  14.     "context": "${parameterValues['context']}"
  15.   }
  16. parameters:
  17.   - label: Git Commit
  18.     name: gitCommit
  19.     description: The Git Commit to create a status for
  20.     type: string
  21.   - label: Status
  22.     name: status
  23.     type: string
  24.   - label: Target URL
  25.     name: targetUrl
  26.     type: string
  27.   - label: Context
  28.     name: context
  29.     type: string

Create New Relic Deployment

  1. label: New Relic - Create Deployment
  2. type: newRelicDeployment
  3. enabled: true
  4. description: Create a Deployment in New Relic
  5. method: POST
  6. customHeaders:
  7.   X-Api-Key:
  8.     - my-api-key
  9.   Content-Type:
  10.     - application/json
  11. url: https://api.newrelic.com/v2/applications/${parameterValues['appId']}/deployments.json
  12. payload: |-
  13.   {
  14.     "deployment": {
  15.       "revision": "${parameterValues['revision']}",
  16.       "user": "${parameterValues['user']}",
  17.       "description": "${parameterValues['description']}"
  18.     }
  19.   }
  20. parameters:
  21.   - label: Application ID
  22.     name: appId
  23.     description: New Relic Application ID
  24.     type: string
  25.   - label: Revision
  26.     name: revision
  27.     type: string
  28.   - label: User
  29.     name: user
  30.     type: string
  31.   - label: Description
  32.     name: description
  33.     type: string

Last modified May 4, 2021: more cleanup (0281411)