Skip to main content

Integration with CI/CD

Overview​

There are detailed guides that explain how to integrate Signadot with different CI/CD systems:

If your system is not listed above, you can use the general instructions below to integrate Signadot with your custom system as well.

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 also other ways to have a sandbox deleted which may be more fitting to certain integration scenarios. First, one can set the time to live in the sandbox spec. This can act either as a back-up to make sure the sandbox is deleted if for some reason the CI failed to run a sandbox deletion, or in lieu of a call to sandbox delete altogether. However, in explicit deletes help minimize resource utilisation.

The explicit delete 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}