GitHub Action
Run a suite on every pull request and get one aggregate check with a per-test table.
The mockingbird/run-suite Action runs a named suite and reports the result as one
aggregate PR check with a per-test pass/fail table and a link to the full suite run in the
app.
Basic usage
- uses: mockingbird/run-suite@v1
with:
api-key: ${{ secrets.MOCKINGBIRD_API_KEY }}
project: acme-store
suite: checkout-flowapi-key identifies the workspace; project and suite are the slugs shown in the app.
What it does
- Enqueues the suite via
POST /api/v1/runs, keyed to the commit and job attempt, so "Re-run job" re-tests instead of returning a stale result. - Polls until the suite reaches a terminal state (
passed,failed, orerror). - Writes a job summary: a test-by-status table and a single link to the suite run.
- Exits non-zero on
failed,error, or timeout, so the check goes red.
The check is informational by default. To make it block merges, add it to your branch-protection required checks.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
api-key | yes | none | Mockingbird API key (mb_live_...). Store in GitHub Secrets. |
project | yes | none | Project slug the suite belongs to. |
suite | yes | none | Suite slug to run. |
url | no | empty | Per-run base URL, such as this PR's preview deployment. Overrides the project base URL. |
headers | no | empty | JSON object of protection headers (basic auth or bypass token). Store the value in Secrets. |
base-url | no | https://app.mockingbirdai.com.au | Mockingbird app base URL. |
timeout | no | 900 | Max seconds to wait for the suite to finish. |
Targeting a preview deployment
Point the run at the PR's preview URL and pass a protection header so Mockingbird can reach it:
- uses: mockingbird/run-suite@v1
with:
api-key: ${{ secrets.MOCKINGBIRD_API_KEY }}
project: acme-store
suite: checkout-flow
url: ${{ needs.deploy.outputs.preview-url }}
headers: ${{ secrets.MOCKINGBIRD_PREVIEW_HEADERS }}headers is a JSON object, for example {"x-vercel-protection-bypass":"..."} or
{"authorization":"Basic ..."}. Store the whole value in a GitHub Secret.
Skipped tests
A test with no resolvable target URL is reported as skipped and is non-failing: it shows
in the table but never turns the check red. If every test is skipped, the summary calls it
out (0 tests ran) so a misconfigured suite cannot pass silently.
Requirements
The environment under test must be reachable from Mockingbird; per-run protection headers cover basic auth and bypass tokens, but there is no tunnel into private networks.