CI Integration

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
    env:
      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 --json

project run exits with code 1 when any scenario fails, so the workflow fails automatically. It also writes a compact GitHub job summary with scenario results and links to Monito evidence.

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.

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