Configure sandbox profiles
Configure repository setup and startup scripts, build reusable filesystem snapshots, and inspect the sandbox profile Smart Gate uses for pull requests.
This feature is in Early Access. During this time, aspects of the functionality may still be developed, and this documentation may not always be up to date. If you have any questions, contact Statsig Support.
A sandbox profile defines how Smart Gate prepares a repository or folder for coding and verification. A profile build saves the repository, installed dependencies, and tools in a reusable filesystem snapshot. Customize a profile when your repository needs setup steps that automatic setup doesn't discover.
Open a sandbox profile
You need permission to edit Smart Gate settings and a repository connected through the Statsig GitHub App. If you haven't connected the repository, follow Set up Smart Gate.
- Open the Smart Gate settings from Settings > Integrations > Statsig GitHub App.
- On the Repositories tab, expand the repository and find the folder row you want to configure.
- In the Sandbox profile column, select Customize to create a profile or Configure to edit an existing profile.
- Select Configuration in the profile drawer.
A folder without its own profile can inherit a parent folder's profile. Select Save and build to give that folder its own profile. If the settings page says Save to customize, save your repository settings first. If profile controls aren't available, contact your Statsig account team.
Configure setup and startup scripts
Use the Setup script setting for toolchain installation, dependency installation, and required build or code-generation steps. The setup script runs during a snapshot build.
| Setup option | When to use it |
|---|---|
| Automatic | Let Smart Gate work out the installation steps from repository setup instructions and configuration. Start here unless your repository needs custom steps. |
| Script in the repository | Use a checked-in setup script, such as scripts/sandbox-setup.sh. |
| Inline script | Enter shell commands directly in the profile. |
Use the Startup script setting for work that each new sandbox needs after checkout, such as starting required services. Choose None, Script in the repository, or Inline script. Keep dependency installation in the setup script so Smart Gate can reuse the installed files from the snapshot.
Write scripts that work in the default Linux sandbox image. Make scripts safe to run again, and keep verification focused on the repository or folder the profile serves. Never put tokens, passwords, or other secrets in scripts or setup learnings. Organization members can read these values.
Build a snapshot
Select Save and build to save the profile configuration and start a snapshot build. The build uses the default sandbox image, checks out the repository, prepares the toolchain, verifies the setup, and captures the filesystem for later runs.
Setup verification checks whether tools can execute commands such as lint, typecheck, and focused tests. Existing source-code errors can still appear in those checks. A usable toolchain doesn't mean every check passes on every pull request.
To try configuration changes without changing the artifact Smart Gate uses, select Test build. Test builds retain their build details and logs, but Smart Gate doesn't use their artifacts for pull requests or save their new setup learnings. Select Save and build when you're ready to publish a reusable snapshot.
Inspect build results
Open the Builds tab in the profile drawer and select a build to inspect its details.
- Status and duration: Check the build status and how long the build takes.
- Usable until: Check the snapshot's expiration date. Rebuild the profile when its snapshot approaches expiration.
- Logs: Inspect setup, installation, verification, and capture output to diagnose a failed build.
- Source commit and scripts: Confirm which repository revision and setup configuration the build used.
- Snapshot details: Inspect the snapshot ID, size, and base image when you need to identify an artifact.
- Setup learnings: Read observations from the build. Successful saved builds can update the profile's read-only learnings for future builds.
Check the profile's active build indicator to confirm which snapshot Smart Gate selects. A newer build in the history doesn't necessarily replace the active snapshot.
How Smart Gate uses snapshots
Smart Gate restores a usable snapshot for the profile, checks out the pull request's code, and verifies the environment before coding. It can attempt repairs for requirements that differ from the saved snapshot.
A successful saved build can become the profile's active snapshot. Smart Gate checks that the snapshot matches the repository and folder and has enough usable lifetime remaining. It excludes expired snapshots and test-build artifacts. If the active snapshot is unavailable, Smart Gate looks for another compatible, usable snapshot.
If toolchain setup fails and the profile has no usable prepared snapshot, Smart Gate can retain a snapshot containing only the repository checkout. This reduces repeated cloning, but it doesn't provide verified lint, typecheck, or test tools. Smart Gate prefers a prepared snapshot when one is available. A failed build doesn't displace a usable prepared snapshot.
Was this helpful?
For AI agents: a documentation index is available at /llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.