Skip to content

allez.yml

allez's own file: automation config for the whole solution. The same filename is used at two scopes; where the file sits decides its scope.

See the repo structure for its position beside the fabric-cicd files and item folders.

Scope File May contain
Solution root fabric/allez.yml version, environments, protected-branches, branch-workspace (with its git), dag
Per workspace fabric/<sub-folder>/allez.yml version, branch-workspace (a patch over the root), audit

A sub-folder's effective config is the root file merged with its own file, key by key (the sub-folder wins), then resolved for one --env.

fabric/ is a name, not a rule. One root is.

The solution root is whichever folder holds the allez.yml that declares environments:. Nothing in allez expects it to be called fabric/: every verb takes a path (allez deploy solution --env dev), .allez/ sits beside whatever that folder is, and a branch workspace's name is [repo]-[branch-slug]-[sub-folder], so the root's name never reaches Fabric. The docs and the sample say fabric/ because the example does. The example's pipelines pass the folder as deployRoot and filter their triggers on it, so a renamed root is one edit there.

Two roots in one repo, say fabric/sales/allez.yml and fabric/finance/allez.yml, each with its own environments: and dag:, is not a supported shape. Each verb only sees the root you point it at, so the two load and deploy separately, and that is where the trouble starts: branch workspace names carry no root, so two sub-folders with the same name in different roots collide; allez teardown --orphans matches on the repo name, so a sweep run from one root deletes the other root's orphaned workspaces too; $allez.<sub-folder> cannot reach a sub-folder in the other root; the VS Code extension shows the root with the shortest path and ignores the other; and the pipelines need a job per root. One repo holds one solution (philosophy); a second domain is a second repo. The case is recorded in the allez repo's plan.md under "Several solution roots", with what it would take to change the answer.

Editor support

allez.schema.json describes both scopes. With the YAML extension, a first-line comment that names it enables completion, hover text and shape checks. Name it at the allez tag you install, so the checks match the installed version:

fabric/allez.yml, and each fabric/<sub-folder>/allez.yml
# yaml-language-server: $schema=https://raw.githubusercontent.com/EvaluationContext/allez/0.1.0/allez.schema.json

To edit offline, or where the editor cannot reach GitHub, copy the file from that tag to your repo root and name it by path instead: $schema=../allez.schema.json in the root file, $schema=../../allez.schema.json in a sub-folder's. The sample in this repo does that, because the schema sits beside it.

The loader also checks environment names, paths on disk and dependencies on every run (Rejected at load). It remains the authority where editor checks differ.

Examples

fabric/allez.yml
version: 1
environments: [feature, dev, test, prod]
protected-branches: [main]   # trunk-based: no verb makes a branch workspace for main

branch-workspace:   # branch workspaces only — dev/test/prod are made outside allez
  capacity: F4-Standard-Capacity
  roles:
    - principal: data-devs@contoso.com
      id: bbbbbbbb-1111-2222-3333-444444444444
      role: Contributor
  git:              # how `allez deploy --branch-workspace --commit-to-git` connects a branch workspace to its branch
    provider: AzureDevOps
    organization: contoso
    project: Data Platform
    repository: my-fabric-solution
    connection-name: Fabric git (SPN)   # made once with `fab mkdir`; required
    base-env: dev                       # optional — the UI relation only

dag:      # deploy order over config files
  - config: data/config.yml
    post_deploy_hooks: [data/.deploy/hooks/ingest.hooks.yml]
  - config: reporting/config.yml
    depends_on: [data/config.yml]
fabric/data/allez.yml
# workspace patch
version: 1
branch-workspace:
  description: "Core data engineering — warehouse + ingestion notebooks"
  identity: true
  settings:
    sparkSettings:
      job:
        sessionTimeoutInMinutes: 30

environments

Required, root file only. The list of environments --env allez can deploy into. Every environment name used anywhere else, as --env or inside the file, is checked against it at load, so a typo fails instead of silently doing nothing:

fabric/allez.yml
version: 1
environments: [feature, dev, test, prod]

branch-workspace:
  capacity:
    default: F4-Standard-Capacity
    prd: F64-Prod-Capacity        # not in `environments:` → fails at load, nothing deploys
allez deploy fabric --env uat --plan
allez deploy failed: Unknown environment 'uat'. fabric/allez.yml declares: feature, dev, test, prod.

Each declared environment is one of two kinds, depending on whether config.yml names a workspace for it:

  • Named environment: each sub-folder's config.yml names its workspace under core.workspace.<env> (for example dev: data-dev). These are long-lived environments such as dev, test and prod.
  • Branch environment: declared in environments:, with no core.workspace entry in config.yml. The workspace belongs to a branch: a branch workspace, which allez provision creates and allez deploy --env feature --branch-workspace --commit-to-git fills.
