feat: add turbo-scm-base input for Turbo monorepo support in workflows and documentation (#196)

kb-typeform · web-flow · commit 2d7df614e9ee · 2026-03-11T11:49:42.000+01:00
Adds Turbo monorepo support and monorepo-aware build artifact handling
to the centralized frontend workflows.

## Why

`performance-analytics` is a Turborepo monorepo where builds output to
`apps/*/dist/` rather than a single root `dist/` directory. The existing
`build-output-dir` input only supports a single directory path, which
breaks both artifact upload (nothing found at root `dist/`) and download
(`upload-artifact@v4` strips the common prefix from glob paths, so files
restore to the wrong location).

## Changes

### Turbo SCM support
- New `turbo-scm-base` input on both `frontend-pr-workflow` and
`frontend-deploy-workflow`
- Sets `TURBO_SCM_BASE` env var on all build/test/deploy steps, enabling
Turbo's `--affected` flag

### Monorepo artifact handling
- New `build-artifact-path` input — glob pattern for `upload-artifact`
(e.g. `apps/*/dist`) to capture builds from all apps. Falls back to
`build-output-dir` for single-app repos.
- New `build-artifact-download-path` input — directory to extract
artifacts into. Needed because `upload-artifact@v4` strips the least
common ancestor from glob paths (e.g. `apps/*/dist` uploads as
`insights/dist/`, `dashboards/dist/`). Setting this to `apps` restores
the correct `apps/*/dist/` structure so deploy tools (`jarvis deploy
--path dist`) work from each app's directory.
diff --git a/.github/workflows/frontend-deploy-workflow.yml b/.github/workflows/frontend-deploy-workflow.yml
@@ -57,10 +57,26 @@ on:
         description: 'Clean command before build'
         type: string
         default: 'yarn clean'
+      # Monorepo artifact handling:
+      # - build-output-dir: relative path used by deploy tools (e.g. jarvis deploy --path dist)
+      #   from each app's directory. Single-app repos only need this one.
+      # - build-artifact-path: glob for upload-artifact to capture all app builds
+      #   (e.g. apps/*/dist). Defaults to build-output-dir when not set.
+      # - build-artifact-download-path: extraction dir — upload-artifact strips the
+      #   common prefix (e.g. apps/) from the glob, so we download into that prefix
+      #   to restore the correct directory structure. Defaults to build-output-dir.
       build-output-dir:
         description: 'Build output directory name (dist, build, lib, etc.)'
         type: string
         default: 'dist'
+      build-artifact-path:
+        description: 'Path pattern for build artifacts upload (supports globs for monorepos, e.g. apps/*/dist). Defaults to build-output-dir.'
+        type: string
+        default: ''
+      build-artifact-download-path:
+        description: 'Directory to download build artifacts into. For monorepos where upload-artifact strips the common prefix (e.g. apps/), set this to that prefix. Defaults to build-output-dir.'
+        type: string
+        default: ''
       
       # Deploy configuration
       deploy-command:
@@ -206,6 +222,12 @@ on:
         type: boolean
         default: true
       
+      # Turbo monorepo configuration
+      turbo-scm-base:
+        description: 'Git SHA for Turbo SCM base comparison (enables --affected flag for Turbo monorepos)'
+        type: string
+        default: ''
+      
       # Timeout configuration
       build-timeout:
         description: 'Build job timeout (minutes)'
@@ -299,6 +321,7 @@ jobs:
         run: ${{ inputs.pre-build-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Clean dist directory
         run: ${{ inputs.clean-command }}
@@ -308,6 +331,7 @@ jobs:
         env:
           PUBLIC_CDN_URL: ${{ inputs.cdn-url }}
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
           JARVIS_DATADOG_LOGS_ENABLED: ${{ inputs.jarvis-datadog-enabled }}
           JARVIS_DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY || secrets.DATADOG_API_KEY_FRONTEND_METRICS }}
           JARVIS_DATADOG_SITE: datadoghq.com
@@ -326,7 +350,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: build-${{ github.run_id }}
-          path: ${{ inputs.build-output-dir }}
+          path: ${{ inputs.build-artifact-path || inputs.build-output-dir }}
           retention-days: 1
   
   # Job 2: Unit Tests (runs in parallel with other tests)
@@ -363,11 +387,13 @@ jobs:
         run: ${{ inputs.pre-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Run unit tests
         run: ${{ inputs.unit-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Upload coverage
         if: always()
@@ -413,17 +439,19 @@ jobs:
         run: ${{ inputs.pre-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Download Build Artifacts
         uses: Typeform/.github/shared-actions/download-build-artifacts@v1
         with:
           artifact-name: ${{ needs.build.outputs.artifact-name }}
-          output-dir: ${{ inputs.build-output-dir }}
+          output-dir: ${{ inputs.build-artifact-download-path || inputs.build-output-dir }}
       
       - name: Run integration tests
         run: ${{ inputs.integration-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Upload test results
         if: always()
@@ -555,7 +583,7 @@ jobs:
         uses: Typeform/.github/shared-actions/download-build-artifacts@v1
         with:
           artifact-name: ${{ needs.build.outputs.artifact-name }}
-          output-dir: ${{ inputs.build-output-dir }}
+          output-dir: ${{ inputs.build-artifact-download-path || inputs.build-output-dir }}
       
       - name: Setup Jarvis
         uses: Typeform/.github/shared-actions/setup-jarvis@v1
@@ -577,6 +605,7 @@ jobs:
           DEBUG: jarvis
           # GitHub
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
           # AWS configuration
           AWS_REGION: ${{ inputs.aws-region }}
           AWS_ASSETS_BUCKET: ${{ inputs.cdn-bucket }}
diff --git a/.github/workflows/frontend-pr-workflow.yml b/.github/workflows/frontend-pr-workflow.yml
@@ -183,10 +183,26 @@ on:
         description: 'Deploy command'
         type: string
         default: 'yarn deploy:preview'
+      # Monorepo artifact handling:
+      # - build-output-dir: relative path used by deploy tools (e.g. jarvis deploy --path dist)
+      #   from each app's directory. Single-app repos only need this one.
+      # - build-artifact-path: glob for upload-artifact to capture all app builds
+      #   (e.g. apps/*/dist). Defaults to build-output-dir when not set.
+      # - build-artifact-download-path: extraction dir — upload-artifact strips the
+      #   common prefix (e.g. apps/) from the glob, so we download into that prefix
+      #   to restore the correct directory structure. Defaults to build-output-dir.
       build-output-dir:
         description: 'Build output directory name (dist, build, lib, etc.)'
         type: string
         default: 'dist'
+      build-artifact-path:
+        description: 'Path pattern for build artifacts upload (supports globs for monorepos, e.g. apps/*/dist). Defaults to build-output-dir.'
+        type: string
+        default: ''
+      build-artifact-download-path:
+        description: 'Directory to download build artifacts into. For monorepos where upload-artifact strips the common prefix (e.g. apps/), set this to that prefix. Defaults to build-output-dir.'
+        type: string
+        default: ''
       cdn-bucket:
         description: 'S3 bucket for assets'
         type: string
@@ -218,6 +234,12 @@ on:
         type: string
         default: 'staging'
       
+      # Turbo monorepo configuration
+      turbo-scm-base:
+        description: 'Git SHA for Turbo SCM base comparison (enables --affected flag for Turbo monorepos)'
+        type: string
+        default: ''
+      
       # Timeout configuration
       build-timeout:
         description: 'Build job timeout (minutes)'
@@ -304,10 +326,13 @@ jobs:
         run: ${{ inputs.pre-build-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Run linting
         if: inputs.run-linting
         run: ${{ inputs.lint-command }}
+        env:
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Clean dist directory
         run: ${{ inputs.clean-command }}
@@ -317,6 +342,7 @@ jobs:
         env:
           PUBLIC_CDN_URL: ${{ inputs.cdn-url }}
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
           JARVIS_DATADOG_LOGS_ENABLED: ${{ inputs.jarvis-datadog-enabled }}
           JARVIS_DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY || secrets.DATADOG_API_KEY_FRONTEND_METRICS }}
           JARVIS_DATADOG_SITE: datadoghq.com
@@ -336,7 +362,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: build-${{ github.run_id }}
-          path: ${{ inputs.build-output-dir }}
+          path: ${{ inputs.build-artifact-path || inputs.build-output-dir }}
           retention-days: 1
   
   # Job 2: Unit Tests (parallel with integration tests)
@@ -371,11 +397,13 @@ jobs:
         run: ${{ inputs.pre-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Run unit tests
         run: ${{ inputs.unit-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Upload coverage
         if: always()
@@ -417,6 +445,7 @@ jobs:
         run: ${{ inputs.pre-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Setup Playwright
         if: inputs.integration-test-framework == 'playwright'
@@ -426,12 +455,13 @@ jobs:
         uses: Typeform/.github/shared-actions/download-build-artifacts@v1
         with:
           artifact-name: ${{ needs.build.outputs.artifact-name }}
-          output-dir: ${{ inputs.build-output-dir }}
+          output-dir: ${{ inputs.build-artifact-download-path || inputs.build-output-dir }}
       
       - name: Run integration tests
         run: ${{ inputs.integration-test-command }}
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
       
       - name: Upload test results
         if: always()
@@ -469,7 +499,7 @@ jobs:
         uses: Typeform/.github/shared-actions/download-build-artifacts@v1
         with:
           artifact-name: ${{ needs.build.outputs.artifact-name }}
-          output-dir: ${{ inputs.build-output-dir }}
+          output-dir: ${{ inputs.build-artifact-download-path || inputs.build-output-dir }}
       
       - name: Setup Jarvis
         uses: Typeform/.github/shared-actions/setup-jarvis@v1
@@ -489,6 +519,7 @@ jobs:
         env:
           DEBUG: jarvis
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          TURBO_SCM_BASE: ${{ inputs.turbo-scm-base }}
           AWS_ASSETS_BUCKET: ${{ inputs.cdn-bucket }}
           AWS_CLOUDFRONT_DIST: ${{ inputs.cloudfront-dist }}
           PUBLIC_CDN_URL: ${{ inputs.cdn-url }}
diff --git a/reusable-workflows/frontend-pr-workflow/README.md b/reusable-workflows/frontend-pr-workflow/README.md
@@ -67,6 +67,7 @@ jobs:
 | `run-deep-purple` | Run Deep Purple E2E tests | `false` |
 | `deploy-preview` | Deploy preview environment | `true` |
 | `deploy-command` | Deploy command | `'yarn deploy:preview'` |
+| `turbo-scm-base` | Git SHA for Turbo SCM base comparison (enables `--affected` flag for Turbo monorepos). Sets `TURBO_SCM_BASE` env var on all command steps. | `''` |
 | `jarvis-branch` | Jarvis branch to use | `''` |
 | `jarvis-datadog-enabled` | Enable Jarvis Datadog logging | `true` |
 | `jarvis-datadog-env` | Datadog environment | `'staging'` |
@@ -277,6 +278,22 @@ with:
   run-unit-tests: true
 ```
 
+### performance-analytics (Turbo monorepo with --affected)
+```yaml
+with:
+  app-name: 'performance-analytics'
+  use-asdf: true
+  cache-mode: 'full'
+  turbo-scm-base: ${{ github.event.pull_request.base.sha }}
+  pre-build-command: 'echo "GRAPHQL_SCHEMA_URL=${{ vars.GRAPHQL_SCHEMA_URL }}" >> $GITHUB_ENV'
+  build-command: 'yarn dist:preview --affected'
+  run-unit-tests: true
+  unit-test-command: 'yarn verify --affected --concurrency=1'
+  run-integration-tests: true
+  integration-test-command: 'yarn test:integration --affected && yarn test:visual --affected'
+  run-deep-purple: false  # Handled separately via matrix job
+```
+
 ### hall-of-forms
 ```yaml
 with:
@@ -384,6 +401,7 @@ git push origin main
 - ✅ hall-of-forms
 - ✅ bob-the-builder
 - ✅ chief
+- ✅ performance-analytics (Turbo monorepo with `turbo-scm-base`)
 
 **All frontend applications**
 
