moon migrate

Migrate moon workspaces and configuration between versions

The moon migrate command helps you migrate existing moon workspaces to newer versions by automatically updating configuration files, renaming settings, and applying breaking changes.

moon migrate <subcommand>

Subcommands

v2

Migrate an existing moon v1 workspace to moon v2.

moon migrate v2 [options]

Options

--yes

Useful for automated migration scripts or CI/CD pipelines.

How it works

The migration process:

1. Prompts for confirmation - Unless --yes is provided, asks before modifying files
2. Migrates configuration files in this order:
   • workspace.yml - Core workspace settings
   • toolchain.yml → toolchains.yml - Toolchain configuration
   • tasks.yml and tasks/**/*.yml - Global and inherited task configs
   • **/moon.yml - Individual project configurations
3. Updates settings automatically:
   • Renames deprecated settings
   • Removes obsolete options
   • Restructures configuration to match v2 schema
   • Converts variable syntax ($projectName → $projectTitle)
4. Reformats files - Strips comments and standardizes YAML formatting

The migration will strip all comments from configuration files and re-format them. Make sure to commit any important comments or documentation before running the migration.

Pkl-based configuration files (.pkl extension) cannot be automatically migrated. You’ll need to manually update these files.

Migration changes

Workspace configuration

Changes applied to workspace.yml:

• runner → pipeline
• unstable_remote → remote
• vcs.manager → vcs.client
• vcs.syncHooks → vcs.sync
• codeowners.syncOnRun → codeowners.sync
• codeowners.orderBy: project-name → project-id
• constraints.enforceProjectTypeRelationships → constraints.enforceLayerRelationships
• docker.scaffold.include → docker.scaffold.configsPhaseGlobs
• docker.prune.installToolchainDeps → docker.prune.installToolchainDependencies
• Removes: experiments, docker.scaffold.copyToolchainFiles, hasher.batchSize, pipeline.archivableTargets
• Extracts extensions to separate extensions.yml file

Toolchain configuration

Changes applied when migrating toolchain.yml → toolchains.yml:

• File renamed from toolchain.yml to toolchains.yml
• Node.js settings:
  • node.binExecArgs → node.executeArgs
  • node.bun, node.npm, node.pnpm, node.yarn → separate toolchain entries
  • Removes: node.addEnginesConstraint
  • Moves package manager settings to javascript section
• Python settings:
  • python → unstable_python
  • python.pip, python.uv → unstable_pip, unstable_uv
  • Removes: rootRequirementsOnly, rootVenvOnly
• Deno settings:
  • Removes: deno.depsFile, deno.lockfile
• All unstable settings promoted to stable (removes unstable_ prefix)

Task configuration

Changes applied to tasks.yml, tasks/**/*.yml, and project tasks:

• platform → toolchains
• command → script (if command contains shell operators: ||, &&, |, ;, >, >>, <)
• local: true → preset: server
• preset: watcher removed
• deps[].args converted from string to array
• Renames tasks.yml → tasks/all.yml
• Adds inheritedBy field based on file name patterns:
  • tag-* → { tag: "*" }
  • Detects toolchain, stack, layer, language from filename

Project configuration

Changes applied to **/moon.yml files:

• type → layer
• platform → toolchains.default
• toolchain → toolchains
• project.name → project.title
• project.metadata flattened into project
• docker.scaffold.include → docker.scaffold.sourcesPhaseGlobs
• toolchains.*.disabled removed
• Task changes applied (same as task configuration above)

Variable syntax

All token variables updated:

• $projectName → $projectTitle
• $projectType → $projectLayer
• $taskPlatform → $taskToolchain

Examples

Interactive migration

moon migrate v2

You’ll be prompted:

? Migrate configuration files?
  This will strip comments and re-format the files.
  [y/N]

Type y to proceed with the migration.

Automatic migration

moon migrate v2 --yes

All migrations will be applied immediately without prompts. Perfect for automation:

#!/bin/bash
# Backup workspace
tar -czf workspace-backup.tar.gz .moon/ **/moon.yml

# Run migration
moon migrate v2 --yes

# Verify and commit
git add -A
git commit -m "chore: migrate to moon v2"

Before and after examples

Workspace configuration

Before (v1):

runner:
  cacheLifetime: 24h

vcs:
  manager: git
  syncHooks: true

experiments:
  - action-pipeline-v2

After (v2):

pipeline:
  cacheLifetime: 24h

vcs:
  client: git
  sync: true

Task configuration

Before (v1 - tasks.yml):

tasks:
  build:
    command: 'tsc && vite build'
    platform: node

After (v2 - tasks/all.yml):

tasks:
  build:
    script: 'tsc && vite build'
    toolchains:
      - node

Project configuration

Before (v1):

type: application
platform: node

project:
  name: My API
  metadata:
    tier: 1

tasks:
  start:
    command: node server.js
    local: true

After (v2):

layer: application

toolchains:
  default: node

project:
  title: My API
  tier: 1

tasks:
  start:
    command: node server.js
    preset: server

Best practices

1. Backup first - Always commit your current configuration or create a backup before migrating:

   git add -A && git commit -m "chore: backup before v2 migration"
   

2. Review changes - After migration, review all changed files:

   git diff
   

3. Test thoroughly - Run your tasks to ensure everything still works:

   moon check --all
   

4. Update documentation - If you have internal docs referencing old settings, update them

5. Handle Pkl files manually - Pkl configuration files must be migrated by hand

Limitations

• Pkl files not supported - .pkl configuration files cannot be auto-migrated
• Comments are removed - All YAML comments will be stripped during migration
• Custom formatting lost - Files are reformatted using standard YAML formatting
• No rollback - The command doesn’t create automatic backups; use version control

Exit codes

• 0 - Migration completed successfully
• Non-zero - Migration failed or was cancelled