Configuring miska.ai

miska.ai works out of the box with zero configuration. When you want more control over which agents run and how they behave, drop a .miska.yml file in your repository root.

---

Overview

The .miska.yml configuration file controls how miska.ai tests your pull requests. You can configure which QA agents run, define custom user personas for user testing, and provide authentication instructions for your review app.

If no configuration file is found, miska.ai falls back to sensible defaults: it runs the functional agent and a default "First-time user" persona. You can customize which agents and personas run, or disable personas entirely.

File location

Place the file at the root of your repository:

your-repo/
  .miska.yml      # ← configuration goes here
  src/
  package.json
  ...

miska.ai reads this file from the PR branch, so configuration changes in a pull request take effect immediately for that PR's test run.

Minimal example

The simplest useful configuration just lists the agents you want to run. If you don't define any personas, a default "First-time user" persona is used automatically.

agents:
  - functional
  - destructive

# Optional: define custom personas (a default is used if omitted)
personas:
  - name: "New user evaluating the product"
    goal: "Explore the app and decide if it's worth using"

---

Model

miska.ai supports multiple LLM providers. By default it uses Anthropic's Claude, but you can configure a different provider per-repository using the model block in your .miska.yml, or set a default in your account settings.

Supported providers

Provider	Default model	Notes
anthropic	claude-sonnet-4-6	Default provider. Best for complex QA reasoning.
gemini	gemini-2.5-flash	Google's Gemini models. Fast and cost-effective.
custom	—	Any OpenAI-compatible API (Ollama, Groq, Together, vLLM, etc.). Requires base_url.

Per-repository configuration

Add a model block to your .miska.yml to override the default provider for a specific repository:

model:
  provider: gemini
  name: gemini-2.5-flash

For a custom OpenAI-compatible provider:

model:
  provider: custom
  name: llama-3.3-70b
  base_url: https://api.groq.com/openai/v1

Resolution order

When miska.ai needs to decide which provider and model to use, it checks in this order:

1. .miska.yml model block — per-repository override (highest priority)
2. Account settings — your default provider and model on the Settings page
3. Platform defaults — Anthropic Claude (fallback)

API keys are always resolved from your account settings. If you configure gemini as the provider in .miska.yml, miska.ai will use the Gemini API key from your account settings (or the platform's hosted key if you haven't set one).

---

Execution Mode

By default, miska.ai runs agents sequentially (one at a time). You can switch to parallel execution (all agents at once) in your account settings.

Team and Enterprise plans can also override the execution mode per-repository using the execution_mode key in .miska.yml:

execution_mode: parallel   # or "sequential"

Resolution order

1. .miska.yml execution_mode — per-repository override (Team and Enterprise plans only)
2. Account settings — your execution mode on the Settings page
3. Default — sequential

---

Review App

miska.ai needs a URL to your review app (preview deployment) so agents can interact with it. By default, miska.ai tries to auto-detect this URL from GitHub deployment status webhooks sent by your hosting provider.

Some providers (like Railway) don't include the actual app URL in their deployment webhooks — they only send dashboard links. In these cases, disable auto-detection and provide the URL manually via /miska review <url> or the dashboard form.

review_app:
  auto_detect: false   # disable URL auto-detection from deployment webhooks

Options

Option	Type	Default	Description
auto_detect	boolean	true	When enabled, miska.ai picks up the review app URL from GitHub deployment status webhooks. Disable this if your hosting provider (e.g. Railway) sends dashboard URLs instead of the actual app URL.

Providing the URL manually

When auto-detection is disabled (or no deployment webhook arrives), you can provide the review app URL in two ways:

1. In the trigger comment — /miska review https://your-app.example.com
2. In the dashboard — paste the URL in the form shown while the test run is waiting

---

Agents

Agents are the core of miska.ai. Each agent type is specialized for a different kind of testing. They run in parallel, each in their own browser session, and report back independently.

agents:
  - functional
  - destructive
  - accessibility      # opt-in
  - integration        # opt-in

Available agent types

---

Personas

Personas let you define the types of users that should test your app. Each persona gets its own AI agent that explores your app from that user's perspective — with their background, patience level, technical skill, and goals in mind.

If no personas are defined, miska.ai automatically uses a default "First-time user" persona that explores the app and evaluates whether it's worth using. To disable user testing entirely, set personas: false.

personas:
  - name: "First-Time Visitor"
    description: |
      You're 25-35, not very technical. You landed here from a social
      media ad. You're curious but impatient — if something is
      confusing, you'll leave.
    focus:
      - "Is the value proposition clear within 10 seconds?"
      - "Can you complete the main action without getting stuck?"
      - "Would you trust this site with your credit card?"

  - name: "Power User"
    description: |
      You've used this app for 6 months. You know the features well.
      You're here to check if the new changes break your workflow.
    focus:
      - "Do existing workflows still work as expected?"
      - "Are there any regressions in features you use daily?"

Persona options

Option	Type	Required	Description
name	string	Yes	A name for the persona. Used in reports to identify findings.
goal	string	No	A short statement of what this persona is trying to accomplish. Guides the agent's overall approach.
description	string	No	Background context for the persona. The more detail you provide, the more realistic the testing behavior will be.
focus	string[]	No	Specific questions or areas the persona should evaluate. Guides the agent toward particular aspects of the experience.
auth	string	No	Per-persona authentication instructions. Overrides the global auth.instructions for this persona. Supports ${VAR} interpolation. Useful when different personas should log in as different users.

Disabling user testing

To run only QA agents without any user persona testing, set personas to false:

personas: false

---

Authentication

If your review app requires authentication, you can provide login instructions that agents will follow before testing. Use environment variable references to keep secrets out of your config file.

The global auth.instructions apply to all QA agents and any persona that doesn't define its own auth field. Personas can override this with per-persona auth instructions — useful when different personas should log in as different users (e.g., a new signup vs. an existing user).

auth:
  instructions: |
    Navigate to /test_auth?token=${MISKA_TEST_AUTH_TOKEN}
    This will create a test session and redirect to the home page.
    Use this when you need to access authenticated features.

Variable interpolation

Use ${VAR_NAME} syntax to reference secrets. Variables are resolved in this order:

1. Repository secrets — configured in your repository settings page on miska.ai
2. Environment variables — set on the miska.ai server (fallback)

Option	Type	Description
instructions	string	Natural-language login instructions for the agent. Supports ${VAR} interpolation for secrets.

---

Example: QA only (no personas)

Runs QA agents (including opt-in accessibility) with no user testing. Set personas: false to disable the default persona.

# .miska.yml
agents:
  - functional
  - destructive
  - accessibility

personas: false

---

Example: E-commerce app

An e-commerce app with personas that mirror real customer segments. The destructive agent catches security issues in checkout, while personas validate the buying experience.

# .miska.yml
agents:
  - functional
  - destructive
  - accessibility

personas:
  - name: "Impatient Shopper"
    goal: "Find and buy a product as fast as possible"
    description: |
      You're on your phone during a commute. You saw an ad for a
      product and want to buy it fast. You have zero patience for
      slow pages or confusing checkout flows.
    focus:
      - "Can I find and purchase a product in under 2 minutes?"
      - "Is the checkout flow clear on mobile?"
      - "Are shipping costs visible before checkout?"

  - name: "Returning Customer"
    goal: "Reorder a previous purchase"
    description: |
      You've bought here 3 times before. You know what you want.
      You expect your saved address and payment to still work.
    focus:
      - "Does the reorder flow still work?"
      - "Is my order history accessible?"

---

Example: SaaS dashboard

A B2B SaaS app where different user roles have very different experiences. Each persona uses per-persona auth to log in as a different user type.

# .miska.yml
agents:
  - functional
  - destructive
  - accessibility
  - integration

# Global auth used by QA agents
auth:
  instructions: |
    Navigate to /test_auth?token=${TEST_AUTH_TOKEN}
    This logs in as an existing admin user.

personas:
  - name: "New Team Member"
    goal: "Get started with the workspace"
    description: |
      Just got invited to the workspace. First time using the app.
      Trying to figure out where everything is.
    auth: |
      Navigate to /test_signup?token=${TEST_AUTH_TOKEN}
      This logs in as a brand new user with an empty workspace.
    focus:
      - "Is the onboarding flow intuitive?"
      - "Can you find the main features without help?"

  - name: "Admin User"
    goal: "Manage team settings and billing"
    description: |
      You manage the workspace settings, billing, and team members.
      You need everything to work reliably.
    focus:
      - "Can you manage team members and permissions?"
      - "Is the billing page accurate and functional?"

The "New Team Member" persona uses its own auth to log in as a fresh user, while the "Admin User" persona falls back to the global auth.instructions.

---

Full configuration

A complete example showing every available option.

# .miska.yml — Full configuration reference

# LLM provider (optional — defaults to account settings or Anthropic)
model:
  provider: anthropic
  name: claude-sonnet-4-6

# Execution mode (optional — Team/Enterprise only, defaults to account settings)
execution_mode: parallel

# Review app URL detection (optional — defaults to auto-detect)
review_app:
  auto_detect: false

# Authentication instructions for the review app
auth:
  instructions: |
    Navigate to /test_auth?token=${MISKA_TEST_AUTH_TOKEN}
    This will create a test session and redirect to the home page.

# Which QA agents to run
agents:
  - functional
  - destructive
  - accessibility
  - integration

# User personas for user testing
personas:
  - name: "First-Time Visitor"
    goal: "Evaluate if the app is worth using"
    description: |
      You're 25-35, not very technical. You landed here from a
      social media ad. Curious but impatient.
    auth: |
      Navigate to /test_signup?token=${MISKA_TEST_AUTH_TOKEN}
      This logs in as a brand new user with no existing data.
    focus:
      - "Is the value proposition clear within 10 seconds?"
      - "Can you complete the main action without getting stuck?"
      - "Would you trust this site with your credit card?"

  - name: "Power User"
    goal: "Verify existing workflows aren't broken"
    description: |
      6 months of daily usage. Knows every feature.
      Checking for regressions.
    focus:
      - "Do existing workflows still work?"
      - "Is the new feature consistent with existing patterns?"