Turborepo orchestrates task execution across monorepo packages, parallelising builds, tests, and lints with a content-addressed remote cache. UUID v7 as a build correlation ID threads through every task log entry, cache miss record, and deployment event — making it possible to reconstruct the full build timeline from logs alone. See DevOpsDays Amsterdam 2026 for the CI/CD pipeline pattern.

Inject UUID v7 at pipeline start

# GitHub Actions
name: CI
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate build correlation ID
        run: |
          BUILD_ID=$(node -e "const {v7}=require('uuid');console.log(v7())")
          echo "BUILD_ID=$BUILD_ID" >> $GITHUB_ENV
          echo "::notice::Build ID: $BUILD_ID"

      - name: Run Turborepo pipeline
        run: npx turbo run build test lint
        env:
          # BUILD_ID is available to all turbo tasks via process.env.BUILD_ID
          BUILD_ID: ${{ env.BUILD_ID }}

The UUID v7 BUILD_ID encodes the exact millisecond the pipeline started — parseInt(BUILD_ID.replace(/-/g,'').slice(0,12), 16) gives the Unix ms timestamp.

turbo.json — pass BUILD_ID to deployment tasks only

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "outputs": ["dist/**", ".next/**"],
      "dependsOn": ["^build"]
      // No env: BUILD_ID here — keeps build cache valid across runs
    },
    "test": {
      "dependsOn": ["build"]
      // Same: no BUILD_ID in env — test results are cached by source hash
    },
    "deploy": {
      "dependsOn": ["build", "test"],
      "env": ["BUILD_ID"],  // BUILD_ID in env — deploy always runs, not cached
      "cache": false
    }
  }
}

Cacheable tasks (build, test, lint) must not include BUILD_ID in their env array — otherwise every build busts the remote cache. Only non-cacheable deployment tasks should reference BUILD_ID.

Structured logging with UUID v7 build ID

// apps/api/src/logger.ts
import pino from 'pino';

const logger = pino({
  base: {
    buildId: process.env.BUILD_ID,   // UUID v7 from CI
    service: process.env.npm_package_name,
  },
});

export default logger;
// Every log line includes buildId — searchable by time range using UUID v7 prefix
logger.info({ orderId: 'abc' }, 'Order created');
// → {"buildId":"018fbe3a-...","service":"api","orderId":"abc","msg":"Order created"}

See UUID v7 in Microservices for the correlation ID middleware pattern.

Remote cache tagging with UUID v7

Turborepo’s remote cache API accepts custom metadata — tag cache entries with the UUID v7 build ID for audit trails:

// Custom Turborepo remote cache adapter
export async function putArtifact(hash: string, artifact: Buffer) {
  await fetch(`https://cache.example.com/artifacts/${hash}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/octet-stream',
      'x-build-id': process.env.BUILD_ID!,    // UUID v7
      'x-artifact-tag': hash,
    },
    body: artifact,
  });
}

Cache entries tagged with a UUID v7 build ID allow querying “all artifacts from builds in the last 7 days” by timestamp-prefix filtering on the build ID — no separate timestamp index needed.

Further reading

External references

Frequently asked questions

How do I inject a UUID v7 build ID into a Turborepo pipeline?

Generate a UUID v7 in your CI entry script before running turbo run, export it as an environment variable (e.g. BUILD_ID), and include it in the globalEnv or env array in turbo.json so Turborepo includes it in cache keys. All tasks that depend on BUILD_ID will include it in their logs.

Does including a UUID v7 in the Turborepo cache key break remote caching?

Yes — if you add BUILD_ID to a task's env array, every build gets a unique cache key and remote cache hits will never occur for that task. Only include BUILD_ID in globalEnv for tasks that should always run (like deployment). For cacheable tasks (build, test, lint), pass the UUID v7 as a log annotation rather than a cache-busting env var.

Why use UUID v7 instead of UUID v4 for CI build IDs?

UUID v7 embeds the pipeline start timestamp in the first 12 hex characters. Build IDs in log aggregators like Datadog, Grafana Loki, or CloudWatch naturally sort chronologically without a separate startedAt field. This makes "show me all builds in the last hour" queries a timestamp-prefix filter rather than a full-table scan. See UUID v7 in Microservices — trace IDs.