CI & GitHub Actions

Overview

Testral plugs into your existing pipeline with a small CI API. Create an API key once, then trigger a test plan from GitHub Actions, the Testral CLI, or a plain HTTP call. Plan runs execute on the plan’s configured cloud or host devices — not on your laptop’s desktop agent.

1. Create an API key

1. Open the desktop app → Integrations.
2. Under API keys, click Create key and give it a name (for example “GitHub Actions”).
3. Copy the key immediately — it is shown only once.

Store it as a secret named TESTRAL_API_KEY in GitHub (or your CI provider).

2. Create a test plan

In the desktop app, create a test plan with the tests and devices you want as a release gate. Prefer cloud or Mac-mini host devices so CI does not depend on a signed-in desktop session. Copy the plan’s ID from the plan detail URL or from testral plans.

3. GitHub Actions (recommended)

Add a workflow step after your app build:

- name: Run Testral plan
  uses: testral/run-plan@v1
  with:
    api-key: ${{ secrets.TESTRAL_API_KEY }}
    plan-id: your-plan-uuid
    wait: true

With wait: true (default), the job polls until the plan finishes and fails if the status is not passed. Outputs include plan-run-id, status-url, and pass/fail counts.

4. CLI (any CI)

Works the same on GitLab, Jenkins, CircleCI, Bitrise, Codemagic, and others:

export TESTRAL_API_KEY=testral_…
export TESTRAL_API_URL=https://api.testral.dev   # optional

npx @testral/cli plans
npx @testral/cli run --plan <plan-id> --wait

Exit code 0 means the plan passed; non-zero means failed, partial, or error.

5. HTTP API

All clients share these endpoints (Bearer token = API key or user JWT):

• POST /api/ci/plans/:planId/run — start a plan run (trigger: ci)
• GET /api/ci/plan-runs/:runId — status, summary, child test runs
• GET /api/ci/plans, GET /api/ci/projects, GET /api/ci/tests — discovery

curl -X POST "$TESTRAL_API_URL/api/ci/plans/$PLAN_ID/run" \
  -H "Authorization: Bearer $TESTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"branch":"main","commit":"abc123"}}'

MCP (authoring companion)

The Testral MCP server lets IDE agents list projects, read .tl tests, and kick off dry runs. Configure it with the same API key. Prefer the Action or CLI for merge gates — MCP is for authoring and debug.