How to set up Continuous Integration (CI) testing

The Liveblocks dev server lets you run your end-to-end tests in CI without needing Liveblocks credentials, and without usage limits. Your tests behave identically whether you run them locally or in CI.

What we’re setting up

You’ll run the Liveblocks dev server as a service container in your GitHub Actions workflow. Your app connects to http://localhost:1153 instead of Liveblocks production, using the built-in "sk_localdev" secret key. No production credentials required.

Step 1: Add a test environment file

Most frameworks automatically load a .env.test file when running tests. Create one with the dev server values:

LIVEBLOCKS_SECRET_KEY=sk_localdev
# Depends on your frameworkVITE_LIVEBLOCKS_BASE_URL=http://localhost:1153         # For ViteNEXT_PUBLIC_LIVEBLOCKS_BASE_URL=http://localhost:1153  # For Next.js

Since these are well-known dev-only values, it’s safe to commit this file to your repository.

Step 2: Reference the environment variables

In your client, read the base URL from the environment variable:

const client = createClient({  baseUrl: process.env.NEXT_PUBLIC_LIVEBLOCKS_BASE_URL || undefined,  authEndpoint: "/api/liveblocks-auth",});

In your Node backend, read both the base URL and secret:

const liveblocks = new Liveblocks({  baseUrl: process.env.NEXT_PUBLIC_LIVEBLOCKS_BASE_URL || undefined,  secret: process.env.LIVEBLOCKS_SECRET_KEY!,});

When these variables are not set, your app connects to Liveblocks production as usual.

Step 3: Add the GitHub Actions workflow

Use the services block to run the Liveblocks dev server as a service container. GitHub Actions starts it automatically before your steps run, and your tests can connect to it on localhost:1153.

name: My app tests
on: [push, pull_request]
jobs:  test:    runs-on: ubuntu-latest    services:      liveblocks:        image: liveblocks/dev-server        ports:          - 1153:1153
    steps:      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4        with:          node-version: 20
      - run: npm ci
      - name: Run tests        run: npm test

That’s it! The service container provides the dev server, and the .env.test file supplies the configuration. No additional setup needed.

What to read next

• Dev server reference
• Get started with the dev server