Signadot Sandbox GitHub Action: A Sandbox per Pull Request

The Signadot Sandbox GitHub Action is now available on the GitHub Marketplace. Version 0.1.0 adds a Signadot Sandbox to any GitHub Actions pull request workflow in a single step. Point it at the workloads your pull request changes and the images you built. Each pull request then gets its own Sandbox in your existing Kubernetes cluster, running the changed services alongside everything else already deployed there.

A Signadot Sandbox is a lightweight ephemeral environment that runs in your cluster and provides a realistic runtime for verifying changes pre-merge. The forked services run against real upstream and downstream dependencies, while everything the pull request doesn’t touch keeps running on the shared stable versions in the cluster.

Teams have always been able to create Sandboxes from CI with the Signadot CLI. The Action packages the whole flow (the spec, the name, the labels, the cleanup, and the outputs your tests need) into one step, so adding Signadot to a GitHub repository takes a few lines of YAML.

What the Action does

Installs a checksum-verified Signadot CLI for you.
Checks the spec before anything is created, with errors that name the problem.
Creates a Sandbox for every pull request from a few inputs: the workloads to fork and the images to run in them. The common case needs no spec file.
Keeps one Sandbox per pull request. The name comes from the PR, so every push updates the same Sandbox instead of creating a new one.
Forks one service or many. A single image pattern names the image for each fork, and monorepos can fork only the services a pull request touched.
Works with the spec templates you already have, adding what the workflow knows without editing your file.
Hands your tests and reviewers what they need: a routing key, a link to the Sandbox in the Signadot dashboard, and preview URLs for the endpoints you name.
Returns the rendered Sandbox spec as YAML, for troubleshooting or, with dry-run, for checking what it would apply during integration without creating anything.
Cleans up when the pull request closes through the Signadot GitHub App, with a TTL or an explicit delete step available when you want more control.

One step to start

Here’s the smallest step that works, followed by a test that sends a request to the Sandbox:

- uses: signadot/sandbox-action@v0.1.0
  id: sbx
  with:
    api-key: ${{ secrets.SIGNADOT_API_KEY }}
    org: acme
    cluster: stage-eks
    fork: kind=Deployment,namespace=hotrod,name=route
    image: ghcr.io/acme/route:${{ github.sha }}

- run: |
    curl -H "baggage: sd-routing-key=${{ steps.sbx.outputs.routing-key }}" \
      https://hotrod.internal/dispatch

The step doesn’t set a name. The Action derives one from the pull request as <repo>-<n>, so this Sandbox is hotrod-42 on PR #42, and the second commit updates it in place. Requests that carry the routing key reach the forked route service, and everything else they call runs on the shared stable versions.

Preview URLs aren’t created by default. Add an endpoints input naming the service reviewers should open, and the Action returns a preview-url: a hosted URL that routes to the Sandbox, so reviewers don’t need to set a header.

When the pull request closes, merged or not, the Signadot GitHub App deletes the Sandbox. It finds the Sandbox through two labels the Action stamps on every pull request run, and it also comments the Sandbox’s details on the pull request. If you don’t use the App, a ttl or the delete sub-action handles cleanup instead.

Many services, one line each

A pull request in a repository that builds two services forks both. fork takes one line per workload, and when your images follow one naming convention, you state it once:

fork: |
  kind=Deployment,namespace=hotrod,name=route
  kind=Deployment,namespace=web,name=frontend
image: ghcr.io/acme/{workload}:{sha}

The Action fills in {workload} per fork, so route and frontend each get their own image from one line. For monorepos, fork also accepts a JSON array computed by an earlier step. A path filter can then fork only the services a pull request touched, while everything else routes to the shared stable versions in the cluster.

Environment variables follow the same pattern: a plain KEY=VALUE line applies to every fork, and a route:KEY=VALUE line applies to one. The resources input provisions things like a per-Sandbox database through a resource plugin.

Bring the spec you already have

Teams already running Signadot in CI usually have a spec template committed under .signadot/. Point the Action at it with template-file:

- uses: signadot/sandbox-action@v0.1.0
  with:
    api-key: ${{ secrets.SIGNADOT_API_KEY }}
    cluster: stage-eks
    template-file: .signadot/sandbox.yaml
    set: |
      image=ghcr.io/acme/route:${{ github.sha }}

The CLI renders the template with the same @{var} language you use today. The Action then adds what the workflow knows: the PR-derived name, the cluster, and the labels the GitHub App reads. It never edits your file. A name written in your template wins over the derived one, so adopting the Action doesn’t retarget a Sandbox you already have. To use the derived name, write name: '@{name}' and the Action binds it for you.

The flat inputs cover what most pull request Sandboxes need. For everything else a Sandbox spec can say, such as a Kubernetes patch on a forked workload, you bring the document, either as a template or as a full spec your workflow builds. That split is deliberate. A field added to the Sandbox spec works through the Action the day it ships, without waiting for a new input to mirror it.

Three rules behind the design

The interface is small, with 21 inputs and six outputs, and three rules shaped how it behaves.

Nothing is inferred

Every fork line names its kind, namespace, and name. There’s no default workload kind to guess wrong, so a team running Argo Rollouts never gets a silent Deployment.

Nothing degrades silently

When an input and your document disagree, the step either fails and names both sides or warns and names the input it ignored. It never picks one quietly. The Action also checks the assembled spec before anything is submitted and before any credential is used.

A document you own stays yours

If you already have a Sandbox spec, the Action adds what the workflow knows and touches nothing else.

Get started

Add your API key as a SIGNADOT_API_KEY secret, drop the step above into a pull_request workflow, and open a PR. If you already have a Sandbox spec, run template-file with dry-run: true to see what the Action would do with it. The step returns the spec it would apply as the rendered-spec output, and nothing is created.

This release is built for pull_request workflows, and branch support, with a Sandbox name that stays stable across pushes, is on the roadmap. We welcome feedback and issues. If there’s an input you expected and didn’t find, open an issue in the repository.

The Signadot GitHub Action Is Live