.moon/workspace

The .moon/workspace.* file configures projects and services in the workspace. This file is required.

File Location

Path: .moon/workspace.yml or .moon/workspace.json
Format: YAML or JSON
Required: Yes

Configuration Options

`extends`

Defines one or many external .moon/workspace.*’s to extend and inherit settings from. Perfect for reusability and sharing configuration across repositories and projects.

.moon/workspace.yml

extends: 'https://raw.githubusercontent.com/organization/repository/master/.moon/workspace.yml'

Settings will be merged recursively for blocks, with values defined in the local configuration taking precedence over those defined in the extended configuration. However, the projects setting does not merge!

`projects` (required)

Defines the location of all projects within the workspace. Supports either a manual map of projects (default), a list of globs in which to automatically locate projects, or both.

Projects that depend on each other and form a cycle must be avoided! While we do our best to avoid an infinite loop and disconnect nodes from each other, there’s no guarantee that tasks will run in the correct order.

Using a map

When using a map, each project must be manually configured and requires a unique name as the map key.

.moon/workspace.yml

projects:
  admin: 'apps/admin'
  apiClients: 'packages/api-clients'
  designSystem: 'packages/design-system'
  web: 'apps/web'

Using globs

Provide a list of globs to automatically locate all project folders.

.moon/workspace.yml

projects:
  - 'apps/*'
  - 'packages/*'
  # Only shared folders with a moon configuration
  - 'shared/*/moon.yml'

Using both map and globs

.moon/workspace.yml

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

You can also customize the format of project IDs for glob discovered projects:

.moon/workspace.yml

projects:
  globFormat: 'source-path'
  globs:
    - 'packages/**/moon.yml'

`defaultProject`

Defines the default project to focus on when no project scope is specified on the command line for task targets.

.moon/workspace.yml

defaultProject: 'web'

`codeowners`

Configures code owners (CODEOWNERS) integration across the entire workspace.

globalPaths

Defines file patterns and their owners at the workspace-level.

.moon/workspace.yml

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

orderBy

The order in which code owners are listed in the CODEOWNERS file. Accepts “file-source” (default) or “project-id”.

.moon/workspace.yml

codeowners:
  orderBy: 'project-id'

sync

Automatically generate a CODEOWNERS file by aggregating and syncing all project owners. Defaults to false.

.moon/workspace.yml

codeowners:
  sync: true

`constraints`

Configures constraints between projects that are enforced during project graph generation.

enforceLayerRelationships

Enforces allowed relationships between a project and its dependencies based on the project’s layer and stack settings.

Layer	Description
`automation`	An automated testing suite, like E2E, integration, or visual tests.
`application`	An application of any kind.
`tool`	An internal tool, CLI, one-off script, etc.
`library`	A self-contained, shareable, and publishable set of code.
`scaffolding`	Templates or generators for scaffolding.
`configuration`	Configuration files or infrastructure.
`unknown`	When not configured.

.moon/workspace.yml

constraints:
  enforceLayerRelationships: false

tagRelationships

Enforces allowed relationships between a project and its dependencies based on the project’s tags setting.

.moon/workspace.yml

constraints:
  tagRelationships:
    next: ['react']

`docker`

Configures Docker integration for the entire workspace.

prune settings

deleteVendorDirectories: Automatically delete vendor directories (package manager dependencies, build targets, etc) while pruning. Defaults to true.

.moon/workspace.yml

docker:
  prune:
    deleteVendorDirectories: false

installToolchainDependencies: Automatically install production dependencies for all required toolchains. Defaults to true.

.moon/workspace.yml

docker:
  prune:
    installToolchainDependencies: false

scaffold settings

configsPhaseGlobs: List of globs to copy additional workspace-relative files into the .moon/docker/workspace skeleton.

.moon/workspace.yml

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

`experiments`

Enable or disable experiments that alter core functionality.

Experiments are a work in progress and may be buggy. Please report any issues you encounter!

.moon/workspace.yml

experiments:
  fasterGlobWalk: true
  gitV2: true

`generator`

Configures aspects of the template generator.

.moon/workspace.yml

generator:
  templates:
    - './templates'
    - 'file://./other/templates'
    - 'git://github.com/moonrepo/templates#master'
    - 'npm://@moonrepo/templates#1.2.3'

`hasher`

Configures aspects of the smart hashing layer.

ignoreMissingPatterns

List of glob patterns to filter and ignore files when warnings are logged for missing inputs.

.moon/workspace.yml

hasher:
  ignoreMissingPatterns:
    - '**/.eslintrc.*'
    - '**/*.config.*'

ignorePatterns

List of glob patterns used to filter and ignore files during the inputs hashing process.

.moon/workspace.yml

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

optimization

Determines the optimization level when hashing content.

accuracy (default) - Use resolved value in the lockfile
performance - Use value defined in the manifest

.moon/workspace.yml

hasher:
  optimization: 'performance'

walkStrategy

Defines the file system walking strategy.

glob - Walks using glob patterns
vcs (default) - Calls out to VCS to extract files

.moon/workspace.yml

hasher:
  walkStrategy: 'glob'

warnOnMissingInputs

Log warnings when attempting to hash an input that does not exist. Defaults to true.

.moon/workspace.yml

hasher:
  warnOnMissingInputs: false

`notifier`

Configures how moon notifies and interacts with a developer or an external system.

.moon/workspace.yml

notifier:
  terminalNotifications: 'always' # or 'failure', 'success', 'task-failure'
  webhookUrl: 'https://api.company.com/some/endpoint'
  acknowledge: false

`pipeline`

Configures aspects of task running and the action pipeline.

autoCleanCache

Automatically cleans cached artifacts older than cacheLifetime. Defaults to true.

.moon/workspace.yml

pipeline:
  autoCleanCache: false

cacheLifetime

The maximum lifetime of cached artifacts. Defaults to “7 days”.

.moon/workspace.yml

pipeline:
  cacheLifetime: '24 hours'

installDependencies

Runs install actions within the pipeline before running an applicable task. Defaults to true.

.moon/workspace.yml

pipeline:
  installDependencies: false
  # Or specific toolchains
  installDependencies: ['node']

syncProjects

Runs the SyncProject action within the pipeline. Defaults to true.

.moon/workspace.yml

pipeline:
  syncProjects: false
  # Or specific projects
  syncProjects: ['app']

syncWorkspace

Runs the SyncWorkspace action within the pipeline. Defaults to true.

.moon/workspace.yml

pipeline:
  syncWorkspace: false

`remote`

Configures a remote service, primarily for cloud-based caching of artifacts.

.moon/workspace.yml

remote:
  host: 'grpcs://your-host.com:9092'
  api: 'grpc' # or 'http'
  auth:
    token: 'ENV_VAR_NAME'
    headers:
      'X-Custom-Header': 'value'
  cache:
    compression: 'zstd'
    instanceName: 'moon-outputs'
    localReadOnly: false
    verifyIntegrity: false

`vcs`

Configures the version control system to utilize within the workspace.

.moon/workspace.yml

vcs:
  client: 'git'
  provider: 'github' # or 'gitlab', 'bitbucket', 'other'
  defaultBranch: 'master'
  remoteCandidates:
    - 'origin'
    - 'upstream'
  hooks:
    pre-commit:
      - 'moon run :lint :format --affected --status=staged --no-bail'
  hookFormat: 'bash' # or 'native'
  sync: true

`versionConstraint`

Defines a version requirement for the currently running moon binary.

.moon/workspace.yml

versionConstraint: '>=0.20.0'

`telemetry`

When enabled, will check for a newer moon version and send anonymous usage data. Defaults to true.

.moon/workspace.yml

telemetry: false

Complete Example

.moon/workspace.yml

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

defaultProject: 'web'

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

pipeline:
  cacheLifetime: '7 days'
  autoCleanCache: true

hasher:
  optimization: 'accuracy'
  warnOnMissingInputs: true

generator:
  templates:
    - './templates'

telemetry: true
versionConstraint: '>=1.0.0'

Get Started

Core Concepts

Guides

Configuration

.moon/workspace

File Location

Configuration Options

`extends`

`projects` (required)

Using a map

Using globs

Using both map and globs

`defaultProject`

`codeowners`

`constraints`

`docker`

`experiments`

`generator`

`hasher`

`notifier`

`pipeline`

`remote`

`vcs`

`versionConstraint`

`telemetry`

Complete Example

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Configuration

​File Location

​Configuration Options

​extends

​projects (required)

​Using a map

​Using globs

​Using both map and globs

​defaultProject

​codeowners

​constraints

​docker

​experiments

​generator

​hasher

​notifier

​pipeline

​remote

​vcs

​versionConstraint

​telemetry

​Complete Example

Build docs developers (and LLMs) love

File Location

Configuration Options

`extends`

`projects` (required)

Using a map

Using globs

Using both map and globs

`defaultProject`

`codeowners`

`constraints`

`docker`

`experiments`

`generator`

`hasher`

`notifier`

`pipeline`

`remote`

`vcs`

`versionConstraint`

`telemetry`

Complete Example