# description
fabric.yaml lives at the repository root and is the single source of truth for a repo's Fabric settings. It is an ordinary file tracked in the operation log, read from the trunk frontier when a policy is enforced. A string value may reference a stored secret with a ${secret.NAME} token: the file records the name only, never the value. The value lives encrypted in the repo's secret store (Settings, Secrets) and is substituted just in time when the setting is used, so the operation log never carries a secret byte. NAME is an uppercase env-var key (an uppercase letter then uppercase letters, digits, or underscores), and it must match a secret the store defines or the change is rejected at propose time.

# $defs.secretReference.description
A reference to a stored secret, written as ${secret.NAME}. NAME must be an uppercase env-var key matching a secret defined in the repo's secret store. The decrypted value is substituted just in time at enforcement; it is never written into the file, the operation log, logs, or rendered settings.

# $defs.colorKey.description
A key from Fabric's fixed badge/status palette. Only these keys are valid, so every override still resolves through the built-in color classes; the file changes which presets are offered and their labels, never the underlying color definitions.

# $defs.permission.description
A Fabric permission key, written as resource:action. Custom roles grant a subset of these. The built-in admin role grants all of them and is resolved from code, never listed in the file.

# properties.approval.description
Change-approval policy. Enforced when a change is accepted into trunk. A change is judged against the policy at its base frontier, so raising the bar inside a change never blocks that change.

# properties.approval.properties.required.description
How many distinct approving reviews a change needs before it can be accepted. 0 (the default) accepts without approval, matching Fabric's behavior when no fabric.yaml is present.

# properties.approval.properties.allow_self_approve.description
Whether the change author's own approval counts toward the required total. Defaults to false.

# properties.approval.properties.reviewers.description
Reviewers whose approvals count. Empty (the default) accepts an approval from anyone with vcs:write.

# properties.checks.description
Required-checks gate. Enforced when a change is accepted into trunk: every listed check must have passed in the change's latest run batch. Judged against the policy at the change's base frontier, so raising the bar inside a change never blocks that change.

# properties.checks.properties.required.description
Checks that must all pass before a change can be accepted. Each name matches a check run by its bare job name (for example "test") or by its "workflow / job" title. Empty (the default) gates on nothing, matching Fabric's behavior when no fabric.yaml is present.

# properties.tickets.description
Change-to-ticket policy. When required is true, a change must be linked to exactly one existing ticket before it can be proposed or accepted, and a second open (draft or proposed) change may not reference a ticket that already has a live one. Multiple accepted changes per ticket over time are always allowed. Judged against the policy at the change's base frontier. Absent (the default) enforces nothing, matching Fabric's behavior when no fabric.yaml is present.

# properties.tickets.properties.required.description
Whether a change must reference exactly one existing ticket to be proposed or accepted. Defaults to false.

# properties.roles.description
Custom roles for the organization, keyed by role key. Each key is a lowercase identifier (a lowercase letter then lowercase letters, digits, or underscores). The role's value lists the permissions it grants. The built-in admin role grants every permission and is resolved from code, so it is never listed here. When the roles section is absent, Fabric falls back to the role table it used before roles moved into the file.

# properties.roles.additionalProperties.properties.name.description
The human-readable role name shown in team settings.

# properties.roles.additionalProperties.properties.description.description
An optional one-line summary of what the role is for.

# properties.roles.additionalProperties.properties.permissions.description
The permissions this role grants. Each must be a known Fabric permission key.

# properties.agent.description
Organization-wide agent settings. Only settings that are org policy live here; per-user preferences stay with the user account.

# properties.agent.properties.voice_hotkey.description
The dictation hotkey for the org, such as "ctrl+space". When absent, Fabric falls back to the stored agent setting, then to its built-in default. A per-user hotkey override stays with the user and is not set here.

# properties.recording.description
Session-recording policy. Promotes the deploy-time SESSION_RECORDING_ENABLED toggle to a repo setting: a value here wins, and when the key is absent the deploy default still applies.

# properties.recording.properties.session_recording.description
Whether the session recorder is injected into authenticated pages for the org. When absent, the SESSION_RECORDING_ENABLED deploy default applies (off in production unless enabled, on elsewhere).

# properties.ui.properties.colors.description
Overrides the badge and status color presets offered in pickers. Each entry pairs a palette key with the label shown for it. Keys are constrained to Fabric's fixed palette, so every color still resolves through the built-in classes; only the offered set and its labels change. When absent, the code-defined presets are used.

# properties.ui.properties.colors.items.properties.label.description
The human-readable name shown for the preset in a color picker.

# properties.automations.description
Overrides workflow triggers, keyed by workflow name. Each value sets the trigger type and an optional match filter, overriding the stored workflow of that name. When absent, every workflow keeps its stored trigger.

# properties.automations.additionalProperties.properties.trigger_type.description
The event class that starts the workflow, such as "change_proposed".

# properties.automations.additionalProperties.properties.trigger_config.description
The trigger's match filter, compared against the trigger event. Omit it to match on trigger type alone.

# properties.notifications.description
Chat destinations and event-routing subscriptions. When this section is absent, Fabric falls back to the notification tables it used before routing moved into the file. When present, it is the source of truth: on accept it is projected into those tables, which the fan-out workers read at delivery time.

# properties.notifications.properties.destinations.description
Chat destinations keyed by a stable destination key. Each key is a lowercase identifier (a lowercase letter then lowercase letters, digits, or underscores). A subscription names a key here to route an event to that destination.

# properties.notifications.properties.destinations.additionalProperties.properties.provider.description
The chat provider this destination delivers through.

# properties.notifications.properties.destinations.additionalProperties.properties.name.description
The human-readable destination name shown in settings.

# properties.notifications.properties.destinations.additionalProperties.properties.channel.description
An optional target channel (Slack). Providers that do not use a channel ignore it.

# properties.notifications.properties.destinations.additionalProperties.properties.webhook.description
A ${secret.NAME} reference to the delivery webhook URL. The URL is never inlined: it lives in the repo secret store and is resolved just in time at delivery, so the operation log never carries it.

# properties.notifications.properties.destinations.additionalProperties.properties.enabled.description
Whether the destination delivers. Defaults to true when omitted.

# properties.notifications.properties.subscriptions.description
Event-to-sink routes. Each entry sends one event type to one sink (an in-app notification or a chat destination).

# properties.notifications.properties.subscriptions.items.properties.event_type.description
The domain event this subscription routes.

# properties.notifications.properties.subscriptions.items.properties.sink.description
The delivery channel: an in-app notification or a configured chat destination.

# properties.notifications.properties.subscriptions.items.properties.destination.description
The destination key this subscription delivers to when sink is chat. It must name a key under destinations. Omitted for an in_app sink.