Github CI Integration

Overview

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 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:
      - 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 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.

jobs:
  signadot:
    runs-on: ubuntu-latest

    # dependency on building image for a service.
    needs: [ build, changes ] 
    steps:
      - name: Create Sandbox
        env:
          SIGNADOT_ORG: signadot
          IMAGE_TAG: ${{ github.sha }}
          SIGNADOT_API_KEY: ${{ secrets.SIGNADOT_API_KEY }}
        run: |
          # 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:${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 github.com/mikefarah/yq/v4@latest
          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
        env:
          SIGNADOT_ORG: signadot
          SIGNADOT_API_KEY: ${{ secrets.SIGNADOT_API_KEY }}
        run: |
          docker run -i \
            -e SIGNADOT_ORG=${SIGNADOT_ORG} \
            -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
            signadot/signadot-cli \
            /signadot sandbox delete \
            -f - \
            < ${GITHUB_WORKSPACE}/.signadot/my-svc-response.yaml