Skip to main content

.moon/workspace.yml

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

.moon/workspace.yml
$schema: 'https://moonrepo.dev/schemas/workspace.json'

extends

Defines an external .moon/workspace.yml to extend and inherit settings from. Perfect for reusability and sharing configuration across repositories and projects. When defined, this setting must be an HTTPS URL or relative file system path that points to a valid YAML document!

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

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!

projectsRequired

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.

caution

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, where this name is used heavily on the command line and within the project graph for uniquely identifying the project amongst all projects. The map value (known as the project source) is a file system path to the project folder, relative from the workspace root, and must be contained within the workspace boundary.

.moon/workspace.yml
projects:
admin: 'apps/admin'
apiClients: 'packages/api-clients'
designSystem: 'packages/design-system'
web: 'apps/web'

Using globs

If manually mapping projects is too tedious or cumbersome, you may provide a list of globs to automatically locate all project folders, relative from the workspace root.

When using this approach, the project name is derived from the project folder name, and is cleaned to our supported characters . Furthermore, globbing does risk the chance of collision, and when that happens, we log a warning and skip the conflicting project from being configured in the project graph.

.moon/workspace.yml
projects:
- 'apps/*'
- 'packages/*'

Using a map and globs

For those situations where you want to use both patterns, you can! The list of globs can be defined under a globs field, while the map of projects under a sources field.

.moon/workspace.yml
projects:
globs:
- 'apps/*'
- 'packages/*'
sources:
www: 'www'

constraints

Configures constraints between projects that are enforced during project graph generation. This is also known as project boundaries.

enforceProjectTypeRelationships

Enforces allowed relationships between a project its dependencies based on the project's type setting. When a project depends on another project of an invalid type, an error will be thrown when attempting to run a task. The following relationships are enforced when this setting is enabled, which defaults to true.

  • Applications can only depend on libraries or tools.
  • Libraries can only depend on other libraries.
  • Tools can only depend on libraries.
.moon/workspace.yml
constraints:
enforceProjectTypeRelationships: false

Projects with an unconfigured or unknown type are ignored during enforcement.

tagRelationships

Enforces allowed relationships between a project and its dependencies based on the project's tags setting. This works in a similar fashion to enforceProjectTypeRelationships, but gives you far more control over what these relationships look like.

For example, let's enforce that Next.js projects using the next tag can only depend on React projects using the react tag. If a dependency does not have one of the configured required tags, in this case react, an error will occur.

.moon/workspace.yml
constraints:
tagRelationships:
next: ['react']

On the project side, we would configure moon.yml like so:

app/moon.yml
tags: ['next']
dependsOn: ['components']
packages/components/moon.yml
tags: ['react']

generator

Configures aspects of the template generator.

templates

A list of file system paths where templates can be located, relative from the workspace root. Defaults to ./templates.

.moon/workspace.yml
generator:
templates:
- './templates'
- './other/templates'

hasher

Configures aspects of the smart hashing layer.

batchSize

When hashing a list of files, we split the list into batches to help reduce memory footprint and avoid overloading the configured VCS. This setting controls how many files are in each batch and defaults to 2500.

If you're running into memory issues, or moon hanging during the file hashing process, lowering this number may help resolve the issue.

.moon/workspace.yml
hasher:
batchSize: 1000

optimization

Determines the optimization level to utilize when hashing content before running targets.

  • accuracy (default) - When hashing dependency versions, utilize the resolved value in the lockfile. This requires parsing the lockfile, which may reduce performance.
  • performance - When hashing dependency versions, utilize the value defined in the manifest. This is typically a version range or requirement.
.moon/workspace.yml
hasher:
optimization: 'performance'

walkStrategy

Defines the file system walking strategy to utilize when discovering inputs to hash.

  • glob - Walks the file system using glob patterns.
  • vcs (default) - Calls out to the VCS to extract files from its working tree.
.moon/workspace.yml
hasher:
walkStrategy: 'glob'

warnOnMissingInputs

When enabled, will log warnings to the console when attempting to hash an input that does not exist. This is useful in uncovering misconfigured tasks. Defaults to true.

.moon/workspace.yml
hasher:
warnOnMissingInputs: false

notifier

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

webhookUrl

Defines an HTTPS URL that all pipeline events will be posted to. View the webhooks guide for more information on available events.

.moon/workspace.yml
notifier:
webhookUrl: 'https://api.company.com/some/endpoint'

runner

Configures aspects of the action pipeline.

cacheLifetime

The maximum lifetime of cached artifacts before they're marked as stale and automatically removed by the action pipeline. Defaults to "7 days". This field requires an integer and a timeframe unit that can be parsed as a duration.

.moon/workspace.yml
runner:
cacheLifetime: '24 hours'

archivableTargets

Defines a list of targets, with or without scope, that will be cached and archived within the runner. Tasks that produce outputs are automatically archived, and do not need to be defined here. Defaults to an empty list.

.moon/workspace.yml
runner:
archivableTargets:
- ':test'
- 'app:typecheck'

This setting primarily exists for remote caching as it will create and persist tar archives located in .moon/cache/outputs.

inheritColorsForPipedTasks

Force colors to be inherited from the current terminal for all tasks that are ran as a child process and their output is piped to the action pipeline. Defaults to true. View more about color handling in moon.

.moon/workspace.yml
runner:
inheritColorsForPipedTasks: true

logRunningCommand

When enabled, will log the task's command, resolved arguments, and working directory when a target is ran. Defaults to false.

.moon/workspace.yml
runner:
logRunningCommand: true

telemetry

When enabled, will check for a newer moon version and send anonymous usage data to the moonrepo team. This data is used to improve the quality and reliability of the tool. Defaults to true.

.moon/workspace.yml
telemetry: false

vcs

Configures the version control system to utilize within the workspace (and repository). A VCS is required for determining touched (added, modified, etc) files, calculating file hashes, computing affected files, and much more.

defaultBranch

Defines the default branch in the repository for comparing differences against. For git, this is typically "master" (default) or "main". For svn, this should always be "trunk".

.moon/workspace.yml
vcs:
defaultBranch: 'master'

manager

Defines the VCS tool/binary that is being used for managing the repository. Accepts "git" (default) or "svn" (experimental, in development).

.moon/workspace.yml
vcs:
manager: 'git'

remoteCandidates

(Git only) Defines a list of remote candidates to query agaist to determine merge bases. Defaults to "origin" and "upstream".

.moon/workspace.yml
vcs:
remoteCandidates:
- 'origin'
- 'upstream'

versionConstraint

Defines a semantic version requirement for the currently running moon binary. This provides a mechanism for enforcing that the globally installed moon on every developers machine is using an applicable version.

.moon/workspace.yml
versionConstraint: '>=0.20.0'