> ## Documentation Index
> Fetch the complete documentation index at: https://www.minitap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub
> The MiniTest GitHub App — how to install it, how you trigger runs from PRs, and what Mini posts back to your repo.
miniTest talks to GitHub through a single GitHub App. Install it once per org and it covers every connected app in that org.
## Is connecting GitHub required?
Strictly speaking, no — you can test any app by uploading builds manually through the CLI. But skipping the GitHub connection means giving up a lot of what makes miniTest useful:
* [Automatic suite generation and maintenance](/docs/minitest/suite/mini-maintains-your-suite) from your codebase.
* Automatic builds on CI-triggered runs (see [Providing app builds](/docs/minitest/runs/builds)).
* Mini showing up on your PRs to tell you whether you can ship.
If you're evaluating miniTest, you can skip GitHub today and add it later. If you're using miniTest day to day, connect it.
## Install
**Workspace settings → Integrations → GitHub → Install**. The flow opens GitHub's App install screen — pick the org and either grant **All repositories** or **Only selected repositories**.
## What you see on a PR
Mini only posts on PRs that target your app's default branch (usually `main`) or a branch that matches your configured [release branch patterns](#when-mini-shows-up). Monorepo apps also require at least one changed file under the app's source folder.
### The sticky comment
Mini posts one comment per PR. It introduces itself, lists every affected app with a **Run tests** checkbox, and waits for you to act — it never kicks off a run on its own.
Ticking a checkbox (or posting `@mini test ` as a PR comment) fires a run. The comment edits in place as the run progresses, and when it finishes it becomes a full report: per-platform verdict, Critical and Warning buckets with expandable story cards, and a link back to the dashboard for the full timeline and video.
If you change the PR after the comment was posted — push a new commit, add an app — Mini edits the comment to match. No thread spam, no second comment.
### The check run
Every CI-triggered run also posts a GitHub check on the PR:
**Check name:** `Minitest (AppName)` — not visible in the project tree, but this is the name you'll see in branch protection lists.
* **States:** queued → in progress → completed (success / failure / neutral).
* **Cancel** and **Bypass** buttons are available during the run and on terminal failures.
The check conclusion is **neutral by default** — Mini won't block merges until you turn on blocking. To require it to pass, enable `block_on_test_failures` in your workspace settings, then add the check to **GitHub → Settings → Branches → Branch protection rules → Require status checks**.
## Triggering a run from a PR
Three paths, all producing the same run report:
### 1. The CI Action (recommended)
**Why this path.** You control exactly when a run fires — on every push, only on PRs, on `release-*` tags, or any combination you want. You own the workflow file, so you decide the trigger conditions.
Add `minitap-ai/minitest-trigger@v1` to your `.github/workflows/*.yml`:
```yaml theme={null}
jobs:
test:
runs-on: ubuntu-latest
permissions:
id-token: write
steps:
- uses: minitap-ai/minitest-trigger@v1
with:
app-slug: my-app
```
The Action authenticates via GitHub OIDC — no API key needed. The MiniTest GitHub App must be installed on the org before the first run. For every input and build-path example, see [GitHub Action reference](/docs/minitest/reference/minitest-trigger-action).
#### Choosing what to run
By default the Action is smart about scope: on a git tag matching your app's tag pattern (set in **App Settings → Maintenance & CI** under `ci_tag_pattern`), it runs only the user stories **affected since the previous matching tag**. On any other event, it runs the whole suite. You override that with two inputs.
| You want | Set | Runs |
| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Affected since last release | `scope: affected` | Only stories the diff touched since the previous matching tag. Needs a release tag pattern set in your **App Settings → Maintenance & CI**. |
| Full regression | `scope: full` | Every user story in the suite. |
| A specific set | `user-stories` or `user-story-types` | Only the stories you name. Takes precedence over `scope`. |
Run everything on every push:
```yaml theme={null}
- uses: minitap-ai/minitest-trigger@v1
with:
app-slug: my-app
scope: full
```
On a release tag, run only what changed since the last release:
```yaml theme={null}
on:
push:
tags: ['release-*']
jobs:
test:
runs-on: ubuntu-latest
permissions:
id-token: write
steps:
- uses: minitap-ai/minitest-trigger@v1
with:
app-slug: my-app
scope: affected
```
Run one area by story type — say your checkout and login journeys:
```yaml theme={null}
- uses: minitap-ai/minitest-trigger@v1
with:
app-slug: my-app
user-story-types: login,checkout
```
Leaving `scope` empty is fine: with a tag pattern set, a matching tag runs the affected set and everything else runs the full suite.
### 2. The PR comment checkbox
Ticking the **Run tests** checkbox in Mini's sticky comment fires a run for that app. No workflow file, no setup — the GitHub App handles the dispatch. Use this when you're reviewing and want to confirm a fix without waiting for CI.
### 3. The `/test` slash command
Post `@mini test ` on the PR and Mini does the same thing as the checkbox. Works in the same comment or in any top-level PR comment.
## When Mini shows up
Mini decides whether to post a sticky comment on a PR using two rules — both configurable per app:
PRs targeting your app's **default branch** (typically `main`) always get a comment for that app. This is the **source branch** you set when connecting the app to a repo.
You can define **gitignore-style patterns** in **App Settings → Maintenance & CI** under `release_branch_patterns`. PRs targeting a branch that matches any pattern (e.g. `release/*`) get a comment even if the default branch is different.
If a PR matches neither (say it targets a feature branch), Mini stays quiet. The check run path via the CI Action still works regardless of branch.
Monorepo apps have one extra rule: at least one file in the PR must fall under the app's configured source folder. PRs that only touch unrelated directories are skipped.
## Triggering from a tag
Set a **tag pattern** in **App Settings → Maintenance & CI** under `ci_tag_pattern` (e.g. `release-*`), then run the CI Action on tag pushes. When the pushed tag matches, Mini runs only the user stories affected since the previous matching tag instead of the whole suite — a fast release gate for tags like `release-1.2.0`. The tag pattern only takes effect through the [CI Action](#1-the-ci-action-recommended); with no Action on tag pushes, nothing fires.
## Connecting an app to a repo
In each app's **Settings → Source**, point at:
* **Repo** (`owner/name`) — auto-completes from the repos the App can see.
* **Branch** — the default branch. Determines which PRs get a sticky comment (see [When Mini shows up](#when-mini-shows-up)) and the base for tag-triggered runs.
* **Source folder** (optional) — subfolder for monorepos. See [Providing app builds](/docs/minitest/runs/builds).
## Removing the App
`GitHub → Settings → Applications → MiniTest → Configure → Uninstall`. miniTest will keep run history and configuration, but builds and PR checks will stop. Reinstalling restores everything.