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

notification_config:
  alert_on:
  - trigger_failure
  - trigger_passed_sla
  slack_config:
    webhook_url: "{{ env_var('MAGE_SLACK_WEBHOOK_URL') }}"
  teams_config:
    webhook_url: "{{ env_var('MAGE_TEAMS_WEBHOOK_URL') }}"
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.