From ab04cd6620a481aa25491828d164ceea792ec5f9 Mon Sep 17 00:00:00 2001 From: frostebite Date: Thu, 5 Mar 2026 07:22:57 +0000 Subject: [PATCH] docs(orchestrator): submodule profiles, local caching, LFS agents, git hooks Documents orchestrator build services: - Submodule profiles: YAML format, glob patterns, variant overlays, auth - Local build caching: Library + LFS, cache key scheme, restore/save - Custom LFS transfer agents: git config setup, elastic-git-storage - Git hooks: lefthook/husky detection, skip lists, disable mechanism Co-Authored-By: Claude Opus 4.6 --- docs/orchestrator/build-services.md | 158 ++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/orchestrator/build-services.md diff --git a/docs/orchestrator/build-services.md b/docs/orchestrator/build-services.md new file mode 100644 index 000000000..c712c42df --- /dev/null +++ b/docs/orchestrator/build-services.md @@ -0,0 +1,158 @@ +# Orchestrator Build Services + +Services that run during the build lifecycle to handle submodules, caching, LFS, and git hooks. These work with any provider (local, AWS, K8s, GCP, Azure, or custom CLI providers). + +## Submodule Profiles + +Selectively initialize submodules from a YAML profile instead of cloning everything. Useful for monorepos where builds only need a subset of submodules. + +### Profile format + +```yaml +primary_submodule: MyGameFramework +submodules: + - name: CoreFramework + branch: main # initialize this submodule + - name: OptionalModule + branch: empty # skip this submodule + - name: Plugins* # glob pattern — matches PluginsCore, PluginsAudio, etc. + branch: main +``` + +- `branch: main` — initialize the submodule on its configured branch +- `branch: empty` — skip the submodule entirely (checked out to an empty branch) +- Glob patterns with trailing `*` match multiple submodules by prefix + +### Variant overlays + +A variant file merges on top of the base profile. Use variants for build-type or platform-specific overrides. + +```yaml +# server-variant.yml — override for server builds +submodules: + - name: ClientOnlyAssets + branch: empty # skip client assets for server builds +``` + +### Inputs + +| Input | Default | Description | +|-------|---------|-------------| +| `submoduleProfilePath` | — | Path to YAML submodule profile | +| `submoduleVariantPath` | — | Path to variant overlay (merged on top of profile) | +| `submoduleToken` | — | Auth token for private submodule clones | + +### How it works + +1. Parses the profile YAML and optional variant overlay +2. Reads `.gitmodules` to discover all submodules +3. Matches each submodule against profile entries (exact name or glob pattern) +4. Initializes matched submodules on the specified branch; skips the rest +5. If `submoduleToken` is set, configures `git config url."https://{token}@github.com/".insteadOf` for auth + +--- + +## Local Build Caching + +Filesystem-based caching of the Unity Library folder and LFS objects between local builds. No external cache actions required. + +### How it works + +- Cache key: `{platform}-{version}-{branch}` (sanitized) +- Cache root: `localCacheRoot` > `$RUNNER_TEMP/game-ci-cache` > `.game-ci/cache` +- On restore: extracts `library-{key}.tar` / `lfs-{key}.tar` if they exist +- On save: creates tar archives of the Library and LFS folders +- Garbage collection removes cache entries that haven't been accessed recently + +### Inputs + +| Input | Default | Description | +|-------|---------|-------------| +| `localCacheEnabled` | `false` | Enable filesystem caching | +| `localCacheRoot` | — | Cache directory override | +| `localCacheLibrary` | `true` | Cache Unity Library folder | +| `localCacheLfs` | `true` | Cache LFS objects | + +### Example + +```yaml +- uses: game-ci/unity-builder@main + with: + providerStrategy: local + localCacheEnabled: true + localCacheRoot: /mnt/cache # optional — persistent disk + targetPlatform: StandaloneLinux64 +``` + +--- + +## Custom LFS Transfer Agents + +Register external Git LFS transfer agents (like [elastic-git-storage](https://github.com/frostebite/elastic-git-storage)) that handle LFS object storage via custom backends. + +### How it works + +Configures git to use a custom transfer agent via: +``` +git config lfs.customtransfer.{name}.path +git config lfs.customtransfer.{name}.args +git config lfs.standalonetransferagent {name} +``` + +The agent name is derived from the executable filename. + +### Inputs + +| Input | Default | Description | +|-------|---------|-------------| +| `lfsTransferAgent` | — | Path to custom LFS agent executable | +| `lfsTransferAgentArgs` | — | Arguments passed to the agent | +| `lfsStoragePaths` | — | Sets `LFS_STORAGE_PATHS` environment variable | + +### Example + +```yaml +- uses: game-ci/unity-builder@main + with: + providerStrategy: local + lfsTransferAgent: ./tools/elastic-git-storage + lfsTransferAgentArgs: --config ./lfs-config.yml + targetPlatform: StandaloneLinux64 +``` + +--- + +## Git Hooks + +Detect and install lefthook or husky during builds. Disabled by default for build performance. + +### How it works + +1. Detects hook framework: looks for `lefthook.yml` / `.lefthook.yml` (lefthook) or `.husky/` directory (husky) +2. If enabled, runs `npx lefthook install` or sets up husky +3. If disabled (default), sets `core.hooksPath` to an empty directory to bypass all hooks +4. Skip list: specific hooks can be skipped via environment variables (`LEFTHOOK_EXCLUDE` for lefthook, `HUSKY=0` for husky) + +### Inputs + +| Input | Default | Description | +|-------|---------|-------------| +| `gitHooksEnabled` | `false` | Install and run git hooks during build | +| `gitHooksSkipList` | — | Comma-separated list of hooks to skip | + +### Example + +```yaml +# Enable hooks but skip pre-commit +- uses: game-ci/unity-builder@main + with: + providerStrategy: local + gitHooksEnabled: true + gitHooksSkipList: pre-commit,prepare-commit-msg + targetPlatform: StandaloneLinux64 +``` + +## Related + +- [Provider Plugins](provider-plugins.md) — CLI provider protocol, dynamic loading, provider interface +- [Cloud Providers](cloud-providers.md) — GCP Cloud Run and Azure ACI configuration