---
title: .moon/workspace
toc_max_heading_level: 6
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import HeadingApiLink from '@site/src/components/Docs/HeadingApiLink';
import RequiredLabel from '@site/src/components/Docs/RequiredLabel';
import VersionLabel from '@site/src/components/Docs/VersionLabel';

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

## `extends`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#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. When defined, this setting
must be an HTTPS URL _or_ relative file system path that points to a valid YAML document!

```yaml title=".moon/workspace.yml" {1}
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_!

:::

## `projects`<RequiredLabel />

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#projects" />

Defines the location of all [projects](../concepts/project) 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](../concepts/project#names) 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.

```yaml title=".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](../concepts/file-pattern#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](../concepts/project#names), but can be customized with the
[`id`](./project#id) setting in [`moon.*`](./project). 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.

```yaml title=".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.

```yaml title=".moon/workspace.yml"
projects:
  globs:
    - 'apps/*'
    - 'packages/*'
  sources:
    www: 'www'
```

Additionally, you can customize the format of project IDs for glob discovered projects. By default
it inherits the fodler name, but this has a high chance of collision. Instead you can configure
`globFormat` to use a different format, for example, using the full workspace relative path as the
project ID.

```yaml title=".moon/workspace.yml"
projects:
  globFormat: 'source-path'
  globs:
    - 'packages/**/moon.yml'
```

## `defaultProject`<VersionLabel version="2.0.0" />

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#defaultProject" />

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

```yaml title=".moon/workspace.yml" {2}
defaultProject: 'web'
```

## `cache`<VersionLabel version="2.3.0" />

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#cache" />

Configures aspects of the caching engine and layer. These settings primarily tune the
content-addressable storage (CAS) cache and the native file hasher.

### `cas`

<HeadingApiLink to="/api/types/interface/CacheConfig#cas" />

Configures aspects of the content-addressable storage (CAS) cache.

#### `verifyIntegrity`

<HeadingApiLink to="/api/types/interface/CacheCasConfig#verifyIntegrity" />

Re-verifies the hash of cached content on every read. When enabled, reads are slower but on-disk
corruption is detected. Defaults to `false`.

```yaml title=".moon/workspace.yml" {2,3}
cache:
  cas:
    verifyIntegrity: true
```

## `codeowners`<VersionLabel version="1.8.0" />

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#codeowners" />

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

### `globalPaths`

<HeadingApiLink to="/api/types/interface/CodeownersConfig#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](./project#paths) does not match or exist.

```yaml title=".moon/workspace.yml" {2-5}
codeowners:
  globalPaths:
    '*': ['@admins']
    'config/': ['@infra']
    '/.github/': ['@infra']
```

### `orderBy`

<HeadingApiLink to="/api/types/interface/CodeownersConfig#orderBy" />

The order in which code owners, grouped by project, are listed in the `CODEOWNERS` file. Accepts
"file-source" (default) or "project-id".

```yaml title=".moon/workspace.yml" {2}
codeowners:
  orderBy: 'project-id'
```

### `sync`

<HeadingApiLink to="/api/types/interface/CodeownersConfig#sync" />

Will automatically generate a `CODEOWNERS` file by aggregating and syncing all project
[`owners`](./project#owners) in the workspace when a [target is run](../concepts/target). The format
and location of the `CODEOWNERS` file is based on the [`vcs.provider`](#provider) setting. Defaults
to `false`.

```yaml title=".moon/workspace.yml" {2}
codeowners:
  sync: true
```

## `constraints`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#constraints" />

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

### `enforceLayerRelationships`

<HeadingApiLink to="/api/types/interface/ConstraintsConfig#enforceLayerRelationships" />

Enforces allowed relationships between a project and its dependencies based on the project's
[`layer`](./project#layer) and [`stack`](./project#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:

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

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.

```yaml title=".moon/workspace.yml" {2}
constraints:
  enforceLayerRelationships: false
```

> Projects with an unconfigured or unknown layer are ignored during enforcement.

### `tagRelationships`

<HeadingApiLink to="/api/types/interface/ConstraintsConfig#tagRelationships" />

Enforces allowed relationships between a project and its dependencies based on the project's
[`tags`](./project#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.

```yaml title=".moon/workspace.yml" {2,3}
constraints:
  tagRelationships:
    next: ['react']
```

On the project side, we would configure [`moon.*`](./project#tags) like so:

```yaml title="app/moon.yml"
tags: ['next']
dependsOn: ['components']
```

```yaml title="packages/components/moon.yml"
tags: ['react']
```

## `docker`<VersionLabel version="1.27.0" />

<HeadingApiLink to="/api/types/interface/ProjectConfig#docker" />

Configures Docker integration for the entire workspace.

### `prune`

<HeadingApiLink to="/api/types/interface/DockerConfig#prune" />

Configures aspects of the Docker pruning process when
[`moon docker prune`](../commands/docker/prune) is executed.

#### `deleteVendorDirectories`

<HeadingApiLink to="/api/types/interface/DockerPruneConfig#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`.

```yaml title=".moon/workspace.yml" {3}
docker:
  prune:
    deleteVendorDirectories: false
```

> This process happens before toolchain dependencies are installed.

#### `installToolchainDependencies`

<HeadingApiLink to="/api/types/interface/DockerPruneConfig#installToolchainDependencies" />

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

```yaml title=".moon/workspace.yml" {3}
docker:
  prune:
    installToolchainDependencies: false
```

> This process happens after vendor directories are deleted.

### `scaffold`

<HeadingApiLink to="/api/types/interface/DockerConfig#scaffold" />

Configures aspects of the Docker scaffolding process when
[`moon docker scaffold`](../commands/docker/scaffold) is executed. Only applies to the
[workspace skeleton](../commands/docker/scaffold#workspace).

#### `configsPhaseGlobs`

<HeadingApiLink to="/api/types/interface/DockerScaffoldConfig#include" />

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

```yaml title=".moon/workspace.yml" {3,4}
docker:
  scaffold:
    configsPhaseGlobs:
      - '**/package.json'
```

## `experiments`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#experiments" />

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!

:::

### `asyncAffectedTracking`<VersionLabel version="2.2.0" />

<HeadingApiLink to="/api/types/interface/ExperimentsConfig#asyncAffectedTracking" />

Utilizes a new asynchronous implementation of the affected tracker that can improve performance by
100-150%. Defaults to `false`.

```yaml title=".moon/workspace.yml" {2}
experiments:
  asyncAffectedTracking: true
```

Can also be enabled with the `MOON_EXPERIMENT_ASYNC_AFFECTED_TRACKING` environment variable.

### `asyncGraphBuilding`<VersionLabel version="2.2.0" />

<HeadingApiLink to="/api/types/interface/ExperimentsConfig#asyncGraphBuilding" />

Utilizes an asynchronous graph building implementation that can improve performance by 100-170% in
large workspaces. Defaults to `false`.

```yaml title=".moon/workspace.yml" {2}
experiments:
  asyncGraphBuilding: true
```

Can also be enabled with the `MOON_EXPERIMENT_ASYNC_GRAPH_BUILDING` environment variable.

### `casOutputsCache`<VersionLabel version="2.3.0" />

<HeadingApiLink to="/api/types/interface/ExperimentsConfig#casOutputsCache" />

Stores task outputs in a local content-addressable storage (CAS) cache, instead of the legacy
tarball-based local cache. This shares the same content-addressed format used by the remote cache,
enabling deduplicated storage across tasks and faster hydration. Defaults to `false`.

```yaml title=".moon/workspace.yml" {2}
experiments:
  casOutputsCache: true
```

Can also be enabled with the `MOON_EXPERIMENT_CAS_OUTPUTS_CACHE` environment variable.

> The CAS layer can be tuned through the top-level [`cache`](#cache) setting.

### `nativeFileHashing`<VersionLabel version="2.3.0" />

<HeadingApiLink to="/api/types/interface/ExperimentsConfig#nativeFileHashing" />

Replaces the VCS-based file hashing mechanism with a custom native implementation that runs within
moon's task pool. In our benchmarks this improves performance by 10-50% depending on workspace size
and file count. Defaults to `false`.

```yaml title=".moon/workspace.yml" {2}
experiments:
  nativeFileHashing: true
```

Can also be enabled with the `MOON_EXPERIMENT_NATIVE_FILE_HASHING` environment variable.

> The hasher can be tuned through the top-level [`cache`](#cache) setting.

## `generator`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#generator" />

Configures aspects of the template generator.

### `templates`

<HeadingApiLink to="/api/types/interface/GeneratorConfig#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://`. <VersionLabel inline version="1.23.0" />
- npm packages and a version, prefixed with `npm://`. <VersionLabel inline version="1.23.0" />

```yaml title=".moon/workspace.yml" {2-4}
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](../guides/codegen#configuring-template-locations)!

## `hasher`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#hasher" />

Configures aspects of the smart hashing layer.

### `ignoreMissingPatterns`<VersionLabel version="1.10.0" />

<HeadingApiLink to="/api/types/interface/HasherConfig#ignoreMissingPatterns" />

When [`hasher.warnOnMissingInputs`](#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](../concepts/file-pattern#globs) can
be configured to filter and ignore files. Files are matched against workspace relative paths, so
prefixing patterns with `**/` is suggested.

Defaults to `**/.env` and `**/.env.*` but will be overwritten when configured.

```yaml title=".moon/workspace.yml" {2-4}
hasher:
  ignoreMissingPatterns:
    - '**/.eslintrc.*'
    - '**/*.config.*'
```

### `ignorePatterns`<VersionLabel version="1.10.0" />

<HeadingApiLink to="/api/types/interface/HasherConfig#ignorePatterns" />

A list of [glob patterns](../concepts/file-pattern#globs) used to filter and ignore files during the
inputs hashing process. Files are matched against workspace relative paths, so prefixing patterns
with `**/` is suggested.

```yaml title=".moon/workspace.yml" {2,3}
hasher:
  ignorePatterns:
    - '**/*.png'
```

### `optimization`

<HeadingApiLink to="/api/types/interface/HasherConfig#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.

```yaml title=".moon/workspace.yml" {2}
hasher:
  optimization: 'performance'
```

### `walkStrategy`

<HeadingApiLink to="/api/types/interface/HasherConfig#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](#vcs) to extract files from its working tree.

```yaml title=".moon/workspace.yml" {2}
hasher:
  walkStrategy: 'glob'
```

### `warnOnMissingInputs`

<HeadingApiLink to="/api/types/interface/HasherConfig#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`.

```yaml title=".moon/workspace.yml" {2}
hasher:
  warnOnMissingInputs: false
```

## `notifier`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#notifier" />

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

### `terminalNotifications`<VersionLabel version="1.38.0" />

<HeadingApiLink to="/api/types/interface/NotifierConfig#terminalNotifications" />

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.

```yaml title=".moon/workspace.yml" {2}
notifier:
  terminalNotifications: 'always'
```

### `webhookUrl`

<HeadingApiLink to="/api/types/interface/NotifierConfig#webhookUrl" />

Defines an HTTPS URL that all pipeline events will be posted to. View the
[webhooks guide for more information](../guides/webhooks) on available events.

```yaml title=".moon/workspace.yml" {2}
notifier:
  webhookUrl: 'https://api.company.com/some/endpoint'
```

### `webhookAcknowledge`

<HeadingApiLink to="/api/types/interface/NotifierConfig#webhookAcknowledge" />

When enabled, webhook notifier 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!

:::

```yaml title=".moon/workspace.yml" {2}
notifier:
  webhookUrl: 'https://api.company.com/some/endpoint'
  webhookAcknowledge: true
```

## `pipeline`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#pipeline" />

Configures aspects of task running and the action pipeline.

### `autoCleanCache`<VersionLabel version="1.24.0" />

<HeadingApiLink to="/api/types/interface/PipelineConfig#autoCleanCache" />

Automatically cleans cached artifacts older than [`cacheLifetime`](#cachelifetime) from the cache
directory (`.moon/cache`) after every run. This is useful for keeping the cache directory lean.
Defaults to `true`.

```yaml title=".moon/workspace.yml" {2}
pipeline:
  autoCleanCache: false
```

### `cacheLifetime`

<HeadingApiLink to="/api/types/interface/PipelineConfig#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](https://docs.rs/humantime/2.1.0/humantime/fn.parse_duration.html).

```yaml title=".moon/workspace.yml" {2}
pipeline:
  cacheLifetime: '24 hours'
```

### `inheritColorsForPipedTasks`

<HeadingApiLink to="/api/types/interface/PipelineConfig#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](../commands/overview#colors).

```yaml title=".moon/workspace.yml" {2}
pipeline:
  inheritColorsForPipedTasks: true
```

### `installDependencies`<VersionLabel version="1.34.0" />

<HeadingApiLink to="/api/types/interface/PipelineConfig#installDependencies" />

When enabled, runs the
[`InstallWorkspaceDeps` and `InstallProjectDeps` actions](../how-it-works/action-graph#install-dependencies)
within the pipeline before running an applicable task. Installation is determined based on changed
manifests and lockfiles. Defaults to `true`.

```yaml title=".moon/workspace.yml" {2}
pipeline:
  installDependencies: false
```

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

```yaml title=".moon/workspace.yml" {2}
pipeline:
  installDependencies: ['node']
```

### `killProcessThreshold`<VersionLabel version="1.32.1" />

<HeadingApiLink to="/api/types/interface/PipelineConfig#killProcessThreshold" />

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

```yaml title=".moon/workspace.yml" {2}
pipeline:
  killProcessThreshold: 5000
```

### `logRunningCommand`

<HeadingApiLink to="/api/types/interface/PipelineConfig#logRunningCommand" />

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

```yaml title=".moon/workspace.yml" {2}
pipeline:
  logRunningCommand: true
```

### `syncProjects`<VersionLabel version="1.34.0" />

<HeadingApiLink to="/api/types/interface/PipelineConfig#syncProjects" />

When enabled, runs the [`SyncProject` action](../how-it-works/action-graph#sync-project) within the
pipeline before running an applicable task. Defaults to `true`.

```yaml title=".moon/workspace.yml" {2}
pipeline:
  syncProjects: false
```

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

```yaml title=".moon/workspace.yml" {2}
pipeline:
  syncProjects: ['app']
```

> The [`moon sync projects`](../commands/sync/projects) command can be executed to manually sync
> projects.

### `syncWorkspace`<VersionLabel version="1.34.0" />

<HeadingApiLink to="/api/types/interface/PipelineConfig#syncWorkspace" />

When enabled, runs the [`SyncWorkspace` action](../how-it-works/action-graph#sync-workspace) within
the pipeline before all other actions. This syncing includes operations such as codeowners, VCS
hooks, and more. Defaults to `true`.

```yaml title=".moon/workspace.yml" {2}
pipeline:
  syncWorkspace: false
```

> The [`moon sync ...`](../commands/sync) sub-commands can be executed to manually sync features.

## `remote`<VersionLabel version="1.30.0" />

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#remote" />

Configures a remote service, primarily for cloud-based caching of artifacts. Learn more about this
in the [remote caching](../guides/remote-cache) guide.

### `api`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/RemoteConfig#api" />

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

- `grpc` (default) - Uses the gRPC API: https://github.com/bazelbuild/remote-apis
- `http` - Uses the HTTP API: https://bazel.build/remote/caching#http-caching

```yaml title=".moon/workspace.yml" {2}
remote:
  api: 'grpc'
```

### `auth`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/RemoteConfig#auth" />

Configures authorization and authentication level features of our remote clients.

#### `headers`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/RemoteAuthConfig#headers" />

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

```yaml title=".moon/workspace.yml" {2-4}
remote:
  auth:
    headers:
      'X-Custom-Header': 'value'
```

#### `token`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/RemoteAuthConfig#token" />

The name of an environment variable in which to extract a token for
[Bearer HTTP authorization](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/).
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.

```yaml title=".moon/workspace.yml" {2-4}
remote:
  auth:
    token: 'ENV_VAR_NAME'
```

### `cache`

<HeadingApiLink to="/api/types/interface/RemoteConfig#cache" />

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

#### `compression`<VersionLabel version="1.31.0" />

<HeadingApiLink to="/api/types/interface/RemoteCacheConfig#compression" />

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

```yaml title=".moon/workspace.yml" {3}
remote:
  cache:
    compression: 'zstd'
```

:::info

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

:::

#### `instanceName`

<HeadingApiLink to="/api/types/interface/RemoteCacheConfig#instanceName" />

A
[unique identifier](https://github.com/bazelbuild/remote-apis/blob/main/build/bazel/remote/execution/v2/remote_execution.proto#L223)
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`.

```yaml title=".moon/workspace.yml" {3}
remote:
  cache:
    instanceName: 'custom-dir-name'
```

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

#### `localReadOnly`<VersionLabel version="1.40.0" />

<HeadingApiLink to="/api/types/interface/RemoteCacheConfig#localReadOnly" />

When enabled and developing locally, existing remote blobs will only be downloaded, but new local
blobs will _not_ be uploaded. Blobs will only be uploaded in CI environments.

```yaml title=".moon/workspace.yml" {3}
remote:
  cache:
    localReadOnly: true
```

#### `verifyIntegrity`<VersionLabel version="1.36.0" />

<HeadingApiLink to="/api/types/interface/RemoteCacheConfig#verifyIntegrity" />

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

```yaml title=".moon/workspace.yml" {3}
remote:
  cache:
    verifyIntegrity: true
```

### `host`

<HeadingApiLink to="/api/types/interface/RemoteConfig#host" />

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

```yaml title=".moon/workspace.yml" {2}
remote:
  host: 'grpcs://your-host.com:9092'
```

### `mtls`

<HeadingApiLink to="/api/types/interface/RemoteConfig#mtls" />

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

```yaml title=".moon/workspace.yml" {3-7}
remote:
  # ...
  mtls:
    caCert: 'certs/ca.pem'
    clientCert: 'certs/client.pem'
    clientKey: 'certs/client.key'
    domain: 'your-host.com'
```

#### `assumeHttp2`

<HeadingApiLink to="/api/types/interface/RemoteMtlsConfig#assumeHttp2" />

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

#### `caCert`

<HeadingApiLink to="/api/types/interface/RemoteMtlsConfig#caCert" />

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

#### `clientCert`

<HeadingApiLink to="/api/types/interface/RemoteMtlsConfig#clientCert" />

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

#### `clientKey`

<HeadingApiLink to="/api/types/interface/RemoteMtlsConfig#clientKey" />

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

#### `domain`

<HeadingApiLink to="/api/types/interface/RemoteMtlsConfig#domain" />

The domain name in which to verify the TLS certificate.

### `tls`

<HeadingApiLink to="/api/types/interface/RemoteConfig#tls" />

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

```yaml title=".moon/workspace.yml" {3-5}
remote:
  # ...
  tls:
    cert: 'certs/ca.pem'
    domain: 'your-host.com'
```

#### `assumeHttp2`

<HeadingApiLink to="/api/types/interface/RemoteTlsConfig#assumeHttp2" />

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

#### `cert`

<HeadingApiLink to="/api/types/interface/RemoteTlsConfig#cert" />

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

#### `domain`

<HeadingApiLink to="/api/types/interface/RemoteTlsConfig#domain" />

The domain name in which to verify the TLS certificate.

## `telemetry`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#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`.

```yaml title=".moon/workspace.yml" {1}
telemetry: false
```

## `vcs`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#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`

<HeadingApiLink to="/api/types/interface/VcsConfig#defaultBranch" />

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

```yaml title=".moon/workspace.yml" {2}
vcs:
  defaultBranch: 'master'
```

### `hooks`<VersionLabel version="1.9.0" />

<HeadingApiLink to="/api/types/interface/VcsConfig#hooks" />

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](https://git-scm.com/docs/githooks#_hooks) must be a valid kebab-cased
name. [Learn more about Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).

```yaml title=".moon/workspace.yml" {2-5}
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!

:::

### `hookFormat`<VersionLabel version="1.29.0" />

<HeadingApiLink to="/api/types/interface/VcsConfig#hookFormat" />

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.

```yaml title=".moon/workspace.yml" {2}
vcs:
  hookFormat: 'bash'
```

### `client`

<HeadingApiLink to="/api/types/interface/VcsConfig#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!

```yaml title=".moon/workspace.yml" {2}
vcs:
  client: 'git'
```

### `provider`<VersionLabel version="1.8.0" />

<HeadingApiLink to="/api/types/interface/VcsConfig#provider" />

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

```yaml title=".moon/workspace.yml" {2}
vcs:
  provider: 'github'
```

### `remoteCandidates`

<HeadingApiLink to="/api/types/interface/VcsConfig#remoteCandidates" />

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

```yaml title=".moon/workspace.yml" {2-4}
vcs:
  remoteCandidates:
    - 'origin'
    - 'upstream'
```

### `sync`<VersionLabel version="1.9.0" />

<HeadingApiLink to="/api/types/interface/VcsConfig#sync" />

Will automatically generate [hook scripts](#hooks) to `.moon/hooks` and sync the scripts to the
local VCS checkout. The hooks format and location is based on the [`vcs.client`](#client) setting.
Defaults to `false`.

```yaml title=".moon/workspace.yml" {4}
vcs:
  hooks:
    # ...
  sync: 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`

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#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.

```yaml title=".moon/workspace.yml" {1}
versionConstraint: '>=0.20.0'
```
