Overview
Each Mage project has ametadata.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.
overrides section (see
/extensibility/env-config/project).
Sample metadata.yaml
Top-level fields
Optional cluster type used by the project (e.g.,
k8s, docker). Used by Mage Pro
when running managed workspaces.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 path (e.g.,
s3://bucket/prefix) for storing variables in object
storage instead of the local filesystem.Default project metadata applied to new workspaces created from this project.
Mage Pro workspaces only.
Default workspace configuration applied across environments (e.g., k8s
defaults when running on Kubernetes). Mage Pro workspaces only.
Feature flags for the project (e.g.,
command_center, dbt_v2,
automatic_kernel_cleanup). Keys are booleans.Environment-specific overrides for any top-level field. Mage Pro only. See
/extensibility/env-config/project.Compute and execution
Spark configuration shared across pipelines (e.g.,
spark_master,
executor_env, spark_jars, use_custom_session).Observability and safety
Project-level alerting configuration (alert types, Slack/Teams webhooks, email,
managed delivery in Mage Pro, etc.). You can edit this in
metadata.yaml.
In Mage Pro, you can also edit it from Settings > Workspace > Alerts in the
Mage UI. Pipeline-level alert settings override this project-level configuration
for that pipeline.Managed notification delivery
Mage Pro managed alert delivery configuration. Set
enabled to true, use
channels: [email], and optionally add recipient email addresses under
email_config.to_emails. Leave to_emails empty to use managed API default
recipients when the operator has configured them. You can also set timeout,
which is capped at 30 seconds.Default automatic retry behavior applied to block runs at the project level.
In Mage Pro, you can configure these values from Settings > Workspace >
Automatic retry or by opening
/settings/workspace/automatic-retry.
Users with viewer access can open the page, but the retry controls are
read-only.
Mage merges retry settings from least specific to most specific: project
defaults, then pipeline-level retry_config, then block-level retry_config.
For the same retry field, the most specific configured value wins. Blank or
null retry fields are ignored during this merge, so a blank pipeline or
block field inherits the next available value from the less-specific config
instead of clearing it.retries: number of retry attempts after a block run fails. Use0to disable global automatic retries. Must be a non-negative integer up to100.delay: seconds to wait before the next retry attempt. Must be a non-negative integer up to86400.max_delay: maximum accumulated retry delay in seconds before scheduling the next attempt. This cap applies whether or not exponential backoff is enabled. Must be a non-negative integer up to86400.exponential_backoff: whether to increase the delay between retry attempts. If omitted, Mage uses the default enabled backoff behavior.
0 is accepted for numeric retry fields.