Skip to main content

Set up Pull Request Sandboxes

Overview​

Setting up automated sandbox environments for pull requests enables teams to shift testing earlier in the development process. This improves code quality by catching integration issues before changes reach shared environments.

Key benefits include:

  • Automated Previews: Enable teams to preview changes before merging
  • Streamlined Integration Testing: Ensure changes work well with the existing system
  • Efficient E2E Testing: Support comprehensive testing of the entire application flow

Implementation Steps​

1. Define the Sandbox Infrastructure​

A sandbox specification defines the test workloads and routing configuration. For example, to test a new version of a microservice route that has a baseline deployment in the hotrod namespace:

name: route-sbx
spec:
  cluster: my-cluster  # name of cluster (as per app.signadot.com)
  description: sandbox for route microservice
  labels:
    team: route-team
    # ...any other metadata
  ttl:
    duration: 1d
  forks:
  - forkOf:
      kind: Deployment     # With respect to the baseline environment, this 
      namespace: hotrod    # forks (clones & customizes) route only. 
      name: route      
    customizations:
      images:                       
      - image: repo/image:abcdef    # new version of the image

Verify the configuration by applying it with the CLI and confirming it reaches ready state.

This example shows a basic customization that updates only the container image. For more advanced configurations, refer to the sandbox reference.

2. Create a Reusable Template​

Transform the sandbox specification into a template that can be used across multiple pull requests and services:

name: "@{service}-@{pr}"
spec:
  cluster: my-cluster  # name of cluster (as per app.signadot.com)
  description: sandbox for @{service} microservice
  labels:
    team: "@{service}-team"
    # ...any other metadata
  ttl:
    duration: 1d
  forks:
  - forkOf:
      kind: Deployment
      namespace: "@{namespace}"
      name: "@{service}"      
    customizations:
      images:                       
      - image: "@{image}"

The template uses variables (@{...}) that are populated at runtime:

signadot apply -f ./my-sbx-template.yaml \
    --set namespace=hotrod \
    --set service=route \
    --set image=repo/image:abcdef
    ...

This approach enables consistent sandbox creation across different services and pull requests.

3. Automate with CI/CD​

Integrate the template into your CI/CD pipeline to automatically create sandboxes for each pull request.

For implementation details specific to your CI/CD system, see the guide on integrating with CI/CD.

Infrastructure Best Practices​

Template Management​

Consider these approaches for managing sandbox templates:

  • Centralized Repository: Store templates in a central infrastructure repository or monorepo (example)
  • Service-Specific Templates: Create specialized templates for services with unique requirements
  • Dynamic Generation: Generate templates programmatically within CI/CD pipelines

Example repository structure:

- signadot/
  ├── sandbox-template.yaml      # Generic template
  ├── route-sandbox-template.yaml  # Service-specific template
  └── frontend-sandbox-template.yaml

Templates can be updated post-creation via CLI or UI for dynamic changes like environment variables.

Workload Organization​

Consider these patterns for organizing workloads:

  • Single Service: Deploy one service per sandbox for maximum flexibility
  • Service Groups: For tightly coupled services, create templates that deploy related services together
  • Route Groups: Use Route Groups to combine multiple sandboxes when testing service interactions

The single-service approach provides the most flexibility, as Route Groups can dynamically combine sandboxes as needed.

Conclusion​

A well-designed sandbox infrastructure enables teams to catch issues early through automated previews and testing. Following these patterns helps create a scalable and maintainable sandbox environment that improves the overall development workflow.