Monito CLI

Run browser tests in CI

Run Monito tests from GitHub Actions with OIDC, verify the workflow, or trigger tests in the background through a deploy webhook.

Choose an integration

Use the CLI when the pipeline should wait for results and fail on test failure. Use a deploy webhook when a deployment should trigger Monito in the background and leave results in the dashboard.

Set up CI with an AI agent

After two one-time browser sign-ins, your AI coding agent can set up the complete GitHub Actions integration for you. You do not need to create, copy, paste, or store a Monito API key in GitHub.

monito auth login
gh auth login

Tell the agent which Monito project to use. For example:

Set up Monito GitHub Actions for this repository using the Storefront project. Run the plan first, then apply and verify it. Do not expose credentials.

For a blocking check after a successful GitHub deployment, the agent can run:

monito ci plan --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --json
monito ci apply --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --yes --json
monito ci verify --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --remote-auth --json

The three commands have separate responsibilities:

  1. plan inspects the Monito project, scenarios, GitHub repository, and existing workflow. It makes no changes and returns the exact artifact and operations as JSON.
  2. apply writes .github/workflows/monito.yml and registers a project-scoped trust binding for the repository's immutable ID, owner ID, workflow ref, triggers, and environment. Re-running the command is safe.
  3. verify confirms that the generated workflow and exact trust binding are present. --remote-auth dispatches a correlated auth-only job and proves the OIDC exchange without running scenarios or spending credits.

At runtime, GitHub issues a short-lived OIDC token to the bound workflow file: at the default-branch ref, at the deployed commit for deployment_status, or at a pull request's merge ref for pull_request. The CLI keeps that token in memory and never prints or persists it. The token permits only CI status and run operations for the bound project: it can launch that project's tests against any of its environments or a base URL override, and read that project's runs. Saved logins stay bound to their approved origins.

A pull_request run uses the workflow file from the pull request, so anyone who can push a branch to the repository can get that access and spend the project's credits. The generated workflow skips fork pull requests. GitHub gives fork pull requests no OIDC token unless an admin of a private or internal repository turns on Send write tokens to workflows from pull requests; keep that setting off in a repository bound to Monito.

The CLI refuses to overwrite a workflow it did not generate. It also requires --yes before any credential or repository mutation.

After static verification, ask the agent to commit and push .github/workflows/monito.yml using your repository's normal Git workflow. The CLI does not create commits or push code. Once the workflow is on the repository's default branch, dispatch it to prove the setup works end to end:

monito ci verify --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --run --yes --json

Dispatching a workflow runs the project's scenarios and spends Monito credits, which is why it requires explicit confirmation.

GitHub Actions with the CLI

Open your project in the dashboard, select Automations, then choose GitHub Actions. The setup screen shows the live repository trust binding and generates the OIDC workflow with the correct project ID. The repository secret status should read Not required. The dashboard's workflow runs project run --wait --github-summary without the GitHub check and PR comment; the CLI's version below adds them.

monito ci apply --execution blocking --auth oidc --project project_123 --yes generates this workflow for a repository whose default branch is main:

# Generated by Monito CLI
# Project: project_123
name: Monito QA
run-name: Monito QA ${{ inputs.verification_id || github.sha }}

on:
  workflow_dispatch:
    inputs:
      auth_check:
        description: Verify the Monito credential without running tests
        required: false
        type: boolean
        default: false
      verification_id:
        description: Correlates an automated credential check
        required: false
        type: string
  pull_request:
  push:
    branches:
      - "main"

permissions:
  checks: write
  pull-requests: write
  contents: read
  id-token: write

jobs:
  monito:
    if: >-
      (github.event_name != 'pull_request' ||
      github.event.pull_request.head.repo.full_name == github.repository)
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      GITHUB_TOKEN: ${{ github.token }}
      MONITO_GITHUB_OIDC: "1"
      MONITO_PROJECT_ID: "project_123"
      PROJECT_ID: "project_123"
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Verify Monito credential
        if: ${{ inputs.auth_check }}
        run: npx -y @monitodev/cli@4 auth status --json

      - name: Run Monito project
        if: ${{ !inputs.auth_check }}
        run: npx -y @monitodev/cli@4 project run "$PROJECT_ID" --wait --github-summary --github-check --github-comment

project run exits with code 1 when any scenario fails or errors. --github-summary writes the job summary, and --github-check publishes a Monito check on the PR head or deployment SHA with result counts and failing tests linked to evidence.

The check is success when every test passed and no requested verification was rejected. It is neutral when every test that didn't pass errored for a reason Monito caused (outcome cause monito_error), or when the CLI times out or stops before it collects every result. Anything else is failure: a failed test, an error with another cause, or a rejected verification. Failed or errored tests still produce CLI exit code 1.

