Project metadata.yaml

Reference for configuring project-level settings in metadata.yaml.

Overview

Each Mage project has a metadata.yaml file at the root of the project directory. The file controls storage locations, feature flags, compute configuration, and defaults that apply to all pipelines in the project.

your_project/
├─ pipelines/
├─ .../
├─ io_config.yaml
├─ metadata.yaml   <-- project metadata lives here
├─ requirements.txt

Use the fields below to customize how your project behaves. For environment-specific overrides, add an overrides section (see /extensibility/env-config/project).

Sample metadata.yaml

project_type: standalone
variables_dir: ~/.mage_data
remote_variables_dir: s3://bucket/path_prefix
help_improve_mage: true

notification_config:
  alert_on:
    - trigger_failure
  slack_config:
    webhook_url: "{{ env_var('MAGE_SLACK_WEBHOOK_URL') }}"

pipelines:
  settings:
    triggers:
      save_in_code_automatically: true

project_uuid: 123456789abcdefg

Top-level fields

project_type · string enum

Project layout. Common options: standalone (default), main, or sub.

cluster_type · string

Optional cluster type used by the project (e.g., k8s, docker). Used by Mage Pro when running managed workspaces.

project_uuid · string

Unique identifier for the project. Generated when the project is created.

variables_dir · string

Local path for storing pipeline variables and outputs. Paths are relative to the project root unless an absolute path is provided. Default to /home/src/mage_data.

remote_variables_dir · string

Remote path (e.g., s3://bucket/prefix) for storing variables in object storage instead of the local filesystem.

variables_retention_period · string

How long variables are retained (e.g., 90d).

workspace_initial_metadata · object

Default project metadata applied to new workspaces created from this project. Mage Pro workspaces only.

workspace_config_defaults · object

Default workspace configuration applied across environments (e.g., k8s defaults when running on Kubernetes). Mage Pro workspaces only.

help_improve_mage · boolean

Allows Mage to collect limited telemetry to improve the product.

features · object

Feature flags for the project (e.g., command_center, dbt_v2, automatic_kernel_cleanup). Keys are booleans.

pipelines.settings.triggers.save_in_code_automatically · boolean

Whether new or updated triggers are automatically written to code.

overrides · object

Environment-specific overrides for any top-level field. Mage Pro only. See /extensibility/env-config/project.

Compute and execution

emr_config · object

Amazon EMR cluster settings (instance types, security groups, key pair, etc.).

spark_config · object

Spark configuration shared across pipelines (e.g., spark_master, executor_env, spark_jars, use_custom_session).

ecs_config · object

Project-level defaults for AWS ECS execution.

gcp_cloud_run_config · object

Project-level defaults for GCP Cloud Run execution.

azure_container_instance_config · object

Project-level defaults for Azure Container Instances execution.

k8s_executor_config · object

Kubernetes executor defaults applied to pipelines and blocks.

concurrency_config · object

Limits and concurrency settings at the project level.

queue_config · object

Configuration for queueing pipeline runs.

state_store_config · object

State store configuration used by pipelines.

Observability and safety

notification_config · object

Project-level alerting configuration (alert types, Slack/Teams webhooks, etc.).

logging_config · object

Configure log destinations and formats for the project.

retry_config · object

Default retry behavior applied at the project level.

ai_config · object

Global AI-related settings (e.g., model providers).

rag_config · object

Retrieval-augmented generation settings shared across pipelines.

openai_api_key · string

Project-level OpenAI API key used by AI features when applicable.

ldap_config · object

Optional LDAP connection settings for authentication.