GitHub pull-request previews

A throwaway environment for every pull request, with the link posted on the PR.

  1. In your repository open Settings, Webhooks, Add webhook.
  2. Payload URL and Secret are on the onboarding page and under Security, Access.
  3. Content type application/json. Events: Pull requests, and Pushes if you want the stale base warning described below.

When a pull request opens or updates, StrataCore queues a provisioning job for your agent. Closing the pull request removes the preview. Pull requests from forks never create a preview, because a preview runs the pull request's own files on your server.

What the agent does

Without any configuration, the agent clones the repository at the pull request commit, runs docker compose up for the compose file it finds (compose.yaml, compose.yml, docker-compose.yml or docker-compose.yaml), and labels every container so the console can track it. For a private repository set STRATACORE_GIT_TOKEN on the agent to a read-only token. If you define STRATACORE_PROVISION_CMD, your own hook runs instead; see Hooks.

This runs code from your repository on your server. Only enable previews for repositories you trust, and keep the Docker host separate from production.

A real URL for each preview

Point a wildcard DNS record for your preview domain at the server and install the agent with --with-proxy. The proxy listens on port 8080 and sends each host name to the matching preview. It speaks plain HTTP, so put your TLS terminator (Cloudflare, Caddy, nginx or a load balancer) in front of it. Each service must publish a port in the compose file, for example ports: ["3000"]. A sleeping preview is woken by the first request.

Sleep when idle

Previews that show no activity for the idle time sleep automatically (default 30 minutes; set 0 to disable under organization settings). Activity means CPU use or a request through the proxy.

The link on the pull request

Add a GitHub token under Security, Access and StrataCore posts one comment per pull request with the preview link and updates it as the preview changes. It also sets a commit status named stratacore/preview. Use a fine-grained token limited to the repositories you preview, with Pull requests and Commit statuses set to Read and write. Without a token the previews still work but are visible only in the console.

Stale base warning

A preview is built from the pull request branch. If the branch it will merge into later changes database or schema files, for example another pull request lands a migration first, the preview was never tested against that change. Select Pushes as well as Pull requests in the GitHub webhook and StrataCore marks the open previews that target that branch as stale. The pull request comment gets a note and a second commit status, stratacore/base-freshness, turns red. Rebase or merge the base branch into your pull request and push: once GitHub confirms the branch contains the base branch tip, the flag clears. That check needs the GitHub token; without one the flag stays until the pull request is closed.

  • It watches these paths: any migrations folder, db/migrate, schema.rb, structure.sql, prisma/schema.prisma, drizzle, alembic/versions and flyway.
  • It sees only the file lists GitHub sends with a push. It does not run migrations and cannot tell whether two migrations really conflict.
  • A push with 20 or more commits is flagged too, because GitHub may have cut the list.
  • To make it a merge gate, require the stratacore/base-freshness status in your branch protection rules.