nocticas-action

# 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

1. **Author + pin a flow** in Nocticas (agentic run → pin → export the deterministic step script as JSON).
2. **Commit the gate** to your repo, e.g. `.nocticas/checkout-flow.json`.
3. **Add your key** as a repo secret: `NOCTICAS_API_KEY`.
4. **Add the workflow:**

```yaml
# .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`](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`](recipe.sh) and [`examples/gitlab-ci.example.yml`](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"`.