Skip to content
ScreenCI

CI Setup

init can generate a ready-to-use GitHub Actions workflow that records the same way you do locally, using a repository secret and a deterministic CI environment.

You will learn

Generated workflow

Opting into CI during init writes .github/workflows/screenci.yaml at the repository root (the only place GitHub discovers workflows). Every step is scoped to your screenci/ directory via working-directory. An existing file is left untouched on re-run.

The workflow runs on pushes to main and on workflow_dispatch, installs Node.js 24 with dependency caching, installs the Playwright Chromium Headless Shell, and runs screenci preview --no-sync. It mirrors Playwright CI. Use push to keep previews current automatically, or workflow_dispatch for a manual, targeted run.

preview --no-sync re-records every requested video and updates the live previews. --no-sync keeps the CI checkout read-only: queued editor edits are not pulled into the sources there (edits drained on a throwaway CI runner would be lost); they stay queued for your next local preview or sync, and the step logs a short note when edits are pending.

Prefer final rendered videos instead of live previews? The generated workflow contains a commented-out alternative that swaps the record step for screenci export --no-wait. export re-records and starts the final renders; --no-wait exits right after the upload instead of waiting for rendering to finish and downloading the results, which keeps the CI job short (the finished renders are available in the ScreenCI app). Export minutes are spent on every video that renders in the run.

Required secret

Add SCREENCI_SECRET as a repository secret, from app.screenci.com/secrets. The workflow fails early if it is missing.

Recording your own app

If your videos navigate to a locally-running app via webServer in screenci.config.ts, the generated workflow needs two extra steps so the app is built and reachable when the record step runs.

Update screenci.config.ts

In CI, use a static serve command (npm run preview for Vite, or your framework’s equivalent) instead of the dev server. The dev server’s dependencies live in the root node_modules, which the generated workflow does not install by default. A built bundle also records more deterministically than a hot-reloading dev server.

webServer: {
  command: process.env.CI ? 'npm run preview' : 'npm run dev',
  cwd: '..', // path from screenci/ to the project root
  url: process.env.CI ? 'http://localhost:4173' : 'http://localhost:5173',
  reuseExistingServer: !process.env.CI,
  timeout: 120_000,
},
use: {
  baseURL: process.env.CI ? 'http://localhost:4173' : 'http://localhost:5173',
},

The port split (4173 for vite preview, 5173 for vite dev) is the Vite default. Adjust both values to match your framework’s preview and dev ports.

Update the generated workflow

Add install and build steps for the root app before the screenci install step, and extend cache-dependency-path to include the root lockfile:

- uses: actions/setup-node@v6
  with:
    node-version: 24
    cache: npm
    cache-dependency-path: |
      package-lock.json
      screenci/package-lock.json


- name: Install app dependencies
  run: npm ci


- name: Build app
  run: npm run build


- name: Install dependencies
  working-directory: screenci
  run: npm ci

The cache-dependency-path list tells actions/setup-node to include the root lockfile in its cache key, so restoring the cache reflects both dependency trees.

Keep recordings deterministic

ScreenCI records the browser in real time, so the recording reflects the CI machine’s speed. Recordings are most reliable when the environment is stable, feature flags and seeded data are fixed, authentication happens before visible recording, and visible waits are tied to UI state. Fix flaky timing in the script locally before pushing it to CI.

For faster, smoother recordings:

  • Run one worker. The generated config sets workers: process.env.CI ? 1 : undefined.

  • Use a faster runner. Recording is CPU- and GPU-bound; the free 2-core runners show the most pauses. See larger runners.

  • Keep setup in hide() so load and hydration time stays out of the recording.

  • Keep CI on the fast encoder (the init default). See Recording encoder.

    video.recordOptions({
      // Lightest encode on constrained CI runners; full quality locally.
      encoder: process.env.CI ? 'fast' : 'sharp',
    })('My video', async ({ page }) => {
      /* ... */
    })

Asset files do not need to be committed

Overlay images and videos and narration media (the files you reference with video.overlays(...) and narration media cues) are uploaded to ScreenCI the first time you record with the files present. On later runs they are reused: ScreenCI matches each asset to the version uploaded for the same video (by file path, or by overlay name) and reuses it.

That means you do not have to commit these (often large) media files to the repository. The screenci init scaffold gitignores the recordings/assets/ folder for exactly this reason. A typical flow:

  1. Record locally once with the asset files present. The recording uploads them.
  2. Keep the files out of git (or delete them). The committed .screenci.ts scripts still reference them by path.
  3. On CI, the files are absent. Recording does not fail: each missing asset is logged (for example Locally missing overlay, reusing the previously uploaded version) and reused from the previous upload.

If a referenced file is missing locally and no previously uploaded version exists for that video (for example a brand new overlay that has never been recorded with its file present), the upload fails with a clear message telling you to record once with the file present, or to commit it. This keeps a video from silently rendering without an overlay or narration clip.

Notes:

  • The match is per video and per project. Record a video at least once with each asset present so a version exists to reuse.
  • Overlays are matched by their declared name, so renaming an overlay (or its file) means the next record needs the file present again.
  • Custom voice sample files (the clip you clone a voice from) follow the same rule: record once with the sample present so it uploads, and later runs reuse the cloned voice from that upload even when the file is absent locally.
  • This is independent of .screenci/, which is always gitignored and holds the local recording output.

Reading back render status

When CI runs the export alternative, screenci export waits for renders and exits 0 only when every requested video rendered and downloaded, so a green export step means the videos are done. When the videos are consumed from the web instead of as files, screenci export --no-wait skips the wait and the download; the step then only verifies that recording and uploading succeeded. To read the results back later (or from another job), run screenci info: it reports each language’s render status (finished, rendering, or failed) and public URLs as JSON.

What’s next