Workspace Configuration

Complete API reference for the .moon/workspace configuration schema

The .moon/workspace.* configuration file defines workspace-level settings for moon, including project discovery, version control, caching, and more. This file is required at the root of your workspace.

Configuration File

Location: .moon/workspace.yml or .moon/workspace.json

Type: WorkspaceConfig

Schema

Core Settings

projects · WorkspaceProjects · required

Configures all projects within the workspace to create a project graph. Supports three formats:

• Map format: Explicit mapping of project IDs to source paths
• Glob format: Array of glob patterns to auto-discover projects
• Both format: Object with sources, globs, and globFormat fields

# Map format
projects:
  web: 'apps/web'
  api: 'apps/api'

# Glob format
projects:
  - 'apps/*'
  - 'packages/*'

# Both format
projects:
  globs:
    - 'apps/*'
  sources:
    www: 'www'
  globFormat: 'source-path'

extends · string | string[]

Extends one or many workspace configuration files. Supports relative file paths or HTTPS URLs.

Settings are merged recursively with local configuration taking precedence.

extends: 'https://example.com/.moon/workspace.yml'

versionConstraint · string

Requires a specific version of the moon binary using a semver requirement.

versionConstraint: '>=1.20.0'

defaultProject · string

The default project to focus on when no project scope is specified for task targets.

defaultProject: 'web'

_{Added in v2.0.0}

telemetry · boolean · default: true

Collects anonymous usage information and checks for new moon versions.

Can be controlled via MOON_TELEMETRY environment variable.

telemetry: false

Project Management

codeowners · CodeownersConfig

Configures code ownership rules for generating a CODEOWNERS file.

Show properties

globalPaths · object

File patterns and their owners at the workspace level.

codeowners:
  globalPaths:
    '*': ['@admins']
    'config/': ['@infra']

orderBy · 'file-source' | 'project-id' · default: "file-source"

Order in which code owners are listed in the CODEOWNERS file.

sync · boolean · default: false

Automatically generates and syncs a CODEOWNERS file.

_{Added in v1.8.0}

constraints · ConstraintsConfig

Configures boundaries and constraints between projects.

Show properties

enforceLayerRelationships · boolean · default: true

Enforces allowed relationships between projects based on their layer and stack settings.

Layer hierarchy: automation → application → tool → library → scaffolding → configuration → unknown

constraints:
  enforceLayerRelationships: true

tagRelationships · object

Enforces allowed relationships based on project tags.

constraints:
  tagRelationships:
    next: ['react']

Version Control

vcs · VcsConfig

Configures the version control system integration.

Show properties

client · 'git' · default: "git"

The VCS tool/binary being used.

provider · 'github' | 'gitlab' | 'bitbucket' | 'other' · default: "github"

The service provider hosting the repository.

defaultBranch · string · default: "master"

The default branch for comparing differences.

vcs:
  defaultBranch: 'main'

remoteCandidates · string[] · default: ["origin","upstream"]

Remote candidates to query for merge bases.

hooks · object

Mapping of hook names to command lists.

vcs:
  hooks:
    pre-commit:
      - 'moon run :lint --affected'

hookFormat · 'native' | 'bash' · default: "native"

Shell format for generated hook files.

_{Added in v1.29.0}

sync · boolean · default: false

Automatically generates and syncs hook scripts.

_{Added in v1.9.0}

Action Pipeline

pipeline · PipelineConfig

Configures aspects of task running and the action pipeline.

Show properties

autoCleanCache · boolean · default: true

Automatically cleans cached artifacts older than cacheLifetime.

_{Added in v1.24.0}

cacheLifetime · string · default: "7 days"

Maximum lifetime of cached artifacts before being marked stale.

pipeline:
  cacheLifetime: '24 hours'

installDependencies · boolean | string[] · default: true

Runs dependency installation actions before tasks.

# Disable all
pipeline:
  installDependencies: false

# Only for specific toolchains
pipeline:
  installDependencies: ['node']

_{Added in v1.34.0}

syncWorkspace · boolean · default: true

Runs workspace sync action before all other actions.

_{Added in v1.34.0}

syncProjects · boolean | string[] · default: true

Runs project sync action before tasks.

_{Added in v1.34.0}

logRunningCommand · boolean · default: false

Logs the task’s command and arguments when running.

inheritColorsForPipedTasks · boolean · default: true

Forces colors to be inherited for piped task output.

killProcessThreshold · number · default: 2000

Threshold in milliseconds to force kill processes after receiving a signal.

_{Added in v1.32.1}

Hashing & Caching

hasher · HasherConfig

Configures aspects of the smart hashing layer.

Show properties

optimization · 'accuracy' | 'performance' · default: "accuracy"

Optimization level for hashing dependency versions.

• accuracy: Uses resolved versions from lockfile
• performance: Uses version ranges from manifest

walkStrategy · 'glob' | 'vcs' · default: "vcs"

File system walking strategy for discovering inputs.

• glob: Walks using glob patterns
• vcs: Extracts files from VCS working tree

