GitHub

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.
• Optionally display sandbox status in GitHub Pull Requests and enable automatic sandbox deletion by installing the Signadot GitHub App.

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

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 the Signadot Control Plane. This is also usually 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 optionally run tests against it. The specification in use in the example below is along the lines of the sandbox template specified above.

jobs:
  run-tests:
    runs-on: ubuntu-latest
    # dependency on building image for a service.
    needs: [ build, changes ]
    env:
      SIGNADOT_ORG: signadot
      SIGNADOT_API_KEY: ${{ secrets.SIGNADOT_API_KEY }}
      SIGNADOT_CLUSTER: demo
      IMAGE_TAG: ${{ github.sha }}
    steps:
      - name: Set up Signadot CLI
        run: |
          curl -sSLf https://raw.githubusercontent.com/signadot/cli/main/scripts/install.sh | sh

      # Create / update sandbox
      - name: Apply Sandbox
        run: |
          # Define the sandbox name using a short version of the gitsha to respect the
          # limit (30 chars)
          export SANDBOX_NAME="my-svc-${IMAGE_TAG:0:6}"
          echo "SANDBOX_NAME=${SANDBOX_NAME}" >> "$GITHUB_ENV"

          # Create the 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 - \
            < ${GITHUB_WORKSPACE}/.signadot/my-svc-template.yaml

      # Optionally run automated tests using jobs
      - name: Run Automated Tests
        run: |
          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
      - name: Delete Sandbox 
        run: |
          echo "Deleting sandbox..."
          signadot sandbox delete ${SANDBOX_NAME}

You can find a real-life example of using sandboxes within GitHub Actions in our HOT R.O.D repository.

Installing the Signadot GitHub App

The Signadot GitHub App enables enhanced integration with GitHub by displaying sandbox status updates directly within Pull Requests and managing automatic sandbox deletion.

Displaying Sandbox Status in GitHub PRs

Once the GitHub App is installed and configured, it will automatically comment on Pull Requests with sandbox status updates, including:

• Sandbox details: Name, routing key, preview URLs, associated route groups, and last update date.
• Smart Test execution results: Number of tests run with their status, a summary of detected Smart Diffs, and an overview of executed Checks.

Here you can see some examples of the generated comments:

This feature is enabled by default, but you can turn it off through the Signadot Dashboard under Settings > Integrations:

Automatic Deletion of Sandboxes

In the previous GHA workflow 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 PR is merged or closed.

The Signadot GitHub App can be used to tie a Sandbox to the lifecycle of a GitHub Pull Request. The Sandbox is automatically deleted when the Pull Request is closed.

Installation

To set up the integration with GitHub, you will need to initiate the integration workflow through the Signadot Dashboard under Settings > Integrations. This will guide you to install the Signadot GitHub application into your GitHub organization.

Once the integration has been set up, it can then be used in the sandboxes you create using Sandbox Labels.

note

If your GitHub organization has an IP allow list configured, the Signadot GitHub App must be whitelisted to function properly.

We automatically include the necessary exceptions in the app registration. However, if needed, you can manually add 54.202.35.48 to your organization's IP allow list. This is the currently designated public IP address from which the Signadot GitHub application operates.

For more details, see: Allowing access by GitHub Apps

Specification

Two special label keys can be used to specify the association with a GitHub pull request. These labels are:

Label Key	Value	Example
signadot/github-repo	path of github repository (org/repo)	signadot/community
signadot/github-pull-request	pull request number	"123"

Example

To make use of this integration, typically you will want to add the above template variables to the sandbox specification stored under .signadot in your repository. An example specification is written as shown below:

name: pr-xyz-@{github-pr}
spec:
  cluster: signadot-staging
  description: sandbox for @{github-pr}
  labels:
    signadot/github-repo: "github-org/github-repo"
    signadot/github-pull-request: "@{github-pr}"
  forks:
  - forkOf:
      kind: Deployment
      namespace: workspaces
      name: web
    customizations:
      images:
        - image: "myrepo/image:@{tag}"
  defaultRouteGroup:
    # ...

You may also invoke the same integration through the Signadot API by passing the same label parameters shown above.