> ## 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`](/cli-reference/momentic/commands/ai#explore) diffs a
commit range, identifies the user journeys that changed, and with `--build`
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](/ai/explore) overview for the concept.

Run it on pushes to `main` - the same way Momentic runs explore on its own
repository. Each merge to `main` is explored once, against the change that just
landed, so coverage is authored for work that has already merged rather than
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: write
  pull-requests: write

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 --build
```

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

`MOMENTIC_API_KEY` authenticates the run.
[Create one here](https://app.momentic.ai/settings/api-keys) and add it as a
repository secret. The `contents: write` and `pull-requests: write` permissions
let the [Momentic GitHub App](/integrations/github) open the pull request, which
uses your repository's
[pull request template](/integrations/github#pull-request-templates).

Drop `--build` to have the agent only discover and log the changed journeys
without authoring tests - 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 or `pull-requests: write`, so it is the option for forked-PR runs.
* `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 with `--prompt` (or `--prompt-file` to load
them from a file), or set a default custom prompt in
[Settings > Explore](https://app.momentic.ai/settings/explore):

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

## 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 `--base`/`--head`
when the range is not the last commit:

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

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