CI integration

Nijam is built to run in CI. You don’t pass commit, branch, PR, or author by hand - the Vitest reporter detects them automatically from your CI provider, so each vitest run lands in history with full context.

The reporter prints the run’s dashboard link to stdout - both when the run starts and when it finishes - so it lands right in your CI run logs (and your terminal locally):

[nijam] run started - view it at https://www.nijam.dev/...
...
[nijam] run finalized (12/14 passed) - view it at https://www.nijam.dev/...

Most CI log viewers make the URL clickable - open it to jump straight from the build to the run in Nijam. Set silent: true to suppress all [nijam] output.

What’s detected

Commit, branch, PR number, CI run id, CI run URL, and the git author (email + name). Resolution order, per field:

CI-specific environment variables (see below)
Generic GIT_* / BRANCH / COMMIT_SHA variables
A git log / git rev-parse shell-out
Empty (branch is left unset → the dashboard shows “No Branch Info”)

Supported providers

Detected from GITHUB_SHA, GITHUB_REF_NAME, GITHUB_HEAD_REF, GITHUB_RUN_ID, GITHUB_REPOSITORY, GITHUB_SERVER_URL.

name: tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx vitest run
        env:
          NIJAM_API_KEY: ${{ secrets.NIJAM_API_KEY }}

Detected from CI_COMMIT_SHA, CI_COMMIT_REF_NAME, CI_PIPELINE_ID, CI_MERGE_REQUEST_IID, GITLAB_USER_EMAIL, GITLAB_USER_NAME, CI_COMMIT_AUTHOR.

tests:
  image: node:22
  script:
    - npm ci
    - npx vitest run
  variables:
    NIJAM_API_KEY: $NIJAM_API_KEY

Detected from CIRCLE_SHA1, CIRCLE_BRANCH, CIRCLE_BUILD_NUM, CIRCLE_PULL_REQUEST, CIRCLE_BUILD_URL.

jobs:
  test:
    docker: [{ image: cimg/node:22.0 }]
    steps:
      - checkout
      - run: npm ci
      - run: npx vitest run
        environment:
          NIJAM_API_KEY: $NIJAM_API_KEY

Detected from BITBUCKET_COMMIT, BITBUCKET_BRANCH, BITBUCKET_PR_ID, BITBUCKET_BUILD_NUMBER, BITBUCKET_REPO_FULL_NAME, BITBUCKET_GIT_HTTP_ORIGIN.

pipelines:
  default:
    - step:
        image: node:22
        script:
          - npm ci
          - npx vitest run

Sharded runs

Running vitest --shard=<i>/<N> is auto-detected from Vitest’s config.shard. Every shard of the same CI run clubs into one Nijam run (they share the CI run id), each test execution is tagged with the 1-based shard index it ran on (i of N), and because Vitest knows the total, Nijam completes the run once every shard has reported. Nothing to configure, no post-matrix step.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx vitest run --shard=${{ matrix.shard }}/4
        env:
          NIJAM_API_KEY: ${{ secrets.NIJAM_API_KEY }}

Unlike the Playwright reporter, the Vitest reporter detects only native --shard: there is no NIJAM_SHARD_INDEX / NIJAM_SHARD_TOTAL override. To split test files across jobs without --shard, use the job matrix below.

Splitting across jobs

If you split your suite across several CI jobs (for example a job matrix by project or directory), they all club into one Nijam run when they share the CI run id, and a failure in any job flips that run to Failing right away. The dashboard shows running / failing live until the run completes.

When each job runs a different subset of tests, there’s no known total, so each job must not finalize on its own. Set autoComplete: false in the NijamReporter constructor (or the NIJAM_AUTO_COMPLETE=false env var), then add one post-matrix step that calls POST /v1/runs/complete to mark the run done - passing the CI run id the jobs shared (GITHUB_RUN_ID, CI_PIPELINE_ID, …) so it targets the right run.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        project: [web, api, shared, utils] # one subset per job
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx vitest run --project ${{ matrix.project }}
        env:
          NIJAM_API_KEY: ${{ secrets.NIJAM_API_KEY }}
          NIJAM_AUTO_COMPLETE: "false" # don't finalize per job

  summary:
    needs: [test] # after every project job
    if: always() # complete even if some failed
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -sf -X POST "https://api.nijam.dev/v1/runs/complete" \
            -H "Authorization: Bearer ${{ secrets.NIJAM_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{\"projectId\":\"<your-project-id>\",\"ciRunId\":\"$GITHUB_RUN_ID\",\"ciRunAttempt\":\"$GITHUB_RUN_ATTEMPT\"}"

A single vitest run needs none of this - it completes on its own.

Other CI systems

On a provider not listed above, set the generic variables and the reporter picks them up:

Variable	Maps to
`COMMIT_SHA`	commit
`BRANCH`	branch
`CI_RUN_ID`	CI run id
`CI_URL`	CI run URL

If none are set, the reporter still falls back to git, so local runs are attributed too. The full variable list lives in the CI variables reference.

What you need to push runs

To send runs and reports to Nijam, the reporter needs two things - set both in vitest.config.ts:

projectId - which project to push to. Not a secret; it just identifies the project.
apiKey - the only secret. Store it as NIJAM_API_KEY in your CI secrets and reference it via the environment.

Everything else - commit, branch, PR, CI link, author - is detected automatically.