GitLab

Overview

This document provides an overview of integrating the Signadot CLI with GitLab, using GitLab CI/CD.

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 merge 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: "@{name}"
spec:
  cluster: "@{cluster}"
  forks:
  - forkOf:
      kind: Deployment
      namespace: default
      name: my-svc
    customizations:
      images:
      - image: "@{image}"

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, which is required to access the Signadot Control Plane. 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 GitLab CI/CD variable.

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

Refer to GitLab CI/CD variables for more information on creating variables from the GitLab UI.

Pipeline YAML

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

stages:
- run_tests

run_tests:
  stage: run_tests
  image: alpine
  variables:
    SIGNADOT_CLUSTER: demo
    IMAGE_TAG: $CI_COMMIT_SHA
    # Define the sandbox name using a short version of the gitsha to respect the
    # limit (30 chars)
    SANDBOX_NAME: "my-svc-${CI_COMMIT_SHORT_SHA}"
  script: |
    # Set up Signadot CLI
    apk add jq curl
    curl -sSLf https://raw.githubusercontent.com/signadot/cli/main/scripts/install.sh | sh

    # Create a sandbox
    echo "Creating sandbox ${SANDBOX_NAME}..."
    signadot sandbox apply \
      --set name=${SANDBOX_NAME} \
      --set image=docker-user/repo:${IMAGE_TAG} \
      --set cluster=${SIGNADOT_CLUSTER} \
      -f - \
      < ${CI_PROJECT_DIR}/.signadot/my-svc-template.yaml

    # Optionally run automated tests using jobs
    echo "Running automated tests..."
    signadot job submit --attach -f \
      --set branch=... \
      -f - \
      < ${GITHUB_WORKSPACE}/.signadot/job.yaml

    # Optionally delete the sandbox if only running automated tests
    # else you may omit this and delete on PR close / using TTL
    echo "Deleting sandbox..."
    signadot sandbox delete ${SANDBOX_NAME}

Set up Automatic Deletion of Sandboxes

In the previous example, we are deleting the Sandbox inline with the execution of the run-tests job, which is fine if you are only running automated tests, but if you are also using Signadot to perform previews, you will want to keep the sandbox alive until the MR is merged or closed.

In that regard, Sandbox TTLs is a simple way to ensure deletion of sandboxes which may fit your organization's use cases. Here is an example of the previously defined sandbox spec including a TTL (defined as 10 days after the last sandbox update):

name: "@{name}"
spec:
  cluster: "@{cluster}"
  forks:
  - forkOf:
      kind: Deployment
      namespace: default
      name: my-svc
    customizations:
      images:
      - image: "@{image}"
  ttl:
    duration: 10d
    offsetFrom: updatedAt

However, using Sandbox TTLs has limitations, in particular with respect to preview URLs which do not work when their associated sandbox has been deleted. To guarantee all sandboxes are available as long as the MR is open, and that all sandboxes associated with closed MRs are deleted, you may consider using the GitLab ability to run pipelines in a scheduled basis (refer to Scheduled pipelines). This feature opens the door for running a periodic script (for example, every 30 minutes) that using the Signadot and GitLab APIs could reconcile the running sandboxes against the open merge requests, deleting any sandbox linked to a merged or closed MR.

Optimization with a Custom Image

GitLab allows using a custom docker image, and doing so can speed up the execution of the steps associated with sandboxes. A custom image for GitLab can be built providing the signadot command directly, as in the Dockerfile below.

# signadot
FROM signadot/signadot-cli as signadot

# here use whatever image you are using as base for performing the tests (in the
# example above alpine)
FROM alpine

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