SBT Multi-Repo Build & Test

Four commands for all SBT operations: build, status, refresh, reset.

When to use this skill

Use this skill when you need to:

• Compile or test any SBT project (single or multi-project)
• Collect scoped coverage while bypassing stale remote-cache pulls
• Publish local artifacts for downstream validation
• Understand dependencies between workspace repos
• Fix stale state after upstream changes
• Inspect test results from JUnit XML reports

Prerequisites

1. SBT and the required JDK installed (default: Java 17).
2. SBT repos under one workspace root, or define overrides in .sbt-workspace.conf.
3. python3 available for test report parsing and workspace graph helpers.
4. ~/.ivy2/.credentials present if the workspace resolves private artifacts.

Configuration

Create <workspace>/.sbt-workspace.conf only when you need overrides:

.java_version=17
.group_id=com.acme
shared-models=/absolute/path/to/shared-models

See references/CONFIG.md for full schema.

Commands

sbt_build.sh — Compile, test, publishLocal

The single command for all build operations. Accepts one project, several, or --all for the entire workspace. Automatically handles preflight, upstream dep publishing, log capture, and JUnit XML test report parsing.

bash <skill_dir>/scripts/sbt_build.sh <project-dir>... [options] -- <sbt-commands>
bash <skill_dir>/scripts/sbt_build.sh --all [options] -- <sbt-commands>

Examples:

# Compile one project
bash <skill_dir>/scripts/sbt_build.sh /path/to/service -- compile

# Run all tests (auto-parses JUnit XML reports)
bash <skill_dir>/scripts/sbt_build.sh /path/to/service -- test

# Test a specific subproject
bash <skill_dir>/scripts/sbt_build.sh /path/to/service -- "core / test"

# Collect coverage for a specific subproject test
bash <skill_dir>/scripts/sbt_build.sh /path/to/service --coverage -- "aws / testOnly com.example.AwsUserPaginationTest"

# Compile with auto-publish of missing upstream deps
bash <skill_dir>/scripts/sbt_build.sh /path/to/service --auto-publish-deps -- compile

# Compile several projects
bash <skill_dir>/scripts/sbt_build.sh /path/to/svc-a /path/to/svc-b -- compile

# Compile all workspace projects in dependency order
bash <skill_dir>/scripts/sbt_build.sh --all -- compile

# Compile + test everything with auto-publish
bash <skill_dir>/scripts/sbt_build.sh --all --auto-publish-deps -- test

# Publish locally at a specific version
bash <skill_dir>/scripts/sbt_build.sh /path/to/library --artifact-version 0.532.0 -- publishLocal

Use the exact scoped project ID reported by sbt_status.sh for subproject names. In multi-project builds the ID may differ from the published artifact name (e.g. myModule vs my-module).

rootPaths auto-detection: When --sbt-env dev is requested but the project has rootPaths/remoteCache settings AND external ProjectRef entries, the skill auto-falls back to non-dev mode. No manual intervention needed.

Coverage mode: --coverage keeps the user command as a normal SBT argument, but wraps it with setup/teardown commands in the same session: it disables maybePullRemoteCache, clears target/scala-*, scopes clean/coverageReport when a subproject is specified, and forces Test / fork := false so scoverage measurements are written in-process.

sbt_status.sh — Discover dependencies and workspace state

Single command for all discovery and diagnostics.

bash <skill_dir>/scripts/sbt_status.sh <project-dir> [options]

Default (no flags): Discovers the project's cross-repo dependencies, workspace artifacts, transitive deps, dirty repo warnings, version variables, and build configuration.

Examples:

# What does this project depend on?
bash <skill_dir>/scripts/sbt_status.sh /path/to/service

# Full workspace state: preflight + all repos + dependency graph
bash <skill_dir>/scripts/sbt_status.sh /path/to/service --workspace

# What happens if I change commons and rebuild service-a?
bash <skill_dir>/scripts/sbt_status.sh /path/to/service-a --plan-change /path/to/commons

# Where is this artifact being resolved from?
bash <skill_dir>/scripts/sbt_status.sh /path/to/service --verify platform-commons

sbt_refresh.sh — Fix stale state

Clears caches, publishes upstream deps, and rebuilds.

bash <skill_dir>/scripts/sbt_refresh.sh <project-dir> [options]

Examples:

# Full upstream publish + cache clear + rebuild (most common for cross-repo changes)
bash <skill_dir>/scripts/sbt_refresh.sh /path/to/service --publish-upstreams --clean-target --rebuild

# Clear caches for a specific artifact and rebuild
bash <skill_dir>/scripts/sbt_refresh.sh /path/to/service --artifact my-lib --version 0.532.0 --clean-target --rebuild

# Dry run to see what would happen
bash <skill_dir>/scripts/sbt_refresh.sh /path/to/service --publish-upstreams --dry-run

sbt_reset.sh — Wipe isolated cache and return to clean state

Removes all local publishes and cached artifacts so builds resolve from remote again.

bash <skill_dir>/scripts/sbt_reset.sh [options]

Examples:

# Full reset — everything from remote again
bash <skill_dir>/scripts/sbt_reset.sh

# Only wipe local publishes
bash <skill_dir>/scripts/sbt_reset.sh --local-only

# Preview what would be deleted
bash <skill_dir>/scripts/sbt_reset.sh --dry-run

Decision Table

Exit Codes

Important rules

1. Use sbt_build.sh for all compile, test, and publishLocal flows. It preserves full logs, auto-checks deps, and auto-parses test reports.
2. All skill-driven SBT runs use the isolated cache at ~/.sbt-build-cache (Ivy, Coursier, SBT boot, SBT global) to avoid contaminating system caches.
3. Use sbt_status.sh before guessing dependency order. Do not guess publish order.
4. Show the dry-run plan before running sbt_refresh.sh with --publish-upstreams for the first time in a session.
5. JUnit XML is the source of truth for test results. Console success only means SBT finished.

Parallel worktree builds

All SBT caches (Ivy, Coursier, SBT boot, SBT global) are isolated inside SBT_BUILD_CACHE_ROOT (default: ~/.sbt-build-cache). For parallel builds across git worktrees, set a different cache root per worktree:

# In worktree 1
export SBT_BUILD_CACHE_ROOT=~/.sbt-build-cache/wt-main

# In worktree 2
export SBT_BUILD_CACHE_ROOT=~/.sbt-build-cache/wt-feature-x

Each worktree gets its own publishLocal artifacts, Coursier downloads, and SBT boot files. No lock contention or cache corruption between parallel builds.

Note: The first build in a new cache root is slower due to cold Coursier and SBT boot caches. Subsequent builds are fast.

Error handling

Troubleshooting