Last Updated: 2019-08-20

Are you trying to create Spinnaker deployment pipelines that get triggered whenever user pushes commits in a on-premise Bitbucket server repository? This codelab will show you how to integrate on-premise Bitbucket server with Spinnaker using HTTP artifact to accomplish this objective.

Resources:

When integrating Bitbucket server with Spinnaker or any external server, you have two triggering options:

  1. Webhooks
  2. Hooks aka Web Post hooks

In this Armory codelab we are going to use two options and show how to configure spinnaker pipeline to deploy Kubernetes deployment.

In Spinnaker, an artifact is an object that references an external resource. An artifact can be fetched using a URI. Such resources could be many things such as.

  1. A file stored in Bitbucket server
  2. A docker image
  3. An object in S3 or GCS
  4. An Amazon Machine Image

An HTTP file artifact is a reference to a file stored in plaintext and reachable via HTTP. These artifacts are generally consumed by stages in a pipeline that read configuration from text files, such as a Deploy Manifest stage. A file represented by an HTTP file artifact can be downloaded using HTTP Basic authentication.

In this Armory codelab we are going to use HTTP artifact option and show how to configure spinnaker pipeline & stages to deploy Kubernetes deployment.

Webhooks provides a way to configure Bitbucket server to make requests to your spinnaker (or another external service) whenever certain events occur. As a prerequisite you need Spinnaker API's endpoint that is publicly reachable.

Advantage of Webhooks

Without webhooks, if you want to detect events in Bitbucket server, you need to poll the API. However, polling the API is inconvenient, inefficient and error-prone.

Creating Webhooks

You can create a webhook through Bitbucket. The administrators of a repository are the only users who can create a webhook on that repository. Use the following steps to create a webhook on a repository in Bitbucket.

  1. From Bitbucket, open the repository where you want to add the webhook.
  2. Click the Repository Settings link on the left side at the bottom.
  3. From the links on the Repository Settings page, click the Webhooks link.
  4. Click the Create webhook button to create a webhook for the repository. The Create webhook page appears as:

  1. Enter a Name with a short description of the webook, eg: "Spinnaker http"
  2. Enter the URL to the spinnaker or external server.
  1. Example: https://your-spin-gate-domain-name.com/webhooks/webhook/stash
  2. Replace domain name appropriately.
  1. Select Events as triggers for webhook. Eg: Push
  2. Ensure that webhook is in Active status.
  3. Click Create to the register this webhook under this repository.

When an event associated with a webhook occurs, Bitbucket server sends a request to the webhook URL containing the event payload.

While webhooks are simple notification mechanisms to external server like Spinnaker, Hooks aka Web Post hooks in Bitbucket server provides a way to control different parts of the git workflow.

Bitbucket server POSTs to the service URL (Spinnaker API endpoint) you specify. The service receives a POST whenever the user pushes to the repository. The content type header of the POST has an application/json type. The content is a JSON payload that represents the repository push.

Creating Hooks aka Web Post hooks

You can create a web post hook through Bitbucket. The administrators of a repository are the only users who can create a hook on that repository. Use the following steps to create a Post hook on a repository in Bitbucket.

  1. From Bitbucket, open the repository where you want to add the hook
  2. Click the Repository Settings link on the left side at the bottom.
  3. From the links on the Repository Settings page, click the Hooks link.
  4. Click Add hook button on the top right side.
  5. Search and Install Web Post Hooks for BitBucket Server.
  6. Click Enable for the "Post-Receive Webhooks' item.
  7. Enter the URL to the spinnaker or external server.
  1. Example: https://your-spin-gate-domain-name.com/webhooks/git/stash
  2. Replace domain name appropriately.
  3. You can add up to 5 URLs.
  1. Press Save.

When a git event occurs, Bitbucket server sends a POST request to the webhook URL containing the event payload.

Hooks page appears as:

Marketplace to find Hooks and new apps appears as:

When configuring Spinnaker pipeline trigger for Bitbucket server, you have two triggering options:

  1. Webhook trigger type
  2. Git trigger type

In this Armory codelab we are going to use two options and show how to trigger spinnaker pipeline to deploy Kubernetes deployment when user pushes commit to Bitbucket server repository.

An HTTP file artifact is a reference to a file stored in plaintext and reachable via HTTP. These artifacts are generally consumed by stages that read configuration from text files, such as a Deploy Manifest stage.

A file represented by an HTTP file artifact can be downloaded using HTTP Basic authentication.

This automated trigger type function uses Bitbucket Web Post hooks for delivering messages to Spinnaker, and must be configured to send messages to Spinnaker's event bus as shown earlier.

Creating Git trigger

You can configure and execute a Spinnaker pipeline automatically on a git push on Bitbucket server repository via Web Post hooks. Use the following steps to create a trigger of type Git from pipeline configuration page under automated triggers sub-section.

  1. Select type as Git
  2. Select repo type as stash to indicate Bitbucket server rather than cloud
  3. Enter Bitbucket server project key ( All caps)
  4. Enter Repository name
  5. Enter Branch name
  6. Check Trigger Enabled

Automated Triggers sub-section appears as:

This automated trigger type function uses Bitbucket Webhooks for delivering messages to Spinnaker, and must be configured to send messages to Spinnaker's event bus as shown earlier.

Creating Webhook trigger

You can configure and execute a Spinnaker pipeline automatically on a user commit push on Bitbucket server repository via Webhooks. Use the following steps to create a trigger of type Webhook from pipeline configuration page under automated triggers sub-section.

  1. Select type as Webhook
  2. Refer Spinnaker webhook endpoint for Bitbucket server. Similar URI is used in Create Webhook section of this codelab to config Bitbucket repository setting.
  3. Select source as stash to indicate Bitbucket server rather than cloud
  4. Check Trigger Enabled

Automated Triggers sub-section appears as:

Since Bitbucker server can contain many repositories, one can assign expected artifact to ensure only changes in a specific repository can trigger and run the pipeline. When a trigger has one or more expected artifacts, it only runs when each expected artifact can bind to one of the artifacts in the trigger's payload.

An HTTP file artifact is a reference to a file stored in plaintext and reachable via HTTP. These artifacts are generally consumed by stages in a pipeline that read configuration from text files, such as a Deploy Manifest stage. A file represented by an HTTP file artifact can be downloaded using HTTP Basic authentication.

Set Expected Artifact

You can configure and execute a Spinnaker pipeline automatically for user events like commit push on Bitbucket server repository. An HTTP file artifact can help consume a file stored in Bitbucker server repository. Use the following steps to set artifacts for a pipeline configuration under expected artifacts sub-section.

  1. Select Custom option under Match against field
  2. Select type as http/file
  3. Enter human friendly reference name
  4. Leave version & location field blank
  5. Enter valid API, complete URL of an artifact in a given Bitbucket server repository.
  6. Repeat similar setting for Default artifact.
  7. Save changes