GitHub Action reference

The minitap-ai/minitest-trigger GitHub Action is the CI surface for miniTest. It authenticates via GitHub OIDC, uploads your build (or asks Mini to build one), and starts the run. By default it returns as soon as the run is queued, and results come back via a GitHub Check Run on the commit. It can also wait for the verdict and fail the step, which is how you gate a release on the suite. For the workflow setup walkthrough, see Triggering a run → From CI.

Minimal usage

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app

That’s enough. Mini builds your app for both platforms on the head commit, runs every story, and posts the verdict to the PR.

Prerequisites

The workflow must have the id-token: write permission for OIDC authentication:

permissions:
  id-token: write

And the MiniTest GitHub App must be installed on the org. See GitHub integration.

Inputs

Input	Required	Default	Description
`app-slug`	Yes	None	The miniTest app slug. Find it in App Settings → General.
`run-ios`	No	`true`	Include the iOS lane. Mini builds the app when no `ios-build-path` is given.
`run-android`	No	`true`	Include the Android lane. Mini builds the app when no path is given.
`ios-build-path`	No	None	Pre-built iOS bundle, either a simulator `.app` directory or an `.ipa` file.
`android-build-path`	No	None	Pre-built Android `.apk`. Must target x86-64.
`scope`	No	None	What to run: `affected` (only stories changed since the previous matching tag; needs `ci_tag_pattern` set) or `full` (the whole suite). Leave empty to let miniTest decide: affected on a matching tag, full otherwise. Ignored when `user-stories` or `user-story-types` is set. See Choosing what to run.
`user-stories`	No	None	Comma-separated list of user story IDs to run. Takes precedence over `scope`.
`user-story-types`	No	None	Comma-separated list of story types to run (e.g. `login,checkout`). Takes precedence over `scope`.
`run-web`	No	`false`	Include the web lane. For a web app linked to a GitHub repo, Mini builds and serves the commit this workflow runs on and tests against it, with no `web-url` needed. For a web app with only a configured URL, it tests that URL. See Web runs.
`web-targets`	No	None	Explicit web targets, as a comma-separated list of `<browser>:<viewport>` specs (e.g. `chrome:desktop,safari:mobile`). Includes the web lane on its own. Set this or `run-web`, not both.
`web-url`	No	None	Per-run web URL, e.g. a PR preview deployment. When set, the web lane tests this URL instead of building the commit. Applies when `run-web` or `web-targets` is set.
`tenant-id`	No	None	Required only if the repo is linked to multiple workspaces.
`cancel-previous-runs`	No	`true`	Cancel in-flight CI runs on the same source branch when it matches a configured release pattern. See Cancelling previous runs.
`wait-for-result`	No	`false`	Block the step until the run reaches a verdict, instead of returning once it’s queued. See Blocking a release on the result.
`wait-timeout-minutes`	No	`45`	How long to wait while `wait-for-result` is on. The step fails if no verdict lands by then.
`fail-on-failure`	No	`false`	Fail the step when the verdict is a failure. Only does anything with `wait-for-result: true`.
`api-url`	No	miniTest API	Override the API base URL. You won’t normally need this.

Native cloud device type (pending)

Coming soon. These inputs are part of the pending native cloud tablet contract, not a deployed Action release. Tablet execution requires native-tablets, off by default.

Input	Required	Default	Description
`ios-device-type`	No	None (effective `phone`)	`phone` or `tablet` for the enabled native cloud iOS lane.
`android-device-type`	No	None (effective `phone`)	`phone` or `tablet` for the enabled native cloud Android lane.

Omitting either input leaves its request field absent and preserves phone execution. Explicit values serialize as iosDeviceType and androidDeviceType. These inputs never enable a lane: explicit phone or tablet is rejected when the corresponding run-ios or run-android is false. Other values are rejected. Choose one form factor per platform per run. These inputs do not configure web viewports or mobile-web devices. See the target restrictions for physical and edge devices too. The pending CI response includes compatibilityWarnings: string[]. The Action displays these as nonblocking warnings, not failures or a reason to skip waiting for the run.

Outputs

Output	Description
`batch-id`	The ID of the triggered run.
`status`	Initial status of the triggered run.
`result`	The verdict, set when `wait-for-result` is on: `passed`, `failed`, `error`, or `nothing_affected`. Empty when the Action didn’t wait.
`batch-url`	Link to the run report in the dashboard.

Build paths and requirements

If you don’t pass a build path, Mini builds your app for that platform on the triggering commit (using whatever’s configured in Providing app builds). If you pass a build path, the Action uploads that artifact instead of asking Mini to build.

iOS

Format	Notes
`.app`	Simulator bundle directory. Automatically packaged into `.ipa` before upload.
`.ipa`	Uploaded as-is. Must be a simulator build.

