Installation

Get miska.ai running on your repositories in under 5 minutes. No code changes required — just install the GitHub App, push a PR, and get your first test report.

---

Prerequisites

Before you get started, make sure you have:

• A GitHub account with access to the repositories you want to test
• A repository with a review app deployment set up (Vercel, Railway, Render, Heroku, Netlify, or any platform that deploys preview environments per pull request)

miska.ai works with any web application that gets deployed as a review app. The deployment platform must send deployment_status webhooks to GitHub — most platforms do this automatically.

---

Sign in with GitHub

Head to the miska.ai homepage and click "Request access" or "Sign in". You'll be redirected to GitHub to authorize the miska.ai OAuth app.

miska.ai requests the minimum permissions needed to operate:

• Read your email address — for account identification
• Read your profile information — for displaying your username and avatar

After authorizing, you'll be redirected back to the miska.ai dashboard.

---

Install the GitHub App

After signing in, install the miska.ai GitHub App on your organization or personal account. You can choose to install it on all repositories or select specific ones.

The GitHub App requires the following permissions:

Permission	Access	Why
Deployments	Read	Detect when review apps go live
Pull requests	Read & Write	Read PR diffs, post test reports as comments
Contents	Read	Read .miska.yml configuration from your repo
Metadata	Read	Required by GitHub for all apps

The app also subscribes to deployment_status and pull_request webhook events so it can automatically trigger test runs when deployments go live.

---

Connect repositories

After installing the GitHub App, your repositories sync automatically. Head to the Dashboard to see your connected repositories. Each repository shows its current status and recent test runs.

If you installed the app on specific repositories and want to add more later, go to your GitHub organization's settings → Installed GitHub Apps → miska.ai → Configure and add the new repositories.

---

Create a pull request

Push a branch and open a pull request against your repository. When your deployment platform deploys the review app, it sends a deployment_status webhook to GitHub, which miska.ai receives automatically.

miska.ai then:

1. Detects the deployment and waits for it to become active
2. Reads your .miska.yml configuration (if present)
3. Analyzes the PR diff to focus testing on changed areas
4. Spins up parallel AI agents that interact with your review app through real browsers
5. Collects results from all agents and synthesizes a report

No code changes are needed in your repository. miska.ai works entirely through the GitHub App and webhook integration.

---

Review the report

Once all agents finish, miska.ai posts a structured report as a comment on your pull request. The report includes:

• Issues found — bugs, regressions, and problems categorized by severity
• Screenshots — visual evidence of issues encountered
• Recommendations — actionable suggestions for fixing issues
• Agent summaries — what each agent tested and found

You can also view detailed results on the miska.ai dashboard by clicking on the test run for your repository. The dashboard shows individual agent run details, including full interaction logs and screenshots.

---

Optional: Add configuration

miska.ai works out of the box with sensible defaults — it runs a functional agent and a default "First-time user" persona. When you want more control, drop a .miska.yml file in your repository root.

With a configuration file you can:

• Choose which QA agents to run (functional, destructive, accessibility, integration)
• Define custom user personas for user testing
• Provide authentication instructions for your review app
• Select a different LLM provider (Anthropic, Gemini, or a custom OpenAI-compatible endpoint)

You can also configure your default LLM provider and manage API keys for each provider on the Settings page.

See the Configuration docs for the full reference.

---

Optional: Set up authentication

If your review app requires login to access the features you want tested, you can provide authentication instructions in your .miska.yml. Agents will follow these instructions to log in before they start testing.

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

Use ${VAR_NAME} syntax to reference secrets stored in your repository settings on miska.ai. See the Authentication section of the configuration docs for full details.

---

Troubleshooting

Deployment not detected

miska.ai relies on deployment_status webhooks from GitHub. If your test run isn't starting:

• Verify your deployment platform sends deployment status events to GitHub (most do by default)
• Check that the miska.ai GitHub App is installed on the repository
• Ensure the deployment is for the correct PR branch

Agents not running

If a test run is created but agents aren't starting:

• Check the test run status on the miska.ai dashboard — it may be waiting for the deployment to become active
• Verify your review app URL is accessible from the internet
• If using authentication, ensure your auth instructions and secrets are configured correctly

Report not posted

If agents ran but no report appeared on your PR:

• Check the test run status on the dashboard — it should show "completed" or "failed"
• Verify the miska.ai GitHub App has write access to pull requests
• Look for any error messages in the test run details