Project 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') }}"
  managed_config:
    enabled: true
    channels:
      - email
    email_config:
      to_emails:
        - data-oncall@example.com
    timeout: 10

pipelines:
  settings:
    triggers:
      save_in_code_automatically: true

project_uuid: 123456789abcdefg

Top-level fields

string enum

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

string

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

string

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

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.

string

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

string

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

object

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

object

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

boolean

Allows Mage to collect limited telemetry to improve the product.

object

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

boolean

Whether new or updated triggers are automatically written to code.

object

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

Compute and execution

object

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

object

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

object

Project-level defaults for AWS ECS execution.

object

Project-level defaults for GCP Cloud Run execution.

object

Project-level defaults for Azure Container Instances execution.

object

Kubernetes executor defaults applied to pipelines and blocks.

object

Limits and concurrency settings at the project level.

object

Configuration for queueing pipeline runs.

object

State store configuration used by pipelines.

Observability and safety

object

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 > Account > Alerts in the Mage UI. Pipeline-level alert settings override this project-level configuration for that pipeline.

object

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.

object

Configure log destinations and formats for the project.

object

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.

retry_config:
  retries: 3
  delay: 5
  max_delay: 60
  exponential_backoff: true

retries: number of retry attempts after a block run fails. Use 0 to disable global automatic retries. Must be a non-negative integer up to 100.
delay: seconds to wait before the next retry attempt. Must be a non-negative integer up to 86400.
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 to 86400.
exponential_backoff: whether to increase the delay between retry attempts. If omitted, Mage uses the default enabled backoff behavior.

In Mage Pro, blank project-level retry fields are omitted from saved project metadata, and 0 is accepted for numeric retry fields.

object

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

object

Retrieval-augmented generation settings shared across pipelines.

string

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

object

Optional LDAP connection settings for authentication.

Adventure starts here

Concepts

Project

Contributing

About

Project metadata.yaml

Overview

Sample `metadata.yaml`

Top-level fields

Compute and execution

Observability and safety

​Overview

​Sample metadata.yaml

​Top-level fields

​Compute and execution

​Observability and safety

Overview

Sample `metadata.yaml`

Top-level fields

Compute and execution

Observability and safety