warnOnMissingInputs · boolean · default: true

Logs warnings when attempting to hash missing inputs.

ignorePatterns · string[]

Glob patterns to filter and ignore files during hashing.

hasher:
  ignorePatterns:
    - '**/*.png'

_{Added in v1.10.0}

ignoreMissingPatterns · string[]

Glob patterns to ignore missing input warnings.

hasher:
  ignoreMissingPatterns:
    - '**/.env.*'

_{Added in v1.10.0}

Remote Caching

remote · RemoteConfig

Configures remote service for cloud-based caching.

Show properties

host · string · required

Host URL for uploading/downloading artifacts. Supports grpc(s):// and http(s):// protocols.

remote:
  host: 'grpcs://cache.example.com:9092'

api · 'grpc' | 'http' · default: "grpc"

API format of the remote server.

_{Added in v1.32.0}

auth · object

Authentication configuration.

Show properties

token · string

Environment variable name containing Bearer token.

headers · object

HTTP headers to include in requests.

_{Added in v1.32.0}

cache · object

Cache layer configuration.

Show properties

instanceName · string · default: "moon-outputs"

Unique identifier for partitioning remote instances.

compression · 'none' | 'zstd' · default: "none"

Compression format for blobs (gRPC only).

_{Added in v1.31.0}

localReadOnly · boolean · default: false

When local, only download blobs; don’t upload.

_{Added in v1.40.0}

verifyIntegrity · boolean · default: false

Verify blob digests/hashes when downloading.

_{Added in v1.36.0}

tls · object

Server-only TLS authentication.

Show properties

cert · string

Path to CA certificate.

domain · string

Domain for certificate verification.

assumeHttp2 · boolean

Assume HTTP/2 support.

mtls · object

Mutual TLS authentication.

Show properties

caCert · string

Path to CA certificate.

clientCert · string

Path to client certificate.

clientKey · string

Path to client private key.

domain · string

Domain for certificate verification.

assumeHttp2 · boolean

Assume HTTP/2 support.

_{Added in v1.30.0}

Code Generation

generator · GeneratorConfig

Configures the template generator.

Show properties

templates · string[] · default: ["./templates"]

Paths where templates are located. Supports:

• File system paths (relative from workspace root)
• Git repositories: git://github.com/user/repo#branch
• npm packages: npm://@scope/package#1.2.3

generator:
  templates:
    - './templates'
    - 'git://github.com/moonrepo/templates#master'

_{Git/npm support added in v1.23.0}

Notifications

notifier · NotifierConfig

Configures how moon sends notifications.

Show properties

webhookUrl · string

HTTPS URL where pipeline events are posted.

notifier:
  webhookUrl: 'https://api.example.com/webhook'

acknowledge · boolean · default: false

Waits for webhook response and validates 2xx status.

terminalNotifications · 'always' | 'failure' | 'success' | 'task-failure'

Display OS notifications for pipeline events.

_{Added in v1.38.0}

Docker Integration

docker · DockerConfig

Configures Docker integration.

Show properties

prune · object

Docker pruning configuration.

Show properties

deleteVendorDirectories · boolean · default: true

Delete vendor directories while pruning.

installToolchainDependencies · boolean · default: true

Install production dependencies after pruning.

scaffold · object

Docker scaffolding configuration.

Show properties

configsPhaseGlobs · string[]

Globs for copying additional files to workspace skeleton.

docker:
  scaffold:
    configsPhaseGlobs:
      - '**/package.json'

_{Added in v1.27.0}

Experiments

experiments · ExperimentsConfig

Enable or disable experimental features.

Show properties

fasterGlobWalk · boolean · default: true

Uses concurrent glob walking (1.5-2x faster).

_{Added in v1.34.0}

gitV2 · boolean · default: true

Uses improved Git implementation with better submodule support.

_{Added in v1.34.0}

_{Added in v1.11.0}

Complete Example

.moon/workspace.yml

projects:
  globs:
    - 'apps/*'
    - 'packages/*'
  sources:
    www: 'www'

versionConstraint: '>=1.20.0'
defaultProject: 'web'

vcs:
  provider: 'github'
  defaultBranch: 'main'
  hooks:
    pre-commit:
      - 'moon run :lint :format --affected --status=staged'
  sync: true

hasher:
  optimization: 'performance'
  ignorePatterns:
    - '**/*.log'
    - '**/*.tmp'

pipeline:
  cacheLifetime: '7 days'
  autoCleanCache: true

remote:
  host: 'grpcs://cache.example.com:9092'
  auth:
    token: 'MOON_REMOTE_TOKEN'
  cache:
    instanceName: 'my-repo'
    compression: 'zstd'

generator:
  templates:
    - './templates'
    - 'git://github.com/org/templates#main'

codeowners:
  sync: true
  globalPaths:
    '*': ['@admins']

constraints:
  enforceLayerRelationships: true
  tagRelationships:
    react: ['frontend']

telemetry: true

Related

• Workspace Concepts
• Project Configuration
• Tasks Configuration
• Remote Caching Guide