A typical xcodebuild line for the simulator:

xcodebuild build \
  -scheme MyApp \
  -sdk iphonesimulator \
  -configuration Debug \
  -derivedDataPath ./build
# Output: ./build/Build/Products/Debug-iphonesimulator/MyApp.app

Android

.apk only, and it must contain native libraries for x86_64. The Action inspects the APK and fails with a clear error if only arm64-v8a or armeabi-v7a are present. Configure app/build.gradle:

android {
  defaultConfig {
    ndk { abiFilters 'x86_64' }
  }
}

Then build:

./gradlew assembleDebug
# Output: app/build/outputs/apk/debug/app-debug.apk

Web runs

run-ios, run-android, and the web inputs each select a lane. Lanes are additive: you can run just the web lane, just one native lane, or any mix. Web targets point at a URL instead of an uploaded artifact, with one exception: a web app linked to a GitHub repo builds and serves the commit this workflow runs on. See Building the commit. There are two ways to include the web lane:

run-web: true runs the app’s configured default web targets, set per app in the dashboard. This is the defaults marker: it expands to whatever browsers and viewports you set there. A repo-linked app runs them against the built commit; a URL-only app runs them against its configured web URL.
web-targets runs an explicit list instead. Each spec is <browser>:<viewport>, comma-separated. Setting web-targets includes the web lane on its own.

Set run-web or web-targets, not both. One picks the app defaults, the other an explicit list. A web app can be tested on a mobile device’s browser, so <browser>:<viewport> maps to a concrete target:

Spec	Where it runs
`safari:mobile`	iOS device in Safari (mobile-web)
`chrome:mobile`	Android device in Chrome (mobile-web)
`chrome:desktop`, `firefox:desktop`	Desktop web

The Action parses <browser>:<viewport> and the backend validates the combination. Browser support is chrome and firefox for desktop, plus safari for iOS mobile-web. Desktop Safari (safari:desktop) is not a valid web target. Each lane ignores nothing silently: web-url and web-targets apply only when the web lane is on, ios-build-path only when run-ios is on, android-build-path only when run-android is on. Passing a lane’s input while that lane is off is rejected, so a typo can’t quietly drop your build or URL.

Building the commit

If your web app is linked to a GitHub repo (set in App Settings), run-web: true builds your frontend at the commit this workflow runs on, serves it in the test environment, and runs your web stories against that build. No web-url is required. This holds even if the app also has a configured web URL: the linked-repo lane tests the commit, not the deployment. Supply web-url only when you want to test a separately-deployed URL (e.g. a PR preview) instead of the commit.

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    run-web: true # builds and serves this commit for a repo-linked web app

Per-run URL with `web-url`

The common CI case is testing a PR preview deployment. Set web-url to the deploy’s URL and it overrides the app’s configured web URL for that run:

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    run-web: true
    web-url: https://pr-142.preview.example.com

This runs the web lane against the preview URL, alongside whichever native lanes are enabled. CI is one of two surfaces allowed to override web targets and the web URL per run; the other is the Run tests panel in the dashboard. The CLI and Slack can pick the web lane but can’t override its targets or URL.

Examples

Default: Mini builds for both platforms

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app

iOS only

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    run-android: false

Android only, with your own build

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    run-ios: false
    android-build-path: ./app/build/outputs/apk/debug/app-debug.apk

Bring your own iOS build, let Mini build Android

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    ios-build-path: ./build/Build/Products/Debug-iphonesimulator/MyApp.app

Restrict to specific story types

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    user-story-types: login,checkout,onboarding

Web app, configured defaults

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    run-web: true

Web app, explicit targets

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    web-targets: chrome:desktop,safari:mobile
    web-url: https://pr-142.preview.example.com

Web app on mobile browsers

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    web-targets: safari:mobile,chrome:mobile

Multi-workspace setup

- uses: minitap-ai/minitest-trigger@v1
  with:
    app-slug: my-app
    tenant-id: tenant_abc123

Cancelling previous runs

When you push repeatedly to the same release branch (reopening a release PR with a fix, for example), older runs that are still pending or running pile up. With cancel-previous-runs: true (the default), the server cancels in-flight runs that match the same source branch before starting the new one. Cancellation is scoped:

Same source branch only: matched on the PR head branch (pull_request events) or the branch ref for push / workflow_dispatch / schedule / merge_group.
Release branches only: the branch must match one of the app’s configured release branch patterns (gitignore-style; configured per app in the dashboard).
CI-triggered only: only runs started by this Action are cancelled. Dashboard, Slack, or CLI runs are untouched.

It’s a no-op for:

Tag pushes (refs/tags/*).
Branches that don’t match a configured release pattern.
Events where the branch can’t be determined.

Opt out with cancel-previous-runs: false.

Blocking a release on the result

By default the Action queues the run and exits, so the rest of your workflow carries on while the suite is still going. Set wait-for-result: true and the step polls until the run has a verdict. Add fail-on-failure: true and the step fails when that verdict is a failure, which skips every job that has a needs: on it. That’s the release gate: a tag that breaks a story never reaches the deploy.

jobs:
  minitest-gate:
    runs-on: ubuntu-latest
    timeout-minutes: 70
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v6
      - uses: minitap-ai/minitest-trigger@v2
        with:
          app-slug: my-app
          wait-for-result: true
          fail-on-failure: true
          wait-timeout-minutes: 60

  deploy:
    needs: minitest-gate
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Set the job’s timeout-minutes a little above wait-timeout-minutes. If GitHub kills the runner first you lose the verdict and get a runner timeout instead of a useful error. A nothing_affected result is a pass only when the launch response contains the exact warning nothing_affected. This is a no-op: there is no run to poll, and the step succeeds. Other warnings do not indicate a no-op.

Exact launched-run polling (pending)

The pending Action contract polls /ci/status using the returned batchId as batch_id, or, if no batchId was returned, the immutable launch reservation launchIntentId as launch_intent_id. maintenanceRunId always identifies the real, shared commit-derived analysis; it is never a reservation alias or an execution polling handle. Polling never falls back to the latest run for the commit SHA. If neither batchId nor launchIntentId is returned and the exact nothing_affected warning is absent, the Action must fail with an upgrade-required error, including when only maintenanceRunId is returned. It must not poll or report a successful no-op. Analysis-only progress or completion does not mean tests passed. Independent phone and tablet jobs for the same commit keep independent results because each polls its own launch handle. Each run still selects one form factor per platform; two jobs do not combine into one phone-and-tablet run.

This is not block_on_test_failures. That app setting changes the check run conclusion from neutral to failure, which is what GitHub branch protection reads when deciding whether a PR can merge. wait-for-result and fail-on-failure act on the workflow instead: the step fails, so downstream jobs don’t run. Use either, or both. Neither switches the other on.

How it works

OIDC auth. The Action requests a GitHub OIDC token scoped to the Minitap API. Nothing to manage on your side.
Validate builds. If you supplied any build paths, the Action checks the artifacts (simulator-only iOS, x86-64 Android).
Upload builds. Anything you supplied is uploaded to miniTest. .app bundles get packaged into .ipa first.
Trigger the run. For any enabled platform without a supplied build, Mini builds the app for the triggering commit. This includes the web lane for a repo-linked web app: Mini builds and serves the commit unless you point web-url at a deployed URL.
Return. By default the Action exits as soon as the run is queued, and results come back via the GitHub Check Run on the commit. With wait-for-result: true it polls until the run has a verdict, sets result, and can fail the step on a failure.

Get started

Your suite

Run your suite

Integrations

Reference

GitHub Action reference

Minimal usage

Prerequisites

Inputs

Native cloud device type (pending)

Outputs

Build paths and requirements

iOS

Android

Web runs

Building the commit

Per-run URL with `web-url`

Examples

Default: Mini builds for both platforms

iOS only

Android only, with your own build

Bring your own iOS build, let Mini build Android

Restrict to specific story types

Web app, configured defaults

Web app, explicit targets

Web app on mobile browsers

Multi-workspace setup

Cancelling previous runs

Blocking a release on the result

Exact launched-run polling (pending)

How it works

​Minimal usage

​Prerequisites

​Inputs

​Native cloud device type (pending)

​Outputs

​Build paths and requirements

​iOS

​Android

​Web runs

​Building the commit

​Per-run URL with web-url

​Examples

​Default: Mini builds for both platforms

​iOS only

​Android only, with your own build

​Bring your own iOS build, let Mini build Android

​Restrict to specific story types

​Web app, configured defaults

​Web app, explicit targets

​Web app on mobile browsers

​Multi-workspace setup

​Cancelling previous runs

​Blocking a release on the result

​Exact launched-run polling (pending)

​How it works

Minimal usage

Prerequisites

Inputs

Native cloud device type (pending)

Outputs

Build paths and requirements

iOS

Android

Web runs

Building the commit

Per-run URL with `web-url`

Examples

Default: Mini builds for both platforms

iOS only

Android only, with your own build

Bring your own iOS build, let Mini build Android

Restrict to specific story types

Web app, configured defaults

Web app, explicit targets

Web app on mobile browsers

Multi-workspace setup

Cancelling previous runs

Blocking a release on the result

Exact launched-run polling (pending)

How it works