Monito CLI

CI Integration

Run Monito from GitHub Actions or 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 exact trusted workflow. The CLI keeps that token in memory and never prints or persists it. Jobs from fork pull requests are skipped, and the Monito authorization permits only CI status and run operations for the bound project.

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 generated workflow has this authentication shape:

name: Monito

on:
  pull_request:
  push:
    branches:
      - "main"

jobs:
  monito:
    if: >-
      github.event_name != 'pull_request' ||
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      checks: write
      pull-requests: write
    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: Run Monito project
        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 neutral if every non-passing test has execution status error; the CLI exit code stays 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.

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).

--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"}'

Writing Good Tests

How to write test scenarios the Monito agent can run and verify, and how the checker and AI Improve help.

Deploy Webhook

Trigger Monito tests from any deployment pipeline with a single HTTP POST.

On this page

Choose an integrationSet up CI with an AI agentGitHub Actions with the CLITest every preview deployVercel deploymentsProtected previewsInspect results and remove CIDeploy webhook