GitHub Actions

This page shows an example workflow for running Momentic on GitHub Actions. More reference workflows live in momentic-ai/examples. Given this root package.json:

package.json

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

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

    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 install

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

      - name: Test
        run: npx momentic run

      - 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

A pull request that Copilot, Cursor, Claude Code, or Devin opened goes through the same job as a pull request a person opened. The agent does not write the end-to-end tests by hand: the tests already live in the repository as YAML, and the job runs them against the branch. A failed test returns a nonzero exit code, so the check fails and the merge stays blocked until the agent or a reviewer fixes the code. 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 failed check links to the step that failed, its video, and its trace:

.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 install
      - 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 check finishes in minutes.
--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 holds the video and the trace.

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. When the agent runs in your editor with the MCP server installed, it runs the same tests before it pushes, reads the failure, and corrects its own code. The CI job is the second check on the pull request, not the first place the agent sees a failure. 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 install

      - 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 install

      - 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 parallelism is safe and the run is as long as the slowest test.
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 install

      - 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 install

      - 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