Configuration Reference¶

Complete reference for all configuration properties.

Step Properties¶

Every step in your configuration can use these properties. Properties are grouped by function.

Quick Reference Table¶

Property	Type	Applies To	Description
Identification
`name`	string	All	Human-readable step name
Actions (one required)
`shell`	string	Shell	Shell command to execute
`file`	object	File	File/directory operation
`template`	object	Template	Template rendering
`include`	string	Include	Include steps from another file
`include_vars`	string	Variables	Load variables from file
`vars`	object	Variables	Define inline variables
Control Flow
`when`	string	All	Conditional expression
`tags`	array[string]	All	Tags for filtering
Loops
`with_items`	string	All	Iterate over list
`with_filetree`	string	All	Iterate over directory
Privilege
`become`	boolean	shell, file, template	Execute with sudo
`become_user`	string	shell only	User for sudo (e.g., 'postgres')
Shell Execution Control
`env`	object	shell only	Environment variables
`cwd`	string	shell only	Working directory
`timeout`	string	shell only	Maximum execution time
`retries`	integer	shell only	Number of retry attempts
`retry_delay`	string	shell only	Delay between retries
Result Control
`changed_when`	string	shell only	Override changed status
`failed_when`	string	shell only	Override failure status
`register`	string	All	Variable name to store result

Property Details¶

name¶

Type: string Applies to: All actions Required: No (but recommended)

Human-readable description displayed in output.

- name: Install dependencies
  shell: npm install

shell¶

Type: string Applies to: Shell action Required: When using shell action

Command to execute in bash shell.

- shell: echo "Hello"

# Multi-line
- shell: |
    echo "Line 1"
    echo "Line 2"

# With variables
- shell: echo "{{message}}"

Supports: - Template variable substitution - Multi-line commands with | - All shell-specific fields

file¶

Type: object Applies to: File action Required: When using file action

File or directory operation.

Properties:

Property	Type	Required	Description
`path`	string	Yes	File/directory path
`state`	string	No	`file`, `directory`, or `absent`
`content`	string	No	Content to write to file
`mode`	string	No	Permissions (e.g., `"0644"`, `"0755"`)

# Create directory
- file:
    path: /tmp/myapp
    state: directory
    mode: "0755"

# Create file with content
- file:
    path: /tmp/config.txt
    state: file
    content: "key: value"
    mode: "0644"

template¶

Type: object Applies to: Template action Required: When using template action

Render pongo2 template file.

Properties:

Property	Type	Required	Description
`src`	string	Yes	Source template file path
`dest`	string	Yes	Destination file path
`vars`	object	No	Additional variables for template
`mode`	string	No	Permissions (e.g., `"0644"`)

- template:
    src: ./config.yml.j2
    dest: /etc/app/config.yml
    mode: "0644"
    vars:
      port: 8080
      debug: true

include¶

Type: string Applies to: Include action Required: When using include action

Path to YAML file containing steps to include.

- include: ./tasks/common.yml

# With condition
- include: ./tasks/linux.yml
  when: os == "linux"

# With variables
- include: ./tasks/{{env}}.yml

include_vars¶

Type: string Applies to: Variable loading action Required: When using include_vars action

Path to YAML file containing variables to load.

- include_vars: ./vars/production.yml

# Dynamic
- include_vars: ./vars/{{environment}}.yml

vars¶

Type: object Applies to: Variable definition action Required: When using vars action

Define inline variables.

- vars:
    app_name: MyApp
    version: "1.0.0"
    environment: production
    ports:
      web: 8080
      api: 8081

when¶

Type: string Applies to: All actions Required: No

Conditional expression. Step executes only if expression evaluates to true.

Operators: ==, !=, >, <, >=, <=, &&, ||, !

# OS check
- shell: brew install git
  when: os == "darwin"

# Multiple conditions
- shell: install-package
  when: os == "linux" && memory_total_mb >= 8000

# Using register results
- shell: which docker
  register: docker_check

- shell: echo "Docker not found"
  when: docker_check.rc != 0

tags¶

Type: array[string] Applies to: All actions Required: No

Tags for filtering step execution via --tags flag.

- shell: npm test
  tags: [test, dev]

- shell: deploy-production
  tags: [prod, deploy]

Usage:

# Run only dev steps
mooncake run --config config.yml --tags dev

# Multiple tags (OR logic)
mooncake run --config config.yml --tags dev,test

with_items¶

Type: string Applies to: All actions Required: No

Iterate over list. Step executes once for each item with {{item}} variable.

# List literal
- shell: echo "{{item}}"
  with_items: [a, b, c]

# Variable reference
- vars:
    packages: [git, vim, tmux]

- shell: brew install {{item}}
  with_items: "{{packages}}"

with_filetree¶

Type: string Applies to: All actions Required: No

Iterate over files in directory tree. Step executes for each file.

Item properties: - {{item.name}} - File name - {{item.src}} - Full source path - {{item.is_dir}} - Boolean, true if directory

- shell: cp "{{item.src}}" "/backup/{{item.name}}"
  with_filetree: ./dotfiles
  when: item.is_dir == false

become¶

Type: boolean Applies to: shell, file, template actions Required: No Default: false

Execute step with sudo privileges.

- shell: apt update
  become: true

- file:
    path: /opt/myapp
    state: directory
  become: true

Requirements: - Must provide --sudo-pass flag or use --raw mode - User must have sudo privileges