Skip to main content

GitHub CI Integration


This document provides an overview of integrating the Signadot CLI with GitHub, using GitHub Actions.

Implementing this integration follows the following steps.

  • Adding a sandbox specification to the repository.
  • Setting up the Signadot API key configuration.
  • Configuring a job to set up and test using sandboxes in GitHub Actions.

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 environment for a single service called my-svc.

name: "my-svc-@{git-short-commit}"
- forkOf:
kind: Deployment
namespace: default
name: my-svc
- image: "@{image}"
name: my-svc-endpoint
port: 8080
protocol: http

Setting up the Signadot API key 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 Signadot. This is also usally easiest to accommplish by setting the environment variable SIGNADOT_API_KEY when running the command, which in turn should be stored as a Github secret.

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

To set up the github secret for a repository, you will need to create a secret for a github action containing the signadot API key as a value. To do so, edit secrets in the settings for the repository, as in the screenshot below.


GitHub Action

Below shows a commented GitHub action job which runs signadot to set up a sandbox for each new commit and run tests against it. The specification in use in the example below is along the lines of the sandbox template specified above.

runs-on: ubuntu-latest

# dependency on building image for a service.
needs: [ build, changes ]
- name: Create Sandbox
SIGNADOT_ORG: signadot
IMAGE_TAG: ${{ github.sha }}
run: |
# run the cli
# setting the gitsha to a short version to respect the name
# limit (30 chars)
docker run -i \
signadot/signadot-cli \
/signadot sandbox apply \
--set image=docker-user/repo:${IMAGE_TAG} \
--set git-short-commit=${IMAGE_TAG:0:6} \
-f - \
-o yaml \
< ${GITHUB_WORKSPACE}/.signadot/my-svc-template.yaml \
> ${GITHUB_WORKSPACE}/.signadot/my-svc-response.yaml
# print out the sandbox yaml
cat ${GITHUB_WORKSPACE}/.signadot/my-svc-response.yaml

- name: Test Sandbox
run: |
go install
endpoint=$(yq '.endpoints[0].url' ${GITHUB_WORKSPACE}/.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

- name: Delete Sandbox
SIGNADOT_ORG: signadot
run: |
docker run -i \
signadot/signadot-cli \
/signadot sandbox delete \
-f - \
< ${GITHUB_WORKSPACE}/.signadot/my-svc-response.yaml