Adding a second branch environment

The name feature means nothing to allez; any environment with no core.workspace entry behaves the same way.

You can add more branch environments, such as hotfix for hotfix/* branches. Two things to know:

  • The pipeline needs changing. provision-feature.yml refuses any branch outside feature/* and passes --env feature. Copy it for hotfix/* with --env hotfix, or widen its guard and choose --env from the branch prefix. The CLI itself refuses only main, master and release/*.
  • One branch environment per branch. The branch workspace name has no environment in it. Provision the same branch for two branch environments and both share one workspace: the second deploy overwrites the first, and nothing fails. Keep each branch environment on its own branch prefix.

protected-branches

Optional, root file only. The branches no verb may make a branch workspace for: allez apply, allez provision and allez deploy --branch-workspace refuse them before any fab call, and allez teardown never deletes a workspace named for one. A list of branch names or * globs, matched on the branch's slug, so release/* and release-* agree. Absent means [main, master, release/*]; [] protects nothing.

fabric/allez.yml
version: 1
environments: [feature, dev, test, prod]
protected-branches: [main, dev, test]   # a Git Flow repo: its deployed branches

The pipeline's first step is the other half: it says which branches may be provisioned at all, and a repo on another flow edits it with the rest of the pipeline.

branch-workspace

Settings for the branch workspaces of branch environments, which allez provision --env <branch environment> creates and applies them to; the git: block is read by allez deploy --branch-workspace. None of it reaches a named environment (dev, test, prod).

Put defaults in the root file; every sub-folder inherits them. Put values that belong to one workspace in that sub-folder's file.

Key Value What provision does with it
capacity capacity display name fab mkdir … -P capacityName=<name> at creation. On a re-run, an existing workspace on another capacity is moved with fab assign; one already there is reported as such. A capacity the identity cannot see is a warning.
description text fab set … -q description
settings nested mapping Flattened to a.b.c paths and applied one by one with fab set -q <path> -i <value>. Leaf values may be Override Maps.
networking nested mapping Same mechanism, for the workspace's networking properties.
identity true / false Provisions the system-assigned workspace identity. If it already exists, that is reported, not an error.
roles list One fab acl set per entry (roles).
tags list of {value} Tag display names. Each is matched against fab api tags, and the ones not already on the workspace go in one fab api workspaces/<id>/applyTags call. A tag must already exist in the tenant or in the workspace's domain; a name that does not is a warning. At most ten. allez never removes a tag.
domain {name, id} fab api workspaces/<id>/assignToDomain with the id. Skipped when the workspace is already in it; a refusal is a warning. Copy the id from the domain's page in the Fabric admin portal.
git mapping Root file only. Read by allez deploy --branch-workspace (git), and ignored by provision.
fabric/allez.yml
branch-workspace:
  capacity: F4-Standard-Capacity
  description: "Core data engineering — warehouse + ingestion notebooks"
  identity: true
  settings:
    sparkSettings:
      job:
        sessionTimeoutInMinutes: 30
      highConcurrency:
        notebookPipelineRunEnabled: true
  domain:
    name: Data Platform
    id: dddddddd-1111-4222-8333-444444444444
  tags:
    - value: analytics-core                       # must already exist in the tenant

roles

Each entry:

Key Required Meaning
principal yes A label for people to read: a UPN, group or app name. Also the key that matches a root entry to a sub-folder entry when they merge.
id for the grant The principal's Entra object id. fab acl set grants by id and cannot look an id up from a name, so an entry without an id is reported and skipped.
role yes Admin, Member, Contributor or Viewer.
environments no Inclusion Filter.
fabric/allez.yml
branch-workspace:
  roles:
    - principal: fabric-pipelines-spn             # the pipeline identity: Admin on every
      id: aaaaaaaa-1111-2222-3333-444444444444    # branch workspace, so `teardown --orphans`
      role: Admin                                 # can see and delete them
    - principal: data-devs@contoso.com
      id: bbbbbbbb-1111-2222-3333-444444444444
      role: Contributor
    - principal: qa-reviewers@contoso.com         # no id → reported and skipped, never granted
      role: Viewer

git

How allez deploy --branch-workspace connects a branch workspace to its branch. Root file only. Values may be Override Maps.

Key Required Meaning
provider no AzureDevOps (default) or GitHub.
organization, project, repository Azure DevOps The repo Fabric connects to. repository is also the <repo> segment of every derived workspace name.
owner, repository GitHub Likewise.
directory no Path inside the repo the workspace is connected to. Default: the sub-folder's path from the repo root.
connection-name yes An existing Fabric git connection (a source control connection), matched by exact display name. allez never creates one and carries no secret (make it once).
base-env no Once the git connection is made, each branch workspace is related to the workspace this environment's config.yml names, so the Fabric UI shows it as a branch of that workspace; the base must itself be git-connected to the same repo root (dev to main, if dev is connected). If unset, no relation is made and the deploy says so.
fabric/allez.yml
branch-workspace:
  git:
    provider: AzureDevOps
    organization: contoso
    project: Data Platform
    repository: my-fabric-solution
    connection-name: Fabric git (SPN) # exact display name; must exist
    base-env: dev                     # optional — relate branch workspaces to dev's; nothing is committed to it
fabric/allez.yml
branch-workspace:
  git:
    provider: GitHub
    owner: contoso
    repository: my-fabric-solution
    connection-name: Fabric git (GitHub) # exact display name; must exist
    base-env: dev

The sample in this repo uses this shape, because the repo lives on GitHub.

audit

Sub-folder file only. Findings of allez audit in this sub-folder that are the design, each with the reason:

fabric/ws_bronze/allez.yml
audit:
  accept:
    - kind: order
      file: .deploy/parameters/landing.parameter.yml
      value: $workspace.historical-files-prod.$items.Lakehouse.Landing.$id
      environments: [feature, dev]
      reason: feature and dev read prod's landing files through the shortcut, by design

The keys and what an accepted finding does are on Accepting a finding.

dag

Root file only, and required: one node per fab deploy config, with its hooks (The deployment dag).

fabric/allez.yml
dag:
  - config: data/config.yml
    post_deploy_hooks: [data/.deploy/hooks/ingest.hooks.yml]
  - config: reporting/config.yml
    depends_on: [data/config.yml]
    pre_deploy_hooks: [reporting/.deploy/hooks/takeover.hooks.yml]

Environment resolution

A value can differ per environment. Two patterns do this:

Override Map

One key, a different value per environment. In place of a plain value, write a map of environment names, with default for the rest:

capacity:                       # in place of `capacity: F4-Standard-Capacity`
  default: F4-Standard-Capacity
  hotfix: F64-Prod-Capacity

--env hotfix gets F64-Prod-Capacity; every other environment gets default. With no default and no key for the environment, capacity is left out.

Inclusion Filter

One list entry, for some environments only. Add environments: to the entry:

roles:
  - principal: data-devs@contoso.com
    id: bbbbbbbb-1111-2222-3333-444444444444
    role: Contributor
    environments: [feature]     # this entry: feature only
  - principal: ops@contoso.com
    id: cccccccc-1111-2222-3333-444444444444
    role: Admin                 # no filter: every env

--env feature gets both roles; --env hotfix gets only ops@contoso.com.

Both work inside branch-workspace (root or sub-folder file) and on dag nodes (The deployment dag), the only places allez resolves per environment.

Merging

A sub-folder's file is laid over the root's: mappings merge key by key, and a list of mappings merges entry by entry, matching a role by principal and a tag by value, so a sub-folder never repeats the whole list. An override with no environments applies to every environment, even if the root entry had a filter.

Both patterns across a root file and a sub-folder, resolved with --env hotfix for data:

fabric/allez.yml
environments: [feature, hotfix, dev, test, prod]

branch-workspace:
  capacity:
    default: F4-Standard-Capacity
    hotfix: F64-Prod-Capacity
  roles:
    - principal: data-devs@contoso.com
      id: bbbbbbbb-1111-2222-3333-444444444444
      role: Contributor
      environments: [feature]
fabric/data/allez.yml
branch-workspace:
  capacity:
    hotfix: F128-Heavy-Capacity
  roles:
    - principal: data-devs@contoso.com
      id: bbbbbbbb-1111-2222-3333-444444444444
      role: Member

The resolved block, as printed:

allez provision fabric/data --env hotfix --plan
branch-workspace:
  capacity: F128-Heavy-Capacity
  roles:
    - principal: data-devs@contoso.com
      id: bbbbbbbb-1111-2222-3333-444444444444
      role: Member

Per-environment values in branch-workspace reach branch environments only. A prod: key under branch-workspace.capacity passes the load check and then changes nothing. With feature as the only branch environment, write plain values; an Override Map or Inclusion Filter here is only useful with two or more branch environments, such as feature and hotfix above.

Rejected at load

Before any fab call:

  • an unsupported version (1 is the only one), or an unknown key at any scope (the error lists the allowed keys);
  • a root file without environments:, or a sub-folder file with no root to patch;
  • an Override Map key or environments: filter naming an environment the root doesn't declare;
  • a role or tag missing a required field, a non-GUID id, a non-boolean identity;
  • an audit.accept entry with an unknown kind, no value or reason, or environments on a kind that isn't per environment or naming one the root doesn't declare;
  • a git block in a sub-folder file, an unknown git.provider, a provider's required keys missing, no connection-name, a base-env naming an environment the root doesn't declare;
  • anything in the "Rejected before any fab call" box on The deployment dag.