Skip to main content

​
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.
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

​
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.