Nocticas E2E Gate — GitHub Action
Run a pinned Nocticas gate against a target URL on every push/PR, and fail the build on a red verdict. The browser runs on Nocticas's servers — this Action is a thin client that starts the run, polls for the verdict, and maps it to an exit code. No false greens: a harness error is never treated as a pass.
Quickstart
- Author + pin a flow in Nocticas (agentic run → pin → export the deterministic step script as JSON).
- Commit the gate to your repo, e.g.
.nocticas/checkout-flow.json. - Add your key as a repo secret:
NOCTICAS_API_KEY. - Add the workflow:
# .github/workflows/nocticas.yml
name: Nocticas E2E gate
on: [pull_request, workflow_dispatch]
jobs:
verify:
runs-on: ubuntu-latest # standard runner = free on public repos
steps:
- uses: actions/checkout@v4 # so the gate file is available
- uses: Low-Latency-Labs/nocticas-action@v1
with:
api-key: ${{ secrets.NOCTICAS_API_KEY }}
gate: .nocticas/checkout-flow.json
target: ${{ vars.PREVIEW_URL }} # your deployed preview/staging URL
A red verdict fails the job → blocks the PR/merge.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
api-key | yes | — | Your Nocticas API key (store as a secret). |
gate | yes | — | Path to the pinned gate JSON (array of deterministic steps) in your repo. |
target | yes | — | URL to test (e.g. the PR's preview deploy). |
api-base | no | https://app.nocticas.com/api | Nocticas API base. |
timeout-seconds | no | 300 | Max wait for a verdict. |
poll-seconds | no | 3 | Poll interval. |
fail-on-error | no | true | Treat a harness error (not a test fail) as a build failure. An unverified run is never a pass. |
Outputs
| Output | Description |
|---|---|
run-id | The Nocticas run id (link it in your logs). |
verdict | passed | failed | error | timeout. |
The gate file
A JSON array of deterministic steps — exactly what Nocticas produces when you pin a passing run. Example in examples/gate.example.json. Keeping it in your repo means your E2E test is version-controlled alongside the code it guards.
Don't commit real credentials. Point the gate at a staging/preview target and use a dedicated test account; Nocticas's built-in test inbox handles OTP/magic-link logins so you don't need to embed secrets in the gate.
Cost
- Publishing this Action: free (public repo, no paid plan).
- Running it (your customers): free on public repos with standard runners; within the monthly free-minutes allowance on private repos. It's a single thin job — seconds of runner time.
- The browser run: billed in Nocticas credits — and deterministic/pinned runs are free within your monthly allowance, so gating every push typically costs nothing in credits.
Other CI systems (the recipe)
Not on GitHub? The same start → poll → exit logic is a portable script — see recipe.sh and examples/gitlab-ci.example.yml. The contract is just JSON over HTTP:
POST {api-base}/runs { "mode":"deterministic", "target": "...", "script": [ ...gate... ] } → { "id": "..." }
GET {api-base}/runs/{id} → { "status": "passed|failed|error|..." }
Header: x-nocticas-key: <key>. Exit non-zero unless status == "passed".