---
title: Configuration overview
description: Configure Melos using the `melos.yaml` file.
---

# Configuration Overview

Every project requires a `melos.yaml` project in the root. The below outlines
all the configurable fields and their purpose.

## `name`

> required

The name of this project, using for display purposes within IO environments and IDEs.

```yaml
name: My Awesome Project
```

## `repository`

The URL of where the git repository, which contains this project, is centrally hosted.

Supported hosts:

- GitHub
- GitLab (https://gitlab.com)

```yaml
repository: https://github.com/invertase/melos
```

## `packages`

> required

A list of local packages Melos will use to execute commands against. The list can be
of specific paths or a [glob](https://docs.python.org/3/library/glob.html) pattern expansion format.

```yaml
packages:
  # e.g. all packages inside the /packages directory
  - packages/**
  # e.g. including the workspace root as a package
  - "*"
```

> You can also reduce the scope of packages on a per-command basis via the [`--scope` filter](/filters#scope) flag.

## `ignore`

> required

A list of local packages Melos will ignore when executing commands in the workspace. The list can be
of specific paths or a [glob](https://docs.python.org/3/library/glob.html) pattern expansion format.

```yaml
ignore:
  # e.g. ignore example apps
  - "packages/**/*example"
```

> You can also expand the scope of ignored packages on a per-command basis via the [`--scope` filter](/filters#scope) flag.

## `scripts`

> optional

Define custom scripts that can be executed in the workspace via the [`melos run`](/commands/run) command.

Learn more about defining scripts [here](/configuration/scripts).

## `command`

Configuration relating to specific Melos commands such as versioning.

### `command/version/message`

A template for the commit message, that is generated by `melos version`.

Templates must use mustache syntax and have the following variables available:

- `new_package_versions`: A list of the versioned packages and their new versions.

The default is:

```
chore(release): publish packages

{new_package_versions}
```

```yaml
command:
  version:
    message: |
      chore: cut package releases 🎉

      {new_package_versions}
```

### `command/version/branch`

If specified, prevents `melos version` from being used inside branches other than the one specified.

```yaml
command:
  version:
    branch: main
```

### `command/version/linkToCommits`

Whether to add links to commits in the CHANGELOG.md, that is generated by `melos version`.

Enabling this option, requires [`repository`](#repository) to be specified.

```yaml
command:
  version:
    linkToCommits: true
```

### `command/version/workspaceChangelog`

Whether to additionally build a CHANGELOG.md at the root of the workspace when running `melos version`.

```yaml
command:
  version:
    workspaceChangelog: true
```

### `command/version/updateGitTagRefs`

When running `melos version` this option will allow updates to `pubspec.yaml` for locally (git) hosted packages part of this melos workspace, see [here](/guides/automated-releases#git-hosted-packages)

```yaml
command:
  version:
    updateGitTagRefs: true
```