Skip to main content

.moon/workspace.{pkl,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'
info

Workspace configuration can also be written in Pkl instead of YAML.

extends​

Defines one or many external .moon/workspace.yml's 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, 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.

.moon/workspace.yml
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.

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

codeownersv1.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.

.moon/workspace.yml
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".

.moon/workspace.yml
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.

.moon/workspace.yml
codeowners:
  syncOnRun: true

constraints​

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

enforceLayerRelationships​

This was previously known as enforceProjectTypeRelationships and was renamed to enforceLayerRelationships in v1.39.

Enforces allowed relationships between a project and its dependencies based on the project's layer and stack settings. When a project depends on another project of an invalid layer, a layering violation error will be thrown when attempting to run a task.

Layers are allowed to depend on lower layers in the same stack, but not higher layers. Additionally, layers may depend on itself, excluding automations and applications. The following layers are stacked as such:

LayerDescription
automationAn automated testing suite, like E2E, integration, or visual tests.
applicationAn application of any kind.
toolAn internal tool, CLI, one-off script, etc.
libraryA self-contained, shareable, and publishable set of code.
scaffoldingTemplates or generators for scaffolding.
configurationConfiguration files or infrastructure.
unknownWhen not configured.

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.

.moon/workspace.yml
constraints:
  enforceLayerRelationships: false

Projects with an unconfigured or unknown layer 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 enforceLayerRelationships, 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']

dockerv1.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.

.moon/workspace.yml
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.

.moon/workspace.yml
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.

.moon/workspace.yml
docker:
  scaffold:
    copyToolchainFiles: false

If you disable this feature, you'll most likely need to manually COPY all necessary files in your Dockerfile.

include​

List of globs in which to copy additional workspace-relative files into the .moon/docker/workspace skeleton. When not defined, does nothing.

.moon/workspace.yml
docker:
  scaffold:
    include:
      - '**/package.json'

experimentsv1.11.0​

Enable or disable experiments that alter core functionality.

warning

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

fasterGlobWalkv1.34.0​

Utilizes a new concurrent glob walking implementation that is on average, 1.5-2x faster than the current implementation. Additionally, common globs are now cached for the duration of the process. Defaults to true.

.moon/workspace.yml
experiments:
  fasterGlobWalk: true

gitV2v1.34.0​

Utilizes a Git implementation, that has better support for submodules, subtrees, and workspaces. Additionally, processes are parallized when applicable. Defaults to true.

.moon/workspace.yml
experiments:
  gitV2: true

extensionsv1.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.

.moon/workspace.yml
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.

.moon/workspace.yml
extensions:
  example:
    plugin: 'file://./path/to/example.wasm'
    setting1: true
    setting2: 'abc'
info

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
.moon/workspace.yml
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​

This setting is deprecated!

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

ignoreMissingPatternsv1.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.

.moon/workspace.yml
hasher:
  ignoreMissingPatterns:
    - '**/.eslintrc.*'
    - '**/*.config.*'

ignorePatternsv1.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.

.moon/workspace.yml
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.
.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.

terminalNotificationsv1.38.0​

When defined, will display OS notifications for action pipeline events when running commands from a terminal. Supports the following values:

  • always - Display on pipeline success and failure.
  • failure - Display on pipeline failure only.
  • success - Display on pipeline success only.
  • task-failure - Display for each task failure.
.moon/workspace.yml
notifier:
  terminalNotifications: 'always'

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'

acknowledge​

When enabled, webhook notfier will wait for request result and validates the return code for 2xx. Defaults to false.

warning

Activating this setting will slow down your pipeline, because every webhook request will be evaluated!

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

pipeline​

Configures aspects of task running and the action pipeline.

archivableTargets​

info

This setting is deprecated and purely existed for moonbase, our old cloud remote caching service. Going forward, if using Bazel Remote Caching, all tasks are automatically cached (archived).

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

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

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

autoCleanCachev1.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.

.moon/workspace.yml
pipeline:
  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.

.moon/workspace.yml
pipeline:
  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.

.moon/workspace.yml
pipeline:
  inheritColorsForPipedTasks: true

installDependenciesv1.34.0​

When enabled, runs the InstallWorkspaceDeps and InstallProjectDeps actions within the pipeline before running an applicable task. Installation is determined based on changed manifests and lockfiles. Defaults to true.

.moon/workspace.yml
pipeline:
  installDependencies: false

Instead of a boolean, a list of toolchain IDs can be provided to only allow those toolchains to install dependencies.

.moon/workspace.yml
pipeline:
  installDependencies: ['node']

killProcessThresholdv1.32.1​

Threshold in milliseconds in which to force kill running child processes after the pipeline receives an external signal (like SIGINT or SIGTERM). A value of 0 will not kill the process and let them run to completion. Defaults to 2000 (2 seconds).

.moon/workspace.yml
pipeline:
  killProcessThreshold: 5000

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
pipeline:
  logRunningCommand: true

syncProjectsv1.34.0​

When enabled, runs the SyncProject action within the pipeline before running an applicable task. Defaults to true.

.moon/workspace.yml
pipeline:
  syncProjects: false

Instead of a boolean, a list of project IDs can be provided to only sync those projects.

.moon/workspace.yml
pipeline:
  syncProjects: ['app']

The moon sync projects command can be executed to manually sync projects.

syncWorkspacev1.34.0​

When enabled, runs the SyncWorkspace action within the pipeline before all other actions. This syncing includes operations such as codeowners, VCS hooks, and more. Defaults to true.

.moon/workspace.yml
pipeline:
  syncWorkspace: false

The moon sync ... sub-commands can be executed to manually sync features.

unstable_remotev1.30.0​

Configures a remote service, primarily for cloud-based caching of artifacts. Learn more about this in the remote caching guide.

apiv1.32.0​

The API format of the remote server. This format dictates which type of client moon uses for communicating with. Supports the following:

.moon/workspace.yml
unstable_remote:
  api: 'grpc'

authv1.32.0​

Configures authorization and authentication level features of our remote clients.

headersv1.32.0​

A mapping of HTTP headers to include in all requests to the remote server. These headers are applied to all API formats and protocols, not just HTTP.

.moon/workspace.yml
unstable_remote:
  auth:
    headers:
      'X-Custom-Header': 'value'

tokenv1.32.0​

The name of an environment variable in which to extract a token for Bearer HTTP authorization. An Authorization HTTP header will be included in all requests to the remote server.

If the token does not exist, or is not enabled, remote caching will be disabled.

.moon/workspace.yml
unstable_remote:
  auth:
    token: 'ENV_VAR_NAME'

cache​

Configures aspects of the caching layer, primarily the action cache (AC) and content addressable cache (CAS).

compressionv1.31.0​

The compression format to use when uploading/downloading blobs. Supports none and zstd, and defaults to no compression (identity format in RE API).

.moon/workspace.yml
unstable_remote:
  cache:
    compression: 'zstd'
info

Compression is only applied to gRPC based APIs, not HTTP.

instanceName​

A unique identifier used to distinguish between the various instances on the host. This allows the same remote service to serve and partition multiple moon repositories. Defaults to moon-outputs.

.moon/workspace.yml
unstable_remote:
  cache:
    instanceName: 'custom-dir-name'

We suggest changing the instance name to the name of your repository!

verifyIntegrityv1.36.0​

When downloading blobs, verify the digests/hashes in the response match the associated blob contents. This will reduce performance but ensure partial or corrupted blobs won't cause failures. Defaults to false.

.moon/workspace.yml
unstable_remote:
  cache:
    verifyIntegrity: true

host​

The host URL to communicate with when uploading and downloading artifacts. Supports both grpc(s):// and http(s):// protocols. This field is required!

.moon/workspace.yml
unstable_remote:
  host: 'grpcs://your-host.com:9092'

mtls​

Connect to the host using server and client authentication with mTLS. This takes precedence over normal TLS.

.moon/workspace.yml
unstable_remote:
  # ...
  mtls:
    caCert: 'certs/ca.pem'
    clientCert: 'certs/client.pem'
    clientKey: 'certs/client.key'
    domain: 'your-host.com'

assumeHttp2​

If true, assume that the host supports HTTP/2, even if it doesn't provide protocol negotiation via ALPN.

caCert​

A file path, relative from the workspace root, to the certificate authority PEM encoded X509 certificate (typically ca.pem).

clientCert​

A file path, relative from the workspace root, to the client's PEM encoded X509 certificate (typically client.pem).

clientKey​

A file path, relative from the workspace root, to the client's PEM encoded X509 private key (typically client.key).

domain​

The domain name in which to verify the TLS certificate.

tls​

Connect to the host using server-only authentication with TLS.

.moon/workspace.yml
unstable_remote:
  # ...
  tls:
    cert: 'certs/ca.pem'
    domain: 'your-host.com'

assumeHttp2​

If true, assume that the host supports HTTP/2, even if it doesn't provide protocol negotiation via ALPN.

cert​

A file path, relative from the workspace root, to the certificate authority PEM encoded X509 certificate (typically ca.pem).

domain​

The domain name in which to verify the TLS certificate.

runner​

This setting was renamed to pipeline but still works for backwards compatibility.

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".

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

hooksv1.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.

.moon/workspace.yml
vcs:
  hooks:
    pre-commit:
      - 'moon run :lint :format --affected --status=staged --no-bail'
      - 'another-command'
info

If running moon commands directly, the moon binary must be installed globally!

hookFormatv1.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.
.moon/workspace.yml
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!

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

providerv1.8.0​

Defines the service provider that the repository is hosted on. Accepts "github" (default), "gitlab", "bitbucket", or "other".

.moon/workspace.yml
vcs:
  provider: 'github'

remoteCandidates​

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

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

syncHooksv1.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.

.moon/workspace.yml
vcs:
  hooks:
    # ...
  syncHooks: true
caution

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.

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