> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Author tests from a diff in CI

> Run the explore agent whenever changes land on main to discover changed user journeys and open the new tests as a PR.

<Warning>The explore agent is in beta and may change.</Warning>

[`momentic ai explore`](/docs/cli-reference/momentic/commands/ai#explore) diffs a
commit range, identifies the user journeys that changed, and by default authors
or edits Momentic tests to cover them, opening the new tests as a pull request
so coverage stays current with the product. See the
[explore agent](/docs/coding-agents/explore) overview for the concept.

Run it on pushes to `main`. Each merge to `main` is explored once, against the
change that just landed, so coverage is authored for merged work instead of
re-running on every commit of every open branch.

## Add the workflow

Add a workflow that runs explore whenever changes land on `main`:

```yaml .github/workflows/momentic-explore.yml theme={null}
name: Momentic explore

on:
  push:
    branches:
      - main

permissions:
  contents: read

env:
  MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}

jobs:
  explore:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: "npm"

      - run: npm ci
      - run: npx momentic install-browsers chromium

      - name: Explore the changes that landed and build tests
        run: npx momentic ai explore diff
```

`fetch-depth: 0` gives the agent the history it needs to diff the pushed range.
Outside a pull request, `momentic ai explore diff` diffs the commit that just
landed (`HEAD~1..HEAD`), so a squash-merged PR is explored as a single change
without passing an explicit commit range.

`MOMENTIC_API_KEY` authenticates the run.
[Create one here](https://app.momentic.ai/settings/api-keys) and add it as a
repository secret.

Pass `--dry-run` to have the agent only discover and log the changed journeys
without authoring tests, which is useful while you are evaluating what it would
do.

## Choose what a build produces

Set **On successful explore** in
[Settings > Explore](https://app.momentic.ai/settings/explore) to control what
happens to the tests the agent authors:

* `pull-request`: open a PR with the new and edited tests. Best when you want
  generated coverage reviewed and merged like any other change.
* `draft-pull-request`: open the PR as a draft so a human marks it ready.
* `direct-commit-except-main`: commit and push to the checked-out branch. On
  `main` or a GitHub-protected branch, open a draft PR instead.
* `patch`: print a `git apply`-ready diff instead of opening a PR. Needs no
  GitHub App, so it is the option for forked-PR runs where the app is
  unavailable.
* `nothing` (default): leave the changes on disk.

Pull requests are pushed to a `momentic-explore/` branch, so generated coverage
lands in the same review flow as any other change.

## Steer the agent

Append project-specific instructions by committing a prompt file to the repo and
passing `--prompt-file`, so the guidance is version-controlled and reviewed
alongside your code:

```bash theme={null}
npx momentic ai explore diff --prompt-file .momentic/explore-prompt.md
```

Use `--prompt` for a quick inline override:

```bash theme={null}
npx momentic ai explore diff --prompt "Focus on the checkout and billing flows."
```

See [Configure the agent](/docs/coding-agents/explore#custom-instructions) for more
on custom instructions and the knowledge base.

Use `--granularity` when the default coverage depth is too broad or too
specific:

```bash theme={null}
npx momentic ai explore diff --granularity high
```

`low` covers the happy path of the main flows plus important failure states
(e.g. a failed login), `medium` covers the happy path of every interaction plus
important failure states, and `high` covers every flow in depth including the
happy path and its different failure modes. The flag overrides the project
setting for that run. To cap the number of tests instead, pass
`--budget <tests>`.

For full-app seeding, run `momentic ai explore latest` instead of a diff. Seed
runs default to a 60 minute timeout because they map the whole product; diff
runs default to 15 minutes. Pass `--timeout <minutes>` to override either
default.

## Variations

For large repositories, run explore on a schedule or on demand instead of on
every push to `main` by swapping the trigger. Pass an explicit commit range
(`base...head`) when the window is not the last commit:

```yaml theme={null}
on:
  workflow_dispatch:
  schedule:
    - cron: "0 9 * * 1" # every Monday at 09:00 UTC
```

To hunt for product bugs instead of building tests, run a
[bug bash](/docs/guides/explore/bug-bash) with the same discovery.

See the [`momentic ai explore`](/docs/cli-reference/momentic/commands/ai#explore)
reference for every flag. The same pattern works on
[GitLab CI](/docs/running-tests/ci/gitlab-ci),
[CircleCI](/docs/running-tests/ci/circleci), [Jenkins](/docs/running-tests/ci/jenkins),
and [custom setups](/docs/running-tests/ci/custom-setups).