Set up EasyFabric with an AI agent

The fastest way to bootstrap a new EasyFabric project is the /setup-easyfabric skill for Claude Code. It downloads a versioned platform release into an empty folder, interviews you for tenant, workspace and environment values, patches the YAML configuration, and prints the remaining checklist for Microsoft Entra, Azure, Microsoft Fabric and Azure DevOps.

You move from an empty folder to a configured, push-ready repository in a single guided session.

What you'll need

• Claude Code installed and signed in.
• An empty folder for the new project (the agent refuses to extract on top of existing EasyFabric files).
• Python 3 on PATH (used by the bundled fetch/patch helpers — stdlib only, nothing to install).
• An EasyFabric license key (the agent will ask for it).
• Access to your Microsoft Entra tenant, Azure subscription, Microsoft Fabric capacity, and Azure DevOps project. You don't need everything created up front — the agent flags missing values as <<TBD>> and lists them in the closing checklist.

The Azure CLI (az) is optional. If it's installed and signed in, the agent uses it to pre-fill values like your tenant ID; otherwise it just asks.

Running the agent

From the empty target folder, launch Claude Code and paste this single line:

Download https://api.appdm.net/api/skill/setup-easyfabric.zip, extract it to a temp folder, and follow the instructions in setup-easyfabric/SKILL.md.

Claude downloads the skill bundle, unpacks it, reads SKILL.md, and walks the stages below. You can interrupt, redirect or accept defaults at any point.

To pin a specific version, swap setup-easyfabric.zip for setup-easyfabric-<version>.zip — the same naming scheme as the platform release manifest at api.appdm.net/api/skill/versions.json.

1. Answer the interview

Questions are grouped so you can answer in batches:

• Project basics — short name, environments (dev / tst / acc / prd), default Azure region.
• Microsoft Entra — tenant ID, app registration client ID, Key Vault secret name for the app secret.
• Azure infrastructure per environment — resource group and Key Vault names.
• Azure DevOps — organization URL, project name, service connection per environment, agent pool.
• Microsoft Fabric per environment — workspace name (the workspace you create manually in the Fabric portal — see Why workspaces are pre-created below) and lakehouse layer names. EasyFabric resolves the workspace GUID at runtime from the name, so only the name is stored.

Sensible defaults are pre-filled (e.g. rg-<platform>-<env>, SC_<PLATFORM>_<ENV>). Anything you don't know becomes a <<TBD: name>> placeholder you can fill in later.

2. Review the patched files

The agent surgically updates the YAML config that came out of the release zip:

• Generator/Dataplatform/DP/Configuration/dp.<env>.yaml — environment description, service connection, resource group, tenant, app registration, Key Vault, workspace IDs, tabular model name.
• Yml/environments/<env>.yaml — Key Vault, service connection, Fabric workspace ID/name, tenant.
• Yml/variables/global.yaml — default pool, agent, environment, location, service connection.

Per-environment files that don't exist yet are seeded from the nearest sibling. Indentation, quoting and comments in the originals are preserved.

3. Follow the closing checklist

The agent prints a tailored checklist with copy-pasteable commands for everything it couldn't do automatically. The major groups:

1. Microsoft Entra — app registration, client secret, API permissions for Power BI / Fabric.
2. Azure — one az group create per env (a human with subscription Contributor runs this once), grant the deploy SPN Contributor + Role Based Access Control Administrator on each RG, then run the bundled Yml/infrastructure.yml pipeline to create the Key Vault and the SPN's scoped Key Vault Secrets User role. After the pipeline succeeds, upload the SPN client secret to the KV manually. See Which rights the SPN needs for the exact role list.
3. Microsoft Fabric — capacity assignment, manual workspace creation in the portal (one per environment, using the names you gave in the interview), lakehouses (Bronze, Silver, Gold, Meta), and adding the service principal as Workspace Admin on each workspace. All steps are [PORTAL] by design — see Why workspaces are pre-created.
4. Azure DevOps — create the Git repo, git init and first push from the configured folder, set up the service connection (federated identity preferred), variable group, and pipeline import.

Any remaining <<TBD>> placeholders are listed at the end with file and line, so nothing slips through.

After setup

Once the checklist is complete:

1. Push your initialised folder to the new Azure DevOps repo.
2. Run the Deploy-Fabric-Environment pipeline against your first environment.
3. Verify the Bronze, Silver, Gold and Meta lakehouses appear in the Fabric workspace.

From there, follow the Basics section to add your first source system and table.

Troubleshooting

• "Target folder not empty" — the agent refuses to write into a folder containing Generator, Yml, FabricBuilds, DM or .git. Either run in a fresh folder or pass --allow-non-empty when re-running the install helper.
• SHA-256 mismatch — the release manifest was likely updated mid-fetch. Re-run /setup-easyfabric to retry with the current manifest.
• Cloudflare 403 — the fetch helper sends a custom user agent so this should not happen; if it does, check that outbound HTTPS to api.appdm.net is permitted.
• Status of the release feed — visit api.appdm.net/api/status to confirm the platform release feed and all EasyFabric API endpoints are healthy.

Why workspaces are pre-created manually

EasyFabric deliberately does not create Microsoft Fabric workspaces for you. A human creates each workspace once in the Fabric portal, then adds the service principal as Workspace Admin. The agent asks you for the workspace names so the YAML config matches what you've created (or are about to create).

This is a least-privilege choice for the service principal that runs your deploy pipeline:

Permission the SPN needs	Where it's granted	Scope
Call Fabric REST APIs at all	Tenant setting Service principals can call Fabric public APIs (auth-only gate; enabled by default on new tenants)	Tenant, but grants no data access on its own
Everything inside a workspace — create lakehouses, items, run jobs, read/write OneLake, manage permissions	Workspace Admin role on each workspace	One workspace at a time
(Skipped) Create workspaces, connections, deployment pipelines anywhere	Tenant setting Service principals can create workspaces, connections, and deployment pipelines — leave off	Tenant-wide privilege the SPN does not need

With pre-created workspaces, the SPN can do anything inside the workspaces you've granted it — full CRUD on Lakehouses, Warehouses, notebooks, pipelines, semantic models, OneLake data, item permissions — but cannot create new workspaces, cannot create cloud connections, and cannot touch admin APIs elsewhere in the tenant. If the SPN credentials are ever compromised, the blast radius is bounded to those workspaces, not the tenant.

The portal steps you do once, per environment:

1. Assign a Fabric capacity (F-SKU or trial) in the workspace region.
2. Create the workspace with the exact name you gave the agent (case-sensitive — it must match the YAML).
3. Assign the workspace to the capacity.
4. Open the workspace → Manage access → add your service principal with role Admin.
5. Create the four lakehouses: Bronze, Silver, Gold, Meta.

If the SPN doesn't appear in the Manage access picker, it isn't in the security group allowed by Service principals can call Fabric public APIs. Add it to that group and retry.

Which rights the SPN needs

The "deploy SPN" is the Microsoft Entra service principal behind each environment's Azure DevOps service connection — the identity that runs the bundled pipelines (Yml/infrastructure.yml, Yml/main_build.yaml). It's the same SPN whose App (client) ID you gave the agent during the interview. Below is the full list of rights it needs and the exact scope for each.

Microsoft Entra

No tenant-level roles required. The SPN just needs to exist as an app registration with a credential. Membership in the security group allowed by the Fabric tenant setting Service principals can call Fabric public APIs is required and is the only tenant-wide gate.

Azure

The pre-flight (one-time per env, run by a human with subscription Contributor):

# Create the resource group the env will live in
az group create --name rg-<platform>-<env> --location <region>

# Grant the deploy SPN scoped rights on that RG
RG_ID=$(az group show --name rg-<platform>-<env> --query id -o tsv)
az role assignment create --assignee <appId> --role "Contributor" --scope "$RG_ID"
az role assignment create --assignee <appId> --role "Role Based Access Control Administrator" --scope "$RG_ID"

That's the full Azure setup — one az group create and two role assignments, scoped to one resource group, per environment. Everything else (the Key Vault, the Key Vault Secrets User role on it, tags) is provisioned by the infrastructure pipeline.

Resulting role set for the deploy SPN, per env:

Role	Scope	Granted by	Used for
Contributor	Resource group	Human, one-time	Creating the Key Vault, tagging
Role Based Access Control Administrator	Resource group	Human, one-time	Granting the SPN the next role on its own KV
Key Vault Secrets User	The Key Vault	infrastructure.yml, automatically	Reading the SPN client secret at deploy time

Zero-manual alternative. If you'd rather skip the human az group create, grant the deploy SPN Contributor + Role Based Access Control Administrator at subscription scope instead. The pipeline will then create the RG itself. Only do this when the subscription is dedicated to EasyFabric — in a shared subscription, the SPN can touch anything in it.

Microsoft Fabric

Role	Scope	Granted by	Used for
Membership in the Service principals can call Fabric public APIs security group	Tenant (auth gate only)	Tenant admin, one-time	Authenticating against Fabric REST APIs
Workspace Admin	Each pre-created workspace	Human (workspace owner), one-time per workspace	Creating lakehouses, deploying notebooks/semantic models, reading/writing OneLake, etc.

The Fabric tenant settings Service principals can create workspaces, connections, and deployment pipelines and Service principals can access admin APIs are deliberately left off — the SPN doesn't need them and they would be tenant-wide privilege.

Azure DevOps

The service connection itself (one per env) needs to be authorised for pipelines. After az devops service-endpoint azurerm create, run:

az devops service-endpoint update --id <id> --enable-for-all

If you prefer per-pipeline authorisation over enable-for-all, authorise each pipeline against the service connection individually in the Azure DevOps UI.

Summary

The deploy SPN's full blast radius for one environment, after all setup is done:

• Azure: one resource group + one Key Vault inside it (read secrets, manage resources in the RG). Cannot touch anything else in the subscription.
• Fabric: one workspace (full admin inside). Cannot create workspaces, cannot touch other workspaces, cannot touch admin APIs.
• Entra: no roles at all beyond existing as an app registration.

Lose the SPN credentials and the worst-case impact is one environment, not the tenant.

Without Claude Code

If you can't run Claude Code at all, the same artefacts are downloadable directly:

# Platform release (the YAML/notebook/config bundle that gets patched)
curl https://api.appdm.net/api/platform/versions.json
curl -O https://api.appdm.net/api/platform/easyfabric-platform-latest.zip
unzip easyfabric-platform-latest.zip

# Skill bundle (read SKILL.md as a runbook; the Python helpers are stdlib only)
curl -O https://api.appdm.net/api/skill/setup-easyfabric.zip
unzip setup-easyfabric.zip

You then walk the steps in setup-easyfabric/SKILL.md and setup-easyfabric/REFERENCE.md yourself, calling scripts/fetch-release.py and scripts/patch-config.py from the command line and answering the interview questions in a JSON file. The agent path is strongly recommended — it removes the easiest places to make a typo (tenant GUIDs, workspace IDs, service connection names).