Skip to main content
The moon.* configuration file is not required but can be used to define additional metadata for a project, override inherited tasks, and more at the project-level.

​
File Location

  • Path: moon.yml or moon.json (in project root)
  • Format: YAML or JSON
  • Required: No

​
Project Dependencies

​
dependsOn

Explicitly defines other projects that this project depends on, primarily when generating the project and task graphs.
moon.yml
dependsOn:
  - 'apiClients'
  - 'designSystem'
You can also specify a scope:
moon.yml
dependsOn:
  - id: 'apiClients'
    scope: 'production'
  - id: 'designSystem'
    scope: 'peer'
Available scopes: production (default), development, build, peer

​
Metadata

​
id

Overrides the name (identifier) of the project.
moon.yml
id: 'custom-id'
All references to the project must use the new identifier, including project and task dependencies.

​
language

The primary programming language the project is written in. This setting is required for task inheritance, editor extensions, and more. Supported values:
  • bash - Bash based project (Unix only)
  • batch - Batch/PowerShell based project (Windows only)
  • go - Go based project
  • javascript - JavaScript based project
  • php - PHP based project
  • python - Python based project
  • ruby - Ruby based project
  • rust - Rust based project
  • typescript - TypeScript based project
  • unknown (default)
  • Custom language (converted to kebab-case)
moon.yml
language: 'javascript'

# Custom
language: 'kotlin'

​
owners

Defines ownership of source code within the current project, by mapping file system paths to owners.
Define ownership of source code. Supports two formats:Format 1: List (requires defaultOwner)
moon.yml
owners:
  defaultOwner: '@frontend'
  paths:
    - '**/*.ts'
    - '**/*.tsx'
    - '*.config.js'
Format 2: Map (multiple owners per path)
moon.yml
owners:
  defaultOwner: '@frontend'
  paths:
    '**/*.rs': ['@backend']
    '**/*.js': []
    '*.config.js': ['@frontend', '@frontend-infra']
Define custom groups for Bitbucket Code Owners app.
moon.yml
owners:
  customGroups:
    '@@@backend': ['@"user name"', '@@team']
Marks the project’s code owners section as optional. Defaults to false.
moon.yml
owners:
  optional: true
Requires a specific number of approvals. Defaults to 1.
moon.yml
owners:
  requiredApprovals: 2

​
layer

The layer within a stack. Supported values:
  • application - An application of any kind
  • automation - An automated testing suite
  • configuration - Configuration files or infrastructure
  • library - A self-contained, shareable, and publishable set of code
  • scaffolding - Templates or generators for scaffolding
  • tool - An internal tool, CLI, one-off script, etc.
  • unknown (default)
moon.yml
layer: 'application'

​
stack

The technology stack this project belongs to. Supported values:
  • backend - Server-side APIs, etc.
  • data - Data sources, database layers, etc.
  • frontend - Client-side user interfaces, etc.
  • infrastructure - Cloud/server infrastructure, Docker, etc.
  • systems - Low-level systems programming
  • unknown (default)
moon.yml
stack: 'frontend'

​
tags

Tags for categorizing projects. Used for querying, enforcing boundaries, task inheritance, and more.
moon.yml
tags:
  - 'react'
  - 'prisma'

​
project

Defines metadata about the project itself.
moon.yml
project:
  title: 'moon'
  description: 'A monorepo management tool.'
  channel: '#moon'
  owner: 'infra.platform'
  maintainers: ['miles.johnson']
Available fields:
  • title (required) - Human readable name
  • description (required) - Description of what the project does
  • channel - Slack, Discord, Teams channel name
  • owner - Team or organization that owns the project
  • maintainers - List of people who maintain the project
  • Custom fields (any valid JSON value)

​
Environment Variables

​
env

Map of strings passed as environment variables to all tasks within the current project.
moon.yml
env:
  NODE_ENV: 'production'

​
File Groups

​
fileGroups

Defines file groups to be used by local tasks.
moon.yml
fileGroups:
  configs:
    - '*.config.{js,cjs,mjs}'
    - '*.json'
  sources:
    - 'src/**/*'
    - 'types/**/*'
  tests:
    - 'tests/**/*'
    - '**/__tests__/**/*'
  assets:
    - 'assets/**/*'
    - 'images/**/*'
    - 'static/**/*'
    - '**/*.{scss,css}'
Reference them in tasks using token functions:
moon.yml
tasks:
  build:
    command: 'vite build'
    inputs:
      - '@group(configs)'
      - '@group(sources)'

​
Tasks

​
tasks

Tasks are actions that are ran within the context of a project.
moon.yml
tasks:
  format:
    command: 'prettier --check .'
  lint:
    command: 'eslint .'
  test:
    command: 'jest'
  typecheck:
    command: 'tsc --noEmit'
Extend settings from a sibling task within the same project, or inherited from the global scope.
moon.yml
tasks:
  lint:
    command: 'eslint .'
    inputs:
      - 'src/**/*'
  
  lint-fix:
    extends: 'lint'
    args: '--fix'
    preset: 'utility'
The command to execute for the task.
moon.yml
tasks:
  format:
    # Using a string
    command: 'prettier --check .'
    # Using an array
    command:
      - 'prettier'
      - '--check'
      - '.'
