Workspace Configuration

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

Configuration Schemas

Workspace Configuration

Configuration File

Schema

Core Settings

Project Management

Version Control

Action Pipeline

Hashing & Caching

Remote Caching

Code Generation

Notifications

Docker Integration

Experiments

Complete Example

Build docs developers (and LLMs) love

Configuration Schemas

​Configuration File

​Schema

​Core Settings

​Project Management

​Version Control

​Action Pipeline

​Hashing & Caching

​Remote Caching

​Code Generation

​Notifications

​Docker Integration

​Experiments

​Complete Example

​Related

Build docs developers (and LLMs) love

Configuration File

Schema

Core Settings

Project Management

Version Control

Action Pipeline

Hashing & Caching

Remote Caching

Code Generation

Notifications

Docker Integration

Experiments

Complete Example

Related