Skip to content

Branch workspaces

A branch environment is one the root allez.yml declares under environments: and config.yml gives no core.workspace entry. The sample calls it feature. Each branch gets one workspace per sub-folder, named from the branch as [<repo>]-[<branch-slug>]-[<sub-folder>] and found by that name at run time (allez provision). Give the environment publish.skip and unpublish.skip entries in each config.yml.

fabric/allez.yml
# yaml-language-server: $schema=https://raw.githubusercontent.com/EvaluationContext/allez/0.1.0/allez.schema.json
version: 1
environments: [feature, dev, test, prod]
protected-branches: [main]            # never a branch workspace for a deployed branch
fabric/data/config.yml
core:
  workspace:            # no `feature` entry: the branch workspace is named from the branch
    dev:  data-dev
    test: data-test
    prod: data-prod
  repository_directory: "."
  item_types_in_scope: [Notebook, Lakehouse]
  parameter: "parameter.yml"

publish:
  skip:
    feature: false      # the binding deploy publishes into the branch workspace
    dev: false
    test: false
    prod: false

unpublish:
  skip:
    feature: true       # never delete a developer's uncommitted items
    dev: false
    test: false
    prod: false

The root allez.yml's branch-workspace: block allows you to configure how allez provision configures the workspace and how allez deploy --branch-workspace connects it to git.

fabric/allez.yml
# yaml-language-server: $schema=https://raw.githubusercontent.com/EvaluationContext/allez/0.1.0/allez.schema.json
version: 1
environments: [feature, dev, test, prod]
protected-branches: [main]            # never a branch workspace for a deployed branch

branch-workspace:
  capacity: F4-Standard-Capacity
  git:
    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

Protected branches

Branches that match protected-branches: in the root allez.yml never get a branch workspace: provision, apply and deploy --branch-workspace refuse them before any fab call, and teardown never deletes a workspace named for one. Without the key, the list is [main, master, release/*].

Provision

On the branch, create the workspaces, then deploy into them and connect them to git:

allez provision fabric --env feature
allez deploy fabric --env feature --branch-workspace --commit-to-git

--env feature selects a declared environment that has no named workspace. Run the two by hand, or from a pipeline. The example's provision-feature.yml runs both, queued once on the branch (example usage); the allez repo's sample-provision.yml workflow runs them when a sample/feature/* branch is created (GitHub Actions).

  1. Create with allez provision

    Each workspace is created and configured from the branch-workspace block: capacity, roles, settings, identity, domain and tags. It inherits nothing from a base workspace, and it starts empty.

  2. Fill with allez deploy --branch-workspace

    The derived workspace's id is resolved at run time and passed to fab deploy for that run only. It is a deploy, not an update from git, because only a deploy runs parameter.yml, which rewrites the references autobinding does not reach.

  3. Connect and commit with --commit-to-git

    Only then is each workspace connected to the branch and committed, so the branch and the workspace agree.

  4. Relate, if branch-workspace.git.base-env is set

    The workspace is related to that environment's workspace, so the Fabric UI shows it as a branch of dev. For that, the base workspace must be connected to git at the same repo root. Never update the base from git or commit from it: it would take the branch workspace's ids.

Teardown after the merge

allez teardown fabric --orphans

--orphans deletes every branch workspace of this repo whose branch is gone from the remote. A merge on its own leaves the workspaces in place, so run it after each merge; the example deploy.yml runs it after every deploy to dev. Leave the pull request's delete source branch option on, or the sweep finds nothing to delete. To remove one branch's workspaces while the branch still exists, run allez teardown fabric --branch <name> (scopes).

Full reference: allez provision, allez deploy, allez teardown and the branch-workspace block.