> ## 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.

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile).
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# Run a nightly regression suite

> Run the whole suite on a schedule against staging, sharded and merged into one run group.

The nightly job runs the whole suite against staging or production on a
schedule. It catches the regressions that PR-scoped checks miss.

## The workflow

The job installs `momentic` from `devDependencies`, so your lockfile pins the
CLI version. Add it once with `npm install -D momentic`.

```yaml .github/workflows/nightly.yml theme={null}
name: Nightly regression

on:
  schedule:
    - cron: "0 6 * * *" # 06:00 UTC
  workflow_dispatch: # manual trigger for debugging

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    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 shard ${{ matrix.shard }}
        run: |
          npx momentic run -y \
            --env staging \
            --shard-index ${{ matrix.shard }} \
            --shard-count 4 \
            --output-dir test-results/shard-${{ matrix.shard }}

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

  upload:
    runs-on: ubuntu-latest
    if: always()
    needs: test
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - uses: actions/download-artifact@v4
        with:
          path: test-results
          pattern: test-results-*
          merge-multiple: true
      - run:
          npx momentic results merge --output-dir test-results/merged
          test-results
      - run: npx momentic results upload test-results/merged

      - name: Triage failures
        run:
          npx momentic ai triage test-results/merged --yes --timeout-minutes 10
```

## Decisions

* **Shards.** Size `--shard-count` to keep each shard under \~15 minutes. Hosted
  browsers (`browser.remoteBrowser: true`) remove the browser footprint from
  your runners and raise parallelism; see
  [hosted test environments](/docs/running-tests/hosted-test-environments).
* **Environment.** `--env staging` picks the `staging` entry in
  `momentic.config.yaml`; secrets for it live in CI, not the repo. See
  [environments](/docs/configuration/environments).
* **One run group.** Merging shard output keeps the dashboard view and triage
  scoped to the whole night, not four partial views.
* **Triage in the same job.** Running `ai triage` after the upload lets
  [auto-maintenance](/docs/reliability/auto-maintenance) repair drifted tests before
  the next night, and classifications land on the merged run group.
* **`workflow_dispatch`.** Keep the manual trigger; debugging a nightly should
  not require a fake commit.

## Triage failures

A nightly suite fails more often than a PR gate, by design. Keep it actionable:

* Quarantine flakes instead of deleting them; they keep producing data.
* Give each test an `owner:` label so the right person reads the failure.
* Watch the trend, not one night: a test that fails twice in a week wants a fix,
  not a retry.

## Related

* [Common CI setups](/docs/guides/common-setups)
* [AI test maintenance](/docs/reliability/auto-maintenance)
* [Results and reporting](/docs/running-tests/results)