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

# Buildkite

> Run Momentic tests from Buildkite, with sharding and secrets.

Example pipeline for running Momentic on
[Buildkite](https://buildkite.com/docs). More reference configs live in
[momentic-ai/examples](https://github.com/momentic-ai/examples).

Buildkite is auto-detected, so Momentic reads git metadata (branch, commit,
pipeline) from the agent automatically. For a given root `package.json`:

```json package.json theme={null}
{
  "name": "my-momentic-repo",
  "scripts": {},
  "devDependencies": {
    "momentic": "latest"
  }
}
```

Create a file called `.buildkite/pipeline.yml` in your repository with the
following contents:

```yaml .buildkite/pipeline.yml theme={null}
steps:
  - label: ":momentic: Test"
    commands:
      - npm install
      - npx momentic install-browsers --all
      - npx momentic run
      - npx momentic results upload test-results
```

## Authentication

To run any commands, you must authenticate with Momentic by providing the
`MOMENTIC_API_KEY` environment variable.

1. Create an API key in the
   [Momentic dashboard](https://app.momentic.ai/settings/api-keys) and copy the
   value.
2. Store it as a secret with the
   [Buildkite secrets](https://buildkite.com/docs/pipelines/security/secrets)
   tooling your agents use (the `secrets` Buildkite plugin, your secrets
   manager, or an agent environment hook). Avoid committing it to the pipeline
   file.
3. Expose it to the `momentic` steps as `MOMENTIC_API_KEY`:

```yaml .buildkite/pipeline.yml theme={null}
steps:
  - label: ":momentic: Test"
    env:
      MOMENTIC_API_KEY: "${MOMENTIC_API_KEY}"
    commands:
      - npm install
      - npx momentic install-browsers --all
      - npx momentic run
```

## Sharding

If you have a large test set, you can use sharding to run tests in parallel.
This can significantly speed up your CI runs.

Buildkite exposes the parallel job index as `BUILDKITE_PARALLEL_JOB` (0-indexed)
and the total as `BUILDKITE_PARALLEL_JOB_COUNT`. Momentic's `--shard-index` is
1-indexed, so add one. To collect every shard into a single run group in the
dashboard, add a step that merges and uploads results after the tests finish.

```yaml .buildkite/pipeline.yml theme={null}
steps:
  - label: ":momentic: Test %n"
    parallelism: 4
    artifact_paths:
      - "test-results/**/*"
    commands:
      - npm install
      - npx momentic install-browsers --all
      - |
        npx momentic run \
          --shard-index $(($BUILDKITE_PARALLEL_JOB + 1)) \
          --shard-count $BUILDKITE_PARALLEL_JOB_COUNT \
          --output-dir test-results/shard-$BUILDKITE_PARALLEL_JOB

  - wait: ~
    continue_on_failure: true

  - label: ":momentic: Merge and upload results"
    commands:
      - npm install
      - buildkite-agent artifact download "test-results/**/*" test-results
      - npx momentic results merge --output-dir test-results/merged test-results
      - npx momentic results upload test-results/merged
```

## Test Analytics

Momentic can emit a Buildkite-flavored JSON report with the `buildkite-json`
[reporter](/cli-reference/momentic/commands/run#output) for
[Buildkite Test Analytics](https://buildkite.com/docs/test-analytics):

```bash theme={null}
npx momentic run --reporter buildkite-json --reporter-dir reports
```