--github-comment creates one PR comment on failure and updates it in place, using the hidden marker <!-- monito-qa -->. A later pass changes the existing comment to All N tests passed; a pass never creates a comment. The PR number comes from the GitHub event or pull ref, or an explicit --pr <number>. Deployment events without PR context need --pr for comments. Both flags require waiting and GITHUB_TOKEN; GitHub API errors only warn and never change the run's exit code.

Long-lived API-key authentication remains available only as an explicit compatibility path for runners that cannot use GitHub OIDC:

monito ci plan --execution blocking --auth api-key --project "Storefront" --json

This mode stores MONITO_TOKEN as a GitHub secret. Prefer OIDC for new GitHub Actions integrations. The lower-level monito auth create-key command prints a credential and is not the agent-safe setup path.

Use the Marketplace action

Coming soon: monito-dev/run-action will be public once the action is listed on GitHub Marketplace. It wraps the CLI project run with waiting and GitHub reporting enabled:

- uses: monito-dev/run-action@v1
  with:
    project-id: project_123

Replace the generated setup and run steps with this step, keeping the job permissions and environment. The OIDC binding must match the workflow file that calls the action, its trigger and its ref; create it with monito ci apply --workflow .github/workflows/monito.yml and the setup options above before editing that file. Pull request runs of that workflow use the same default-branch binding. For runners that can't use OIDC, pass api-key: ${{ secrets.MONITO_TOKEN }} to the action instead.

Test every preview deploy

To QA every preview deployment, point a deployment-triggered workflow at the ephemeral preview URL using the settings of a dedicated environment. Use flows without a login; selecting an environment does not approve its logins on new preview origins.

First create a Monito environment for your preview settings — for example, name it Preview. Then opt in to the preview trigger:

monito ci plan --execution blocking --auth oidc --trigger deployment --preview \
  --environment Preview --project "Storefront" --json
monito ci apply --execution blocking --auth oidc --trigger deployment --preview \
  --environment Preview --project "Storefront" --yes --json

--preview is opt-in and never enabled by default: firing Monito on every preview deploy spends credits, so you enable it explicitly. It gates the workflow on preview deployments — the --environment you name, defaulting to Preview — and generates a run step that:

  • forwards the deployed URL as the run's base URL with --base-url "${{ github.event.deployment_status.target_url }}", and
  • selects the Monito environment with --env "Preview". This does not authorize its logins on a new preview origin.

Vercel's GitHub integration already posts each preview deploy as a GitHub Deployment Status with the preview URL in deployment_status.target_url, so the generated workflow picks it up with no extra configuration and no native Vercel integration required. --environment should match the GitHub deployment environment your provider reports (Vercel uses Preview).

That generated workflow reads a GitHub deployment_status event. Netlify's docs describe commit statuses, commit checks, and pull request comments for Deploy Previews, not that event. Use the Netlify integration for a Deploy Preview URL or a deploySucceeded function that calls the deploy webhook.

--base-url overrides only the target origin for that run; scenario paths and credential origin approvals are unchanged. On Vercel preview URLs, only flows without a login can run: logins are bound to exact HTTPS origins, so tests that need a login fail closed on previews. Selecting --env "Preview" does not approve each new deployment URL. To run against a preview URL by hand — for example from a script or another CI system — pass both flags to project run:

monito project run <project-id> --base-url https://your-app-git-branch.vercel.app --env Preview

Vercel deployments

To run previews directly from Vercel without GitHub Actions YAML, open your Monito project's Automations → Deploy webhook panel and choose Vercel (Monito Pro).

  1. Copy the Vercel webhook URL shown in Monito.
  2. In Vercel, open team Settings → Webhooks, select the Deployment Succeeded deployment event and scope it to the matching Vercel project. Paste the Monito URL and create the webhook. Account webhooks require Vercel Pro or Enterprise; see Vercel's webhook setup.
  3. Copy the signing secret Vercel displays into Monito. Choose the suite and Monito environment whose settings should apply, then click Save Vercel webhook.

On preview URLs, only flows without a login can run. Logins are approved for exact HTTPS origins, and each Vercel deployment URL is a new origin. Tests that need a login fail closed on previews; choosing an environment does not extend its login approvals. On previews, tests that need a login cannot sign in and still use credits, so choose a suite of flows that work without a login.

Only ready preview deployments launch runs. Production and other events are ignored. The suite runs against the deployment URL with PR, commit and branch context when Vercel supplies it. Repeated deliveries of the same deployment do not start another suite. Runs use the usual Monito credits and notification settings; this background webhook does not block deployment completion. Previews on a custom Preview Deployment Suffix are not supported yet; deployment URLs outside .vercel.app are ignored.

There is one deploy webhook per Monito project. Saving Vercel replaces the generic webhook and invalidates its bearer secret. The Vercel signing secret is encrypted and never shown after saving. To replace it, paste the new Vercel secret and save; use Disable to disconnect, or the automation's pause control to stop launches. The first verified preview delivered after setup links the hook to one Vercel project, so the Vercel webhook should cover only this project. Other projects are ignored. The form shows the linked project name and ID; select Reset linked project on save and save the signing secret again to let the next verified preview delivery link a different project. monito ci configures the GitHub workflow path; use this panel for native Vercel events.

Protected previews

Vercel Deployment Protection blocks Monito's browser unless you configure a bypass. The webhook signing secret authenticates events; it does not bypass the preview's protection. Create a separate bypass secret in the Vercel project's Settings → Deployment Protection → Protection Bypass for Automation.

Use Vercel's query-parameter bypass on each test's starting path, for example:

/login?x-vercel-protection-bypass=YOUR_BYPASS_SECRET&x-vercel-set-bypass-cookie=true

The cookie option allows subsequent browser navigation. The preview override keeps the test path and query parameters; a query on the environment base URL or webhook URL does not configure this browser bypass.

The bypass secret becomes part of the test's URL, so it goes to every environment that test runs on. It appears in run records and the agent's context, and it grants access to every protected deployment of that Vercel project. Treat test URLs containing bypass secrets as sensitive.

Environment request headers, which keep the secret out of the test, are coming.

Inspect results and remove CI

Run lists are compact by default and can be scoped to one project. Full logs are opt-in:

monito run list --project <project-id> --json
monito run list --project <project-id> --include-logs --json

To remove the integration, run cleanup once without --yes and review every operation. Apply only after confirming the exact binding and legacy credentials belong to this setup:

monito ci cleanup --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --json
monito ci cleanup --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --yes --json

Cleanup removes only the exact Monito-owned binding and deterministic legacy secret or key. Unknown keys are preserved and reported for manual review. You can also disconnect GitHub Actions or disable the deploy webhook from the project's Automations screen; historical runs remain available.

Deploy webhook

Open your project in the dashboard, select Automations, then choose Deploy webhook. Generate the first secret and store the provided MONITO_WEBHOOK_URL and MONITO_WEBHOOK_SECRET values in your deployment platform.

An AI agent can also configure these as GitHub repository secrets without seeing either value:

monito ci plan --execution webhook --trigger deployment --project "Storefront" --json
monito ci apply --execution webhook --trigger deployment --project "Storefront" --yes --json
monito ci verify --execution webhook --trigger deployment --project "Storefront" --json

CLI 4 still accepts --mode github-actions and --mode deploy-webhook as deprecated aliases. New automation should use separate --execution and --trigger flags so post-deployment blocking checks are not confused with asynchronous webhooks.

If a webhook is already active but GitHub is missing its secrets, the CLI blocks instead of silently rotating the credential. Review the plan, then explicitly add --rotate to apply. Rotation invalidates the previous secret immediately.

If rotation succeeds but GitHub secret installation fails, the CLI writes the new values to a local mode-0600 recovery file and returns only that file's path. The agent should report the path without reading or printing the file so you can recover the credentials manually.

To rotate the secret from an authenticated shell instead:

MONITO_SESSION_TOKEN=$(monito auth token)
curl -fsS -X POST "https://www.monito.dev/api/projects/$PROJECT_ID/hooks/rotate" \
  -H "Authorization: Bearer $MONITO_SESSION_TOKEN"

The response contains webhookUrl and webhookSecret. Rotation invalidates the previous secret immediately, so update the deployment before its next trigger.

Trigger the webhook after deployment:

curl -fsS -X POST "$MONITO_WEBHOOK_URL" \
  -H "Authorization: Bearer $MONITO_WEBHOOK_SECRET"

The webhook returns 202 Accepted once runs are queued. It does not block the deployment for pass/fail results; review the dashboard for the run output.

Run only selected scenarios:

curl -fsS -X POST "$MONITO_WEBHOOK_URL" \
  -H "Authorization: Bearer $MONITO_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"scenarioIds":["scenario_123"]}'

Test a preview deploy by passing its URL (and, optionally, the credential environment or suite names) in the body. baseUrlOverride overrides the target origin for the run; env and suite select a Monito environment and test suite by name:

curl -fsS -X POST "$MONITO_WEBHOOK_URL" \
  -H "Authorization: Bearer $MONITO_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"baseUrlOverride":"https://your-preview-url.example.com","env":"Preview"}'

For setup, limits and benchmark evidence, see GitHub Actions browser testing.

On this page