.moon/workspace.yml
The .moon/workspace.yml
file configures projects and services in the workspace. This file is
required.
$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!
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, 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.
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, but can be customized with the
id
setting in moon.yml
. 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.
projects:
- 'apps/*'
- 'packages/*'
# Only shared folders with a moon configuration
- 'shared/*/moon.yml'
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.
projects:
globs:
- 'apps/*'
- 'packages/*'
sources:
www: 'www'
codeowners
v1.8.0
Configures code owners (CODEOWNERS
) integration across the entire workspace.
globalPaths
This setting defines file patterns and their owners at the workspace-level, and are applied to any matching path, at any depth, within the entire workspace. This is useful for defining global or fallback owners when a granular project-level path does not match or exist.
codeowners:
globalPaths:
'*': ['@admins']
'config/': ['@infra']
'/.github/': ['@infra']
orderBy
The order in which code owners, grouped by project, are listed in the CODEOWNERS
file. Accepts
"file-source" (default) or "project-name".
codeowners:
orderBy: 'project-name'
syncOnRun
Will automatically generate a CODEOWNERS
file by aggregating and syncing all project
owners
in the workspace when a target is run. The format
and location of the CODEOWNERS
file is based on the vcs.provider
setting. Defaults
to false
.
codeowners:
syncOnRun: true
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
and stack
settings. 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 depend on all types except other applications or automation.
- Automation can depend on all types except other automation.
- Libraries can only depend on other libraries, configuration, or scaffolding.
- Tools can only depend on libraries, configuration, or scaffolding.
- Configuration and scaffolding can only depend on other configuration and scaffolding.
When the project stack
setting is defined, it alters these rules to allow these kinds of
relationships. For example, a frontend application can depend on a backend application, but not
another frontend application.
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.
constraints:
tagRelationships:
next: ['react']
On the project side, we would configure moon.yml
like so:
tags: ['next']
dependsOn: ['components']
tags: ['react']
docker
v1.27.0
Configures Docker integration for the entire workspace.
prune
Configures aspects of the Docker pruning process when
moon docker prune
is executed.
deleteVendorDirectories
Automatically delete vendor directories (package manager dependencies, build targets, etc) while
pruning. For example, node_modules
for JavaScript, or target
for Rust. Defaults to true
.
docker:
prune:
deleteVendorDirectories: false
This process happens before toolchain dependencies are installed.
installToolchainDeps
Automatically install production dependencies for all required toolchain's of the focused projects
within the Docker build. For example, node_modules
for JavaScript. Defaults to true
.
docker:
prune:
installToolchainDeps: false
This process happens after vendor directories are deleted.
scaffold
Configures aspects of the Docker scaffolding process when
moon docker scaffold
is executed. Only applies to the
workspace skeleton.
copyToolchainFiles
Copy all toolchain specific configs, manifests, and related files in the entire repository into the
.moon/docker/workspace
skeleton. This is required for certain tools, like package managers, to
work correctly. Defaults to true
.
docker:
scaffold:
copyToolchainFiles: false
If you disable this feature, you'll most likely need to manually
COPY
all necessary files in yourDockerfile
.
include
List of globs in which to copy additional workspace-relative files into the .moon/docker/workspace
skeleton. When not defined, does nothing.
docker:
scaffold:
include:
- '**/package.json'
experiments
v1.11.0
Enable or disable experiments that alter core functionality.
extensions
v1.20.0
A mapping of extensions that can be downloaded and executed with the moon ext
command. An extension is a WASM plugin, and the location of the WASM file must be defined with the
plugin
field, which requires a
plugin locator string.
extensions:
example:
plugin: 'file://./path/to/example.wasm'
# or
plugin: 'https://example.com/path/to/example.wasm'
Additionally, extensions support custom configuration that is passed to the WASM runtime when the
plugin is instantiated. This configuration is defined by inserting additional fields under the
extension name, relative to the plugin
field. Each extension may have its own settings, so refer
to their documentation for more information.
extensions:
example:
plugin: 'file://./path/to/example.wasm'
setting1: true
setting2: 'abc'
View our official extensions guide for more information, including built-in extensions!
generator
Configures aspects of the template generator.
templates
A list of paths in which templates can be located. Supports the following types of paths, and
defaults to ./templates
.
- File system paths, relative from the workspace root.
- Git repositories and a revision, prefixed with
git://
. v1.23.0 - npm packages and a version, prefixed with
npm://
. v1.23.0
generator:
templates:
- './templates'
- 'file://./other/templates'
- 'git://github.com/moonrepo/templates#master'
- 'npm://@moonrepo/templates#1.2.3'
Learn more about this in the official code generation guide!
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.
hasher:
batchSize: 1000
ignoreMissingPatterns
v1.10.0
When hasher.warnOnMissingInputs
is enabled, moon will log a warning to the
terminal that an input is missing. This is useful for uncovering misconfigurations, but can be quite
noisy when inputs are truly optional.
To ignore warnings for missing inputs, a list of glob patterns can
be configured to filter and ignore files. Files are matched against workspace relative paths, so
prefixing patterns with **/
is suggested.
hasher:
ignoreMissingPatterns:
- '**/.eslintrc.*'
- '**/*.config.*'
ignorePatterns
v1.10.0
A list of glob patterns used to filter and ignore files during the
inputs hashing process. Files are matched against workspace relative paths, so prefixing patterns
with **/
is suggested.
hasher:
ignorePatterns:
- '**/*.png'
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.
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.
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
.
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.
notifier:
webhookUrl: 'https://api.company.com/some/endpoint'
runner
Configures aspects of task running and the action pipeline.
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.
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
.
autoCleanCache
v1.24.0
Automatically cleans cached artifacts older than cacheLifetime
from the cache
directory (.moon/cache
) after every run. This is useful for keeping the cache directory lean.
Defaults to true
.
runner:
autoCleanCache: false
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.
runner:
cacheLifetime: '24 hours'
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.
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
.
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
.
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".
vcs:
defaultBranch: 'master'
hooks
v1.9.0
Defines a mapping of hooks to a list of commands to run when that event is triggered. There are no restrictions to what commands can be run, but the binaries for each command must exist on each machine that will be running hooks.
For Git, each hook name must be a valid kebab-cased name. Learn more about Git hooks.
vcs:
hooks:
pre-commit:
- 'moon run :lint :format --affected --status=staged'
- 'another-command'
If running moon
commands directly, the moon
binary must be installed globally!
hookFormat
v1.29.0
The shell and file type in which generated hook files are formatted with. Supports the following:
native
(default) - The format native to the current operating system. Bash on Unix, and PowerShell on Windows.bash
- Forces the format to Bash for all operating systems.
vcs:
hookFormat: 'bash'
manager
Defines the VCS tool/binary that is being used for managing the repository. Accepts "git" (default). Expect more version control systems in the future!
vcs:
manager: 'git'
provider
v1.8.0
Defines the service provider that the repository is hosted on. Accepts "github" (default), "gitlab", "bitbucket", or "other".
vcs:
provider: 'github'
remoteCandidates
(Git only) Defines a list of remote candidates to query against to determine merge bases. Defaults to "origin" and "upstream".
vcs:
remoteCandidates:
- 'origin'
- 'upstream'
syncHooks
v1.9.0
Will automatically generate hook scripts to .moon/hooks
and sync the scripts to the
local VCS checkout. The hooks format and location is based on the vcs.manager
setting.
Defaults to false
.
vcs:
hooks:
# ...
syncHooks: true
When enabled, this will sync hooks for all users of the repository. For personal or small projects, this may be fine, but for larger projects, this may be undesirable and disruptive!
versionConstraint
Defines a 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.
versionConstraint: '>=0.20.0'