Repository and CI

Every ScreenCI video is a Playwright E2E test. The scripts live wherever the agent that wrote them ran; ScreenCI keeps a snapshot so the next prompt can start from them on any machine. Engineering moves them where it wants them by running a prompt inside the repository (the agent commits the scripts next to the product’s code), and Add to CI makes your pipeline record the videos on every push. From then on a video that goes stale is a failed run, and nobody on the team records anything by hand.

This is the plain-language page for the engineering hand-off. The reference behind the generated pipeline, other providers, secrets, and deterministic recordings is CI Setup.

Why the video is a test

A .screenci.ts script drives the real app with Playwright: it clicks the real buttons, fills the real forms, and records the screen. When the product changes and the flow still works, re-running the script produces an up-to-date video with no human involved. When the flow breaks (a renamed button, a moved page), the script fails exactly like an E2E test, before a customer watches an outdated walkthrough. That only pays off when the script lives with the code and runs on every push, which is what the steps below set up.

Working from the repository

There is no separate step for getting the scripts into git. Run any prompt (Add video, Edit, Re-record) inside the repository of the app:

screenci setup <code> uses the repository’s screenci/ workspace when it has one. When it has none, the command pulls the snapshot ScreenCI holds into <repository>/screenci (or scaffolds a new project there).
The agent does the task and records the preview from that workspace.
The agent commits screenci/ on a branch and opens a pull request (or pushes to the default branch when the repository allows it). Review it like any other change.

Every preview and export uploads a snapshot of the workspace’s text files (config and scripts; never env files, lockfiles, or media), so the video page shows the sources behind each version and a prompt run somewhere else starts from them. Inside the repository the repository’s scripts always win: the brief only lists where the version the prompt was made from differs, and --force pulls that version’s files on request. A monorepo may keep the workspace under a package (apps/web/screenci); setup finds it by the projectId in its config from anywhere in the repository. A project whose scripts must not leave the repository sets uploadSources: false in screenci.config.ts; its prompts must then run inside the repository, where the agent finds the scripts.

Working with teammates who do not have the repository

The usual sequence: a teammate makes the first video from a plain folder, against the live site. An engineer runs Edit inside the repository; the scripts get pulled into screenci/, pointed at the dev server (webServer in screenci.config.ts), committed. The teammate clicks Add video or Edit again on their own machine: setup pulls the version’s scripts, sees they name a dev server the machine cannot start, and has the agent point that video at the live site by hand (video.use({ baseURL }), no dev server for the run) and check that the data the flow expects exists there. The preview lands as a new version, and whoever exports picks the version that serves. Your next Edit inside the repository keeps the repository’s config, so the dev server setup is never lost. Keep the project’s site URL filled in (see AI context) so the swap needs no one’s attention, and write navigations as paths relative to the base URL so the same script records in both places without edits.

Bringing a teammate’s changes into CI

A video whose newest script was recorded on someone’s computer shows Not in CI next to its title; one whose newest script is the one CI recorded shows In CI. ScreenCI compares the script each recording was made from, so a local preview of an unchanged script still counts as in CI.

When a teammate changes a video’s steps on their own machine (or makes a new one), the video page offers Request CI update. It saves the request, with an optional note, and copies a short message with a link to the page, ready to paste into Slack or email. The video shows Needs dev until the change lands.

The developer opens the link and clicks Update in CI (or Add to CI for a new video). That copies a prompt for their coding agent. Run inside the repository, screenci setup <code> --force writes the scripts of the teammate’s recording into screenci/ (it refuses when the workspace has uncommitted changes), and the agent reviews git diff: the teammate’s copy may predate recent commits, so only the changes the video needs stay. The agent previews and opens a pull request. When CI records the merged script, the request closes by itself and the badge turns to In CI. A scheduled re-record of the old script leaves it open.

The teammate’s sign-in stays on their machine. screenci login opens a browser where they sign in themselves; the session is saved under .screenci/auth/ and is never uploaded, and neither are env files or any storageState file. See Signing in.

On Windows, the copied commands use npx.cmd: PowerShell resolves plain npx to a script its default execution policy refuses to run, while npx.cmd works in both PowerShell and Command Prompt.

Add to CI

The button appears on the project and video pages until CI records the project. It needs no description; an optional note under Advanced tells the agent what it cannot see (“we use GitLab CI, the app needs a build step”).

The agent:

Mints a CI key for the project (named CI: <project> on the Secrets page; delete it there to cut CI off).
Stores it as SCREENCI_SECRET in your CI provider’s secret store.
Adds a pipeline: screenci ci-workflow writes the GitHub Actions workflow, and the templates under Other providers cover GitLab CI, CircleCI, Buildkite, and a plain shell script.
Commits on a branch, pushes, and triggers the first run. That run uploads its recordings as the project’s CI preview, and the tab that made the prompt opens the first video.

A repository without a screenci/ workspace yet gets the snapshot ScreenCI holds pulled into it, committed together with the pipeline, so Add to CI alone is enough. When the pipeline must sign in to your app, see Signing in from CI.

What a pipeline run costs

Recording and live previews are free on every plan; only rendered exports count against the plan’s quota. The generated pipeline runs screenci preview, so a push that re-records every video costs nothing, and the previews are there to watch and edit in the browser. Switch the pipeline to screenci export --select (see CI Setup) only when you want each release to publish rendered videos automatically; then each changed video renders once per release. Either way the cost follows the videos you publish, not the number of runs.

Record all and Re-record

Record all (project page) and Re-record (video page and every video card) record again with the scripts as they are. They look the same for everyone on the team, and do the right thing for the project:

When the repository is linked through the ScreenCI GitHub App, one click dispatches the recording workflow and the page shows the run’s progress.
Otherwise the button produces a prompt. The agent triggers your pipeline when CI records the project, and records on its own machine when nothing does.

Either way the script is only touched where the product changed underneath it; narration, overlays, and editor changes stay.

Trigger recordings remotely

Two things start a recording without anyone opening a terminal:

A push. The generated workflow runs on every push to the default branch, so shipping the feature re-records its videos.
The Record all prompt on the project page. Your coding agent triggers the workflow with workflow_dispatch (gh workflow run screenci.yaml).

For providers without a dispatch API, a push to the recording branch or the provider’s own run button does the same. See GitHub Actions for the workflow file.

When a run fails

A failed recording run is the stale-video alarm. The run page in the web app shows which video failed and the Playwright error. Fix it the way the team prefers:

Edit on the video page with one sentence (“the invite dialog moved to the members page; update the flow and keep the narration”). The agent changes the script, opens a pull request, and records a preview.
Or fix the .screenci.ts file directly; it is a normal Playwright test in your repository. See Video script basics.

Merge, push, and the pipeline records the fixed video. The video’s public URL keeps serving the last selected version until you select the new one (or the pipeline runs export --select), so a broken run never publishes a broken video. See Version history.

What’s next

CI Setup for the workflow file, other providers, secrets, and deterministic recordings.
Start in a repository when you would rather begin from the code than from the web app.
Make videos by prompt for how the rest of the team uses the same videos from the web app.