Skip to main content

CI Integrations

Overview

Signadot supports the following integrations with Continuous Integration (CI) systems:

Below we discuss the common methodology behind these integrations.

Creating sandboxes

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.

A template of the sandbox specification, in the form of a yaml file is stored within the git repository which is hooked up to the CI system, by convention in .signadot/<service-name>-template.yaml. This takes the following form:

name: "<service>-sandbox-@{git-short-commit}"
spec:
forks:
- customizations:
images:
- container: hotrod
image: "@{image}"
# ... rest of specification

With such a sandbox template in place, we call the signadot CLI to create the sandbox:

signadot sandbox apply -f ${REPO_PATH}/.signadot/<service>-template.yaml \
--set git-short-commit=${GIT_SHA:0:6} \ # the 0:6 makes this a short commit
--set image=docker-user/repo:${GIT_SHA} \
-o yaml > ${REPO_PATH}/.signadot/<service>-response.yaml

As in the example, typically, we include a short commit hash in the name and the full commit hash in the image tag. A short commit hash is used in the sandbox name because the name is limited to 30 characters. A full commit hash is used for the image tag, since docker images use this format commonly. In both cases, the sha provides a uniqueness guarantee.

We store the output of the command in a file .signadot/<service>-response.yaml containing the final specification and status of the sandbox which is required in order to access it and for running tests against it.

Running Tests

Once the sandbox has been created, it is typically tested using endpoints in the sandbox. Endpoint URLs are present in the output file. For example:

endpoints:
- baselineUrl: https://frontend-hotrod-svc-xug66ctplxwrl---baseline.preview.staging.signadot.com
host: frontend.hotrod.svc
name: frontend-hotrod-svc
port: 8080
protocol: http
routeType: host
url: https://frontend-hotrod-svc--test-apply.preview.staging.signadot.com

To run tests against the sandbox workload, one can extract the url or baselineUrl as needed.

% yq 'endpoints[0].url' .signadot/<service>-response.yaml 

https://frontend-hotrod-svc--test-apply.preview.staging.signadot.com

Finally, to use the endpoint URL, the caller needs to authenticate. For example,

endpoint=$(yq 'endpoints[0].url' ${REPO_PATH}/.signadot/<service>-response.yaml)
curl --fail -H "signadot-api-key: ${SIGNADOT_API_KEY}" $endpoint

To run a test suite in the repository, one needs to make sure it accepts sandbox URLs and a signadot API key as input.

Deleting the Sandbox

To delete the sandbox, one runs:

signadot sandbox delete -f ${REPO_PATH}/.signadot/<service>-response.yaml

There are other ways to call sandbox delete which may be more fitting to certain integration scenarios. The form above gleans the identifying name of the sandbox from the response, allowing one to expand any variables in the name field exactly once. This can reduce the chance of error when changing the integration or adapting it to a new context.

However, if deletion is called from a context which does not have access to the response, the name will need to be expanded in the same fashion as it was expanded when the sandbox was created. Following this example, one could call

signadot sandbox delete -f .signadot/<service>-template.yaml \
--set git-short-commit=${GIT_SHA:0:6}

or

signadot sandbox delete <service>-sandbox-${GIT_SHA:0:6}