Additional arguments to append to the command.
moon.yml
tasks:
  test:
    command: 'jest'
    # Using a string
    args: '--color --maxWorkers 3'
    # Using an array
    args:
      - '--color'
      - '--maxWorkers'
      - '3'
One or many commands to execute, with support for pipes, redirects, and more.
moon.yml
tasks:
  exec:
    # Single command
    script: 'cp ./in ./out'
    # Multiple commands
    script: 'rm -rf ./out && cp ./in ./out'
    # Pipes
    script: 'ps aux | grep 3000'
    # Redirects
    script: './gen.sh > out.json'
List of other tasks that will be executed before this task.
moon.yml
tasks:
  build:
    command: 'webpack'
    deps:
      - 'apiClients:build'
      - 'designSystem:build'
      # A task within the current project
      - 'codegen'
With args and env:
moon.yml
tasks:
  build:
    command: 'webpack'
    deps:
      - target: 'apiClients:build'
        args: ['--env', 'production']
        env:
          NODE_ENV: 'production'
Environment variables passed when running the command.
moon.yml
tasks:
  build:
    command: 'webpack'
    env:
      NODE_ENV: 'production'
      APP_TARGET: '${REGION}-${ENVIRONMENT}'
List of sources that calculate whether to execute this task based on touched files.
moon.yml
tasks:
  lint:
    command: 'eslint'
    inputs:
      # Config files
      - '**/.eslintrc.js'
      - '/.eslintignore'
      # Environment variables
      - '$FOO_CACHE'
      - '$FOO_*'
      # Tokens
      - '$projectRoot'
      - '@group(sources)'
      # File with content matching
      - file: 'project/relative/file.js'
        content: 'a|b|c'
      # Group references
      - group: 'sources'
        format: 'dirs'
      # External projects
      - project: 'foo'
        group: 'sources'
List of files and folders created as a result of executing this task.
moon.yml
tasks:
  build:
    command: 'webpack'
    outputs:
      - 'build/'
      - 'build/**/*.js'
      - '!build/internal.js'
Applies a preset to the task.Available presets:
  • server - For long-running servers
  • utility - For utility/interactive tasks
moon.yml
tasks:
  dev:
    command: 'webpack server'
    preset: 'server'
Defines the toolchain(s) the command runs on.
moon.yml
tasks:
  env:
    command: 'printenv'
    toolchains: 'system'
  
  build:
    command: 'npm run build'
    toolchains: ['javascript', 'node', 'npm']
Human-readable description of what the task does.
moon.yml
tasks:
  build:
    description: 'Builds the project using Vite'
    command: 'vite build'

​
Task Options

The options field configures how a task is executed.
moon.yml
tasks:
  typecheck:
    command: 'tsc --noEmit'
    options:
      mergeArgs: 'replace'
      runFromWorkspaceRoot: true
      cache: true
      retryCount: 3
cache: Whether to cache the task. Accepts true (default), false, local, or remote.persistent: Marks the task as persistent (continuously running). Defaults to false.interactive: Marks the task as interactive (runs in isolation). Defaults to false.runInCI: Whether to run in CI. Accepts always, affected, true (default), false, only, or skip.runFromWorkspaceRoot: Use workspace root as working directory. Defaults to false.affectedFiles: Pass affected files as arguments. Accepts true, false, args, or env.allowFailure: Allow task to fail without failing the pipeline. Defaults to false.retryCount: Number of retry attempts. Defaults to 0.timeout: Maximum time in seconds for the task to run.shell: Whether to run in a shell. Defaults to true for system toolchain.outputStyle: Controls output display. Accepts buffer, buffer-only-failure, hash, none, or stream.priority: Priority level. Accepts critical, high, normal (default), or low.

​
Docker Integration

​
docker

Configures Docker integration for the current project.
moon.yml
docker:
  file:
    buildTask: 'build'
    startTask: 'start'
    image: 'node:latest'
    runPrune: true
    runSetup: true
    template: 'templates/Dockerfile.tera'
  scaffold:
    configsPhaseGlobs:
      - '*.json'
    sourcesPhaseGlobs:
      - 'src/**/*'

​
Toolchains

​
toolchains

Overrides toolchain settings at the project level.
moon.yml
toolchains:
  default: 'node'

​
Complete Example

moon.yml
id: 'web-app'
language: 'typescript'
layer: 'application'
stack: 'frontend'
tags:
  - 'react'
  - 'nextjs'

project:
  title: 'Web Application'
  description: 'Main customer-facing web application'
  owner: 'frontend-team'
  maintainers: ['alice', 'bob']

dependsOn:
  - 'ui-components'
  - 'api-client'

fileGroups:
  sources:
    - 'src/**/*'
  tests:
    - 'tests/**/*'
    - '**/__tests__/**/*'

tasks:
  dev:
    command: 'next dev'
    preset: 'server'
  
  build:
    command: 'next build'
    inputs:
      - '@group(sources)'
    outputs:
      - '.next/'
    deps:
      - '^:build'
  
  test:
    command: 'jest'
    inputs:
      - '@group(tests)'
    options:
      retryCount: 2
  
  typecheck:
    command: 'tsc --noEmit'
    options:
      runFromWorkspaceRoot: true

Build docs developers (and LLMs) love

Get started for freeTalk to us