Build it

We will build the order service's pipeline in mangrove/order-service: CI-safe scripts, a timing-based shard split, the workflow, a quarantine list and the ruleset. The service is NestJS on Node 22 with Jest; action versions and Jest options are version dependent, so check them against your project. The split algorithm is also the browser exercise in the Practice section.

1. Make the scripts safe for CI

   CI calls npm scripts, so developers can run exactly the same checks locally. The NestJS starter's lint script fixes files in place; CI gets a version that only reports. --ci makes Jest fail on a missing snapshot instead of writing a new one.

   JSONCopy

   {
     "scripts": {
       "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
       "lint:ci": "eslint \"{src,apps,libs,test}/**/*.ts\" --max-warnings 0",
       "typecheck": "tsc --noEmit -p tsconfig.json",
       "test:ci": "jest --ci",
       "test:e2e": "jest --config test/jest-e2e.json",
       "build": "nest build"
     }
   }

   Commit package-lock.json. Without it, npm ci refuses to run and the npm cache has nothing to hash.

2. Record how long each test file takes

   Every integration shard saves a Jest JSON report as an artifact (step 4). Every week or two, download the reports from a green run on main and turn them into test/timings.json:

   JavaScriptCopy

   // scripts/timings.mjs: turn Jest --json reports into test/timings.json
   // usage: node scripts/timings.mjs report-1.json report-2.json ... > test/timings.json
   import { readFileSync } from 'node:fs';
   import path from 'node:path';
   
   const timings = {};
   for (const file of process.argv.slice(2)) {
     const report = JSON.parse(readFileSync(file, 'utf8'));
     for (const r of report.testResults) {            // one entry per test file
       const key = path.relative(process.cwd(), r.name).split(path.sep).join('/');
       timings[key] = Math.round((r.endTime - r.startTime) / 100) / 10; // ms to s, 1 decimal
     }
   }
   const sorted = Object.fromEntries(Object.entries(timings).sort(([a], [b]) => a.localeCompare(b)));
   console.log(JSON.stringify(sorted, null, 2));

   TerminalCopy

   gh run download 123456789 --pattern "jest-report-*"   # the run ID of a green main run
   node scripts/timings.mjs jest-report-*/report.json > test/timings.json

   Commit the new file in a small PR, so the timing data is reviewed like any other change.

3. Write the split script

   Each shard reads the full list of test files, computes the same longest-first split, and prints only its own files. Files in the quarantine list (step 6) are left out.

   JavaScriptCopy

   // scripts/split-tests.mjs: this shard's test files, balanced by recorded time
   // usage: node scripts/split-tests.mjs <shard 1..N> <N> < list-of-test-files
   import { existsSync, readFileSync } from 'node:fs';
   import path from 'node:path';
   
   const [shard, total] = process.argv.slice(2).map(Number);
   const read = (f, empty) => (existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : empty);
   const timings = read('test/timings.json', {});             // { "test/x.e2e-spec.ts": 41.2 }
   const skip = new Set(read('test/quarantine.json', []).map((q) => q.file));
   const files = readFileSync(0, 'utf8').split('\n').filter(Boolean)
     .map((f) => path.relative(process.cwd(), f).split(path.sep).join('/')) // same keys on any OS
     .filter((f) => !skip.has(f));
   
   const known = files.map((f) => timings[f]).filter((s) => s !== undefined);
   const guess = known.length ? known.reduce((a, b) => a + b, 0) / known.length : 1; // new file
   
   const shards = Array.from({ length: total }, () => ({ files: [], seconds: 0 }));
   files
     .map((file) => ({ file, seconds: timings[file] ?? guess }))
     .sort((a, b) => b.seconds - a.seconds || a.file.localeCompare(b.file)) // longest first
     .forEach((t) => {
       const target = shards.reduce((min, s) => (s.seconds < min.seconds ? s : min)); // emptiest
       target.files.push(t.file);
       target.seconds += t.seconds;
     });
   
   const mine = shards[shard - 1];
   console.error(`shard ${shard}/${total}: ${mine.files.length} files, about ${Math.round(mine.seconds)} s`);
   console.log(mine.files.join('\n'));                        // one path per line

   Try it locally. With the order service's ten timed files plus one new file, wallet-topup, which has no timing yet (the quarantine list is still empty at this point):

   TerminalCopy

   npx jest --config test/jest-e2e.json --listTests > all-tests.txt
   node scripts/split-tests.mjs 2 4 < all-tests.txt

   OutputCopy

   shard 2/4: 3 files, about 219 s
   test/orders.e2e-spec.ts
   test/delivery-slots.e2e-spec.ts
   test/riders.e2e-spec.ts

4. Write the workflow: triggers, concurrency and the fast jobs

   Create .github/workflows/ci.yml. Steps 4 and 5 are one file. Note the merge_group trigger: without it, the merge queue never gets a result.

   YAMLCopy

   name: CI
   on:
     pull_request:
       branches: [main]
     push:
       branches: [main]
     merge_group:                    # the merge queue tests each group with this event
   
   permissions:
     contents: read                  # the token can only read the code
   
   concurrency:
     group: ci-${{ github.event.pull_request.number || github.ref }}
     cancel-in-progress: ${{ github.event_name == 'pull_request' }}   # never cancel main
   
   jobs:
     lint:
       runs-on: ubuntu-latest
       timeout-minutes: 10
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with: { node-version: 22, cache: npm }   # restores npm's download folder
         - run: npm ci                              # exactly the lockfile, nothing else
         - run: npm run lint:ci
         - run: npm run typecheck
   
     unit:
       runs-on: ubuntu-latest
       timeout-minutes: 10
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with: { node-version: 22, cache: npm }
         - run: npm ci
         - run: npm run test:ci

5. Add the integration shards, the build and the gate

   Each shard gets its own Postgres and Redis. The health checks make the runner wait until both accept connections. strategy.job-total is the number of matrix jobs, so changing the shard list is a one-line edit.

   YAMLCopy

     integration:
       runs-on: ubuntu-latest
       timeout-minutes: 15
       strategy:
         fail-fast: false                  # finish every shard, show every failure
         matrix:
           shard: [1, 2, 3, 4]
       services:
         postgres:
           image: postgres:17
           env: { POSTGRES_PASSWORD: postgres }
           ports: ['5432:5432']
           options: --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
         redis:
           image: redis:7
           ports: ['6379:6379']
           options: --health-cmd "redis-cli ping" --health-interval 5s --health-retries 10
       env:
         DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
         REDIS_URL: redis://localhost:6379
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with: { node-version: 22, cache: npm }
         - run: npm ci
         - run: npx prisma migrate deploy  # the same migrations production runs
         - name: Run this shard's files
           run: |
             npx jest --config test/jest-e2e.json --listTests > all-tests.txt
             node scripts/split-tests.mjs ${{ matrix.shard }} ${{ strategy.job-total }} < all-tests.txt > shard.txt
             [ -s shard.txt ] || exit 0    # an empty shard has nothing to run
             npx jest --config test/jest-e2e.json --ci --runTestsByPath $(cat shard.txt) --json --outputFile=report.json
         - uses: actions/upload-artifact@v7
           if: always()                    # keep the report even when tests fail
           with: { name: 'jest-report-${{ matrix.shard }}', path: report.json, retention-days: 14 }

   The empty-shard guard matters: --runTestsByPath with no paths would run every test. Then the build and the one job the ruleset will require:

   YAMLCopy

     build:
       runs-on: ubuntu-latest
       timeout-minutes: 10
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with: { node-version: 22, cache: npm }
         - run: npm ci
         - run: npm run build
   
     ci-ok:                                # the only check the ruleset requires
       needs: [lint, unit, integration, build]
       if: always()                        # run even when a needed job failed or was skipped
       runs-on: ubuntu-latest
       timeout-minutes: 2
       steps:
         - name: Fail unless every needed job succeeded
           if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
           run: exit 1
         - run: echo "lint, unit, integration and build all passed"

6. Keep a quarantine list with owners

   The split script skips every file in test/quarantine.json. Each entry carries who owns the fix, the ticket and the date, so the list can be reviewed every week. If only one test in a big file is flaky, move that test into its own file first, so the rest keeps running.

   JSONCopy

   [
     {
       "file": "test/delivery-slots.e2e-spec.ts",
       "owner": "nadia",
       "ticket": "ORD-1412",
       "added": "2026-10-12",
       "reason": "builds a Now slot from the real clock; fails after 22:00"
     }
   ]

   A second, small workflow runs the quarantined files every night, so a fix shows up as green and a regression is still visible. It blocks nobody.

   YAMLCopy

   # .github/workflows/quarantine.yml (services and env as in the integration job)
   on:
     schedule:
       - cron: '30 1 * * *'          # every night at 01:30 UTC
   jobs:
     quarantined:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with: { node-version: 22, cache: npm }
         - run: npm ci
         - run: npx jest --config test/jest-e2e.json --ci --runTestsByPath $(node -p "require('./test/quarantine.json').map(q => q.file).join(' ')")

7. Require ci-ok and turn on the merge queue

   Merge the workflow first: GitHub only offers checks that have already run in the repository. Then edit the protect-main ruleset from Branching strategies, releases and versions so its status check rule requires only ci-ok:

   JSONCopy

   {
     "type": "required_status_checks",
     "parameters": {
       "strict_required_status_checks_policy": false,
       "required_status_checks": [{ "context": "ci-ok" }]
     }
   }

   In the same ruleset, tick Require merge queue, keep the merge method your team uses (Squash in dw-14), and leave Only merge non-failing pull requests on. Empty the bypass list, or keep only an admin role for emergencies. Then test the gate: push a PR with a failing test, confirm ci-ok goes red and the merge stays blocked, and run gh ruleset check main to see every rule that applies.