GitHub Actions

Run your repository’s Momentic tests in GitHub Actions (GHA). These workflows cover authentication, pull request gates, mobile builds, and sharding. More examples live in momentic-ai/examples. Given this root package.json:

package.json

{
  "name": "my-momentic-repo",
  "scripts": {},
  "devDependencies": {
    "momentic": "latest"
  }
}

Run npm install locally and commit package-lock.json with package.json. The workflows below use the lockfile for npm caching and reproducible dependency installation. Create a file called .github/workflows/ci.yml in your repository with the following contents:

ci.yml

name: CI

on:
  push:
    branches: ["main"]
  pull_request:
    types: [opened, synchronize]

jobs:
  build:
    name: Test
    timeout-minutes: 15
    runs-on: ubuntu-latest
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}

    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Install browsers
        run: npx momentic install-browsers --all

      - name: Test
        run: npx momentic run --output-dir test-results

      - name: Upload results
        if: always()
        run: npx momentic results upload test-results

Authentication

To run any commands, you must authenticate with Momentic. Add the MOMENTIC_API_KEY environment variable to your GitHub Actions workflow.

Create an API key in the Momentic dashboard.

Copy the value. You add it as a CI secret in the next step.

Go to your GitHub repository settings and click Secrets, then Actions. Create a new secret called MOMENTIC_API_KEY and enter your API key.

At the top of your GitHub Actions workflow, provide the following environment variables to jobs that use momentic:

ci.yml

# ...

jobs:
  build:
    name: Build and Test
    timeout-minutes: 15
    runs-on: ubuntu-latest
    # To authenticate, set the following environment variables.
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}

    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
    # ...

Gate a pull request from a coding agent

Pull requests opened by coding agents run through the same configured checks as other pull requests. The job below runs the repository’s YAML tests against their configured target. A counted failure returns a nonzero exit code; make the check required to block merging. Keep the gate small and strict. Label the flows whose failure should block a merge with critical, run only those on pull_request, and upload the results so the dashboard includes the failed step and its available artifacts:

.github/workflows/agent-gate.yml

name: Agent gate

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  test:
    name: Critical flows
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm ci
      - run: npx momentic install-browsers chromium

      - name: Run critical flows
        run: npx momentic run --labels critical --reporter steps -y --upload-results

--labels critical limits the gate to the labeled tests, so the gate runs a smaller set.
--reporter steps logs each step as it starts and finishes. An agent that reads the job log sees the step that failed without opening the dashboard.
--upload-results attaches the run to the dashboard, where the failed step includes the trace and any recorded video.

Add the check name (Agent gate / Critical flows) to the branch protection’s required status checks. Until then, the gate is advisory and an agent can merge over a failure. With the MCP server installed, you can ask the agent to run the affected tests locally and inspect failures before pushing. The CI job then validates the committed version. See Gate pull requests on critical flows for the label conventions and the flake policy.

Run mobile tests on a pull request

iOS and Android tests run with momentic-mobile, one workflow per platform. Remote simulators and emulators run on Momentic, so the test job needs no macOS runner and no Xcode. Only the build step needs macOS, because the iOS testing build is an .app bundle from Xcode. Upload the build once, then run the iOS tests against it:

.github/workflows/ios.yml

name: iOS tests

on:
  pull_request:
    types: [opened, synchronize]

env:
  ASSET_TAG: ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}

jobs:
  build:
    name: Build and upload app
    runs-on: macos-latest
    timeout-minutes: 30
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm ci

      - name: Build for testing
        run: |
          xcodebuild build-for-testing \
            -scheme Shop \
            -destination "generic/platform=iOS Simulator" \
            -derivedDataPath build

      - name: Upload the build
        run: |
          npx momentic-mobile assets upload \
            build/Build/Products/Debug-iphonesimulator/Shop.app \
            --channel pr --tag $ASSET_TAG

  test:
    name: Run iOS tests
    runs-on: ubuntu-latest
    timeout-minutes: 20
    needs: build
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm ci

      - name: Run tests
        run: |
          npx momentic-mobile run tests/ios \
            --channel pr --tag $ASSET_TAG \
            --parallel AUTO -y --upload-results

--channel pr --tag $ASSET_TAG installs the build this pull request produced, so the tests never run against a stale app. Tags are immutable: a (channel, tag) accepts only the same bytes again. A tag built from github.sha, github.run_id, and github.run_attempt is new on every run and every rerun, so a rebuilt app never collides with an earlier upload.
tests/ios limits the run to the iOS tests. Without a path or --include pattern, momentic-mobile run collects the Android tests too, and they fail because no APK exists under this channel and tag.
--parallel AUTO runs the tests at the same time. Each remote test gets its own simulator or emulator, so tests can run independently, subject to organization quotas and runner limits.
An Android build follows the same shape in its own workflow: build the APK on ubuntu-latest, upload it with assets upload, and run tests/android with the same --channel and --tag.

Local simulators and emulators on a CI runner boot slowly and, for iOS, allow one test at a time. Prefer remote simulators in CI. See Simulators and Emulators for the app requirements, and momentic-mobile assets for channels and tags.

Sharding

If you have a large test set, use sharding to run tests in parallel across CI jobs and shorten total run time. To shard your tests, pass the --shard-index and --shard-count options to the momentic run command. --shard-index is the index of the current shard (starting from 1), and --shard-count is the total number of shards. To collect test results inside a single run group in the Momentic dashboard, add a separate step after all tests complete to merge and upload results.

ci.yml

name: CI

on:
  push:
    branches: ["main"]
  pull_request:
    types: [opened, synchronize]

jobs:
  run-tests:
    name: Run tests
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2]
        shardTotal: [2]
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Install browsers
        run: npx momentic install-browsers --all

      - name: Test
        run: |
          npx momentic run \
            --output-dir test-results/shard-${{ matrix.shardIndex }} \
            --shard-index ${{ matrix.shardIndex }} \
            --shard-count ${{ matrix.shardTotal }}

      - name: Save test results artifact
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results-${{ matrix.shardIndex }}
          path: ./test-results
          retention-days: 1

  upload-results:
    name: Merge and upload test results
    runs-on: ubuntu-latest
    if: always()
    timeout-minutes: 5
    needs:
      - run-tests

    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Download all test results artifacts
        uses: actions/download-artifact@v4
        with:
          path: ./test-results
          pattern: test-results-*
          merge-multiple: true

      - name: Merge test results
        run: npx momentic results merge --output-dir test-results/merged test-results

      - name: Upload test results to Momentic
        run: npx momentic results upload test-results/merged

Get started

Building with AI

Author

Run

Learn

Platforms

Integrations

Account

Authentication

Gate a pull request from a coding agent

Run mobile tests on a pull request

Sharding

​Authentication

​Gate a pull request from a coding agent

​Run mobile tests on a pull request

​Sharding

Authentication

Gate a pull request from a coding agent

Run mobile tests on a pull request

Sharding