BitBucket CI Integration

Overview

This document provides an overview of integrating the Signadot CLI with BitBucket, using BitBucket Pipelines.

Implementing the integration follows this basic outline:

• Adding a sandbox specification to the repository.
• Setting up the Signadot configuration.
• Creating the pipeline.

Finally, there is a description of an optional, more advanced custom image which speeds up CI runs by pre-installing dependencies in a custom pipelines container image.

Adding a Sandbox Specification

When a sandbox is created in a CI context, in general it needs to be tailored to run the changes represented in a pull request or commit. These customizations serve to identify the sandbox in a way that can be associated with the commit and to have the sandbox set up to run the changes in the commit.

To accomplish this, a template of the sandbox specification, in the form of a yaml file is stored within the git repository, by convention in .signadot/<service-name>-template.yaml. The sandbox template below provides a simple example that is setting up a sandbox for a single service called my-svc.

name: "my-svc-@{git-short-commit}"
spec:
  forks:
  - forkOf:
      kind: Deployment
      namespace: default
      name: my-svc
    customizations:
      images:
      - container: hotrod
        image: "@{image}"
  defaultRouteGroup: # CLI v0.3.7+ required (see sandbox specification for details)
    endpoints:
    - name: my-svc-endpoint       
      target: http://my-svc.default.svc:8080

Setting up the Signadot configuration

The signadot command needs to have two parameters configured.

1. Signadot Org, which is the name of your organization's account with Signadot. In CI contexts, this is usually easiest to accomplish by setting the environmental variable SIGNADOT_ORG when running the command.
2. API key required to access Signadot. This is also usally easiest to accommplish by setting the environmental variable SIGNADOT_API_KEY when running the command, which in turn should be stored as a BitBucket secured variable.

Both of these values are made available when a new API Key is created via the Signadot Dashboard.

Refer to BitBucket variables for more information about setting variables.

Pipeline YAML

Below is an example BitBucket pipeline configuration yaml file which sets up a single service sandbox for a 'my-svc' service.

image: atlassian/default-image:3

pipelines:
  default:
    - step:
        name: 'Create Sandbox'
        services:
          - docker
        script:
          - |
            # run the cli
            # setting the gitsha to a short version to respect the name
            # limit (30 chars)
            docker run -i \
              -e SIGNADOT_ORG=${SIGNADOT_ORG} \
              -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
              signadot/signadot-cli \
              /signadot sandbox apply \
              --set image=docker-user/repo:${BITBUCKET_COMMIT} \
              --set git-short-commit=${BITBUCKET_COMMIT:0:6} \
              -f - \
              -o yaml \
              < .signadot/my-svc-template.yaml \
              > .signadot/my-svc-response.yaml
            # print out the sandbox yaml
            cat .signadot/my-svc-response.yaml
        artifacts:
          # store the response sandbox spec as an artifact for usage in
          # subsequent steps.
          - .signadot/my-svc-response.yaml
    - step:
        name: 'Test Changes'
        # This supposes ./yq was stored as an artifact from a setup step
        # created with 
        #  - go install github.com/mikefarah/yq/v4@latest
        #  - cp ${HOME}/go/bin/yq .
        script:
          - |
            endpoint=$(./yq '.endpoints[0].url' .signadot/my-svc-response.yaml)
            #
            # run integration test scripts here, providing the Signadot API key and
            # endpoints as needed to each one.  In this example, we use curl
            # as a minimal placeholder that will run on most systems.
            #
            curl --fail -H "signadot-api-key: ${{ secrets.SIGNADOT_API_KEY }}" $endpoint
    - step:
        name: 'Delete Sandbox'
        services:
          - docker
        script:
          - |
            docker run -i \
              -e SIGNADOT_ORG=${SIGNADOT_ORG} \
              -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
              signadot/signadot-cli \
              /signadot sandbox delete -f - \
              < .signadot/my-svc-response.yaml

Optimization with a Custom Image

Bitbucket allows using a custom docker image, and doing so can significantly speed up the execution of the steps associated with sandboxes. A custom image for BitBucket can be built providing the commands signadot and yq directly, as in the Dockerfile below. With this in place, one can use the commands directly instead of calling them via docker run -i ... signadot/signadot-cli ..., or installing yq with every run.

# signadot
FROM signadot/signadot-cli as signadot

# yq
FROM golang:1.19 as yq
RUN go install github.com/mikefarah/yq/v4@latest

# this is the beginning of the BitBucket default 
# Dockerfile for version 3.
FROM atlassian/default-image:3

# add the tools for working with signadot
COPY --from=signadot /signadot /usr/bin/signadot
COPY --from=yq /go/bin/yq /usr/bin/yq