Skip to main content
Stably integrates seamlessly into your CI/CD pipeline. Run tests automatically on every push or pull request, and use stably fix to automatically resolve failing tests with AI assistance.

​
Choose Your Approach

Your Own Runner

Run tests on your CI infrastructure (GitHub Actions, GitLab CI, etc.). You control the environment and pay for compute.

Stably Cloud Runner

Run tests on Stably’s scalable infrastructure. Run hundreds of tests in parallel without managing infrastructure.
FeatureYour Own RunnerStably Cloud
ParallelizationLimited by CI planUp to 100+ workers
SetupInstall browsers, manage depsJust add API key
CostPay your CI providerPay Stably (usage-based)
Best forSmall suites, custom environmentsLarge suites, fast feedback

​
Option 1: Your Own CI Runner

Run Stably CLI commands directly in your CI environment. This approach gives you full control over the test execution environment.

Setup Requirements

Before configuring your CI workflow, you’ll need credentials:
1

Get Your API Key

Go to the API Keys settings page and create or copy your API key.
2

Find Your Project ID

Navigate to your project in the Stably dashboard. The project ID is visible in the project settings or URL.
3

Add Secrets to CI

Add STABLY_API_KEY and STABLY_PROJECT_ID as secrets in your CI provider.GitHub: Settings → Secrets and variables → Actions → New repository secret
Never hardcode your API key in configuration files or commit it to version control. Always use your CI provider’s secret management.
.github/workflows/stably.yaml
name: Stably Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx stably install

      - name: Run tests
        id: test
        continue-on-error: true
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
        run: npx stably test

      - name: Fix failing tests (optional)
        if: steps.test.outcome == 'failure'
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
        run: npx stably fix

      - name: Fail if tests failed
        if: steps.test.outcome == 'failure'
        run: exit 1
The same commands work in any CI environment. See platform-specific guides:
CommandDescription
npx stably installInstalls Playwright browsers needed to run tests
npx stably testRuns your Playwright tests and reports results to Stably
npx stably fixUses AI to analyze and fix failing tests
For full CLI documentation, see the CLI Reference.
When you run stably fix in CI, it automatically detects which test run to fix. You don’t need to pass any ID or reference.Behind the scenes:
  1. stably test generates a unique run ID based on your CI environment (e.g., github-myorg/repo-123-1)
  2. stably fix detects the same CI environment and uses the matching run ID
  3. The AI analyzes the failures and suggests fixes
(Upcoming) If you run multiple test projects in the same CI job, use the --project flag to specify which one to fix:
npx stably test --project=smoke
npx stably test --project=e2e
npx stably fix --project=e2e  # Fix only e2e failures

​
Option 2: Stably Cloud Runner

For teams that need to run large test suites quickly, Stably offers a scalable cloud infrastructure that can run hundreds of tests in parallel.

Why Use Stably Cloud?

Massive Parallelization

Run up to 100+ tests simultaneously. A 2-hour test suite can complete in minutes.

No Infrastructure Management

No need to provision runners, manage browser installations, or scale capacity.

Consistent Environment

Tests run in a clean, consistent environment every time—no flaky failures from CI resource contention.

Built-in Retries

Automatic retries and smart failure analysis included.
If you’re using GitLab, CircleCI, Jenkins, or another CI platform, use the Stably API to trigger cloud runs:
# Trigger a cloud run
curl -X POST "https://api.stably.ai/v1/projects/${STABLY_PROJECT_ID}/runs" \
  -H "Authorization: Bearer ${STABLY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "projects": ["smoke", "regression"],
    "workers": 50
  }'
See the API Reference for full documentation.
Start with your own runner to get familiar with Stably, then consider Stably Cloud when your test suite grows and execution time becomes a bottleneck.

​
Troubleshooting

If stably fix fails due to missing dependencies or configuration issues, you need to run stably init on your repository first. This command sets up the necessary Playwright and Stably SDK dependencies.Solution:
  1. Run stably init locally in your repository:
npx stably init
  1. The AI agent will install and configure the required dependencies
  2. Commit the changes to your repository
  3. Re-run your CI pipeline
stably init only needs to be run once per repository. After the initial setup, stably fix will work in CI without any additional configuration.

​
Next Steps

CLI Reference

Full CLI command reference

GitHub Actions

Detailed GitHub Actions setup

Test Groups

Organize tests into projects

Alerting

Get notified on test failures