Preview and scratch projects

Two related ideas that both exist to keep experimental work away from work that matters.

Scratch projects#

A scratch project is a normal project you intend to throw away. Use one to try Coroid against an unfamiliar codebase, test a policy change before applying it broadly, or explore an approach you are not committed to.

The value is isolation. Experiments in a scratch project do not pollute the task history, metrics or context of a project your team relies on.

Delete them when you are done. A scratch project that survives six months has quietly become a real one, with none of the configuration care that implies.

Preview environments#

A preview is your changed application actually running, built from the branch a task produced.

This matters because some things cannot be established by reading a diff. Whether a page renders correctly, whether a flow works end to end, whether a change looks right — these need the thing running.

Previews are what browser tests run against, and what reviewers open when a screenshot would not settle the question.

Preview a task's change#

In the Factory, open a task that is waiting for review. Under What changed, the Preview window starts the task's branch with one click.

• Starting: the branch's dependencies install and the app starts. The first run can take a few minutes.
• Ready: the running app appears inside the window. Open shows it in a new tab, and the window says how long the preview has left.
• Stop ends it early. A preview that runs in Coroid stops on its own after an hour.

If the build fails, Retry starts it again and Show log shows what went wrong. A change with no web page to open, such as a backend or library change, shows Nothing to show in a browser instead of a button.

Starting a preview that is already starting or running opens the same preview, so two reviewers never start two copies.

Where a preview runs#

You do not choose where a preview runs:

• Coroid sandbox: the default. Coroid builds the task branch in an isolated container that gets none of your secrets. It needs no pull request and no push, so it also works for repositories that stay inside Coroid.
• Vercel: when the project has Vercel connected for direct deploy (project settings → Integrations → Review evidence), Vercel builds the branch and serves it at a Vercel preview address. Vercel's own deployment protection applies, so the preview opens in a new tab rather than inside the window.

A repository in local-only mode never leaves Coroid and always previews in the Coroid sandbox.

A preview address is long and unguessable, but anyone who has it can open the preview while it runs. Treat it like any link to unreleased work.

How previews reach your pull request#

The pull request Coroid opens for a task links to its preview: Preview this change in Coroid opens the task's review and starts the preview. The link needs a Coroid sign-in; the preview address itself is not posted on the pull request.

Where you already have preview deployments — from your hosting provider's Git app or your CI — Coroid also attaches them as review evidence, so the link appears alongside the change rather than somewhere you have to go looking.

The point is that verification evidence and the code it verifies should arrive together.

When to use which#

• Trying out Coroid, or an approach you may discard → scratch project
• Checking that a specific change behaves correctly → preview

They compose: a scratch project can have previews like any other.

Related#

• Create and configure a project
• Review evidence
• Review evidence providers