fab-dev 0.1.1

Developer CLI for Fabric feature-branch workspace provisioning.

Microsoft Fabric - Development Worfklows CLI

The Development Workflows CLI for Microsoft Fabric (fab-dev) is designed to support git-based development tasks on top of Fabric.

Quick start

# Install the CLI
pip install fab-dev

# Authenticate
fab-dev auth login                           # authenticate yourself

# Start developing on Fabric
fab-dev create my_feature --dev-branch dev       # creates a workspace attached to a feature branch cut from dev branch
fab-dev sync push <workspace-id|workspace-url|workspace-name>     # push changes in the branch
fab-dev sync pull <workspace-id|workspace-url|workspace-name>     # downloads latest changes in workspace
fab-dev pr create                                                 # opens a Pull Request

✨ Key Features

🌱 Feature Branch Provisioning

• Create a feature branch and provision a corresponding Fabric workspace in one command.
• Validate branch ancestry against a configurable dev baseline.
• Reuse an existing target workspace when rerunning to keep workflows idempotent.

🔑 Built-In Authentication Commands

• Use fab-dev auth login for interactive user, service principal, or managed identity sign-in.
• Use fab-dev auth status to verify token availability and inspect active account/tenant.
• Use fab-dev auth logout to clear local auth context and reset CLI token cache.

🔄 Git-Aware Workspace Sync

• Pull branch snapshots into a workspace with conflict-aware behavior.
• Push workspace changes back to the connected branch with an optional message.
• Inspect sync status in human-readable or JSON format.

🔐 Access and Governance Defaults

• Grant or revoke users and groups by role.
• Assign branch creator as workspace admin during provisioning.
• Support user/group identity mapping for enterprise directory scenarios.

🧹 Lifecycle Cleanup

• Remove feature workspaces safely when a branch is done.
• Optionally delete the feature branch from origin and local repo.
• Keep cleanup idempotent so repeated execution does not fail on missing resources.

🤝 PR Flow Integration

• Open pull requests to merge feature branches into dev.
• Works with GitHub and Azure DevOps remotes.

🧱 Environment Scaffolding

• Bootstrap baseline environments (dev,test,prod) in one run.
• Create/reuse environment branches and mapped Fabric workspaces using deterministic naming.
• Keep prod/main protected by default (no auto-sync unless explicitly enabled).

📦 Installation

Prerequisites

• Python 3.11+
• A Microsoft Fabric tenant and capacity
• A repository using a dev branch model (for example dev and feat/*)
• A dev workspace attached to that capacity and dev repository
• Multiple developers working from a dev branch

Install from local source

pip install -e .

Verify installation

fab-dev --help
fab-dev --version

Developer tooling (formatting)

This repository uses black as the Python formatter.

# Install dev tools
pip install -r requirements-dev.txt

# Run formatter manually
black .

# Install git pre-commit hook (auto-format on commit)
pre-commit install

After pre-commit install, every local commit runs Black automatically.

🔐 Authentication

Current CLI operations authenticate using one of the following:

• FABRIC_ACCESS_TOKEN, or
• an authenticated Azure CLI session via az login

CLI auth commands:

• fab-dev auth login
• fab-dev auth status [--json]
• fab-dev auth logout

For pull request creation:

• GitHub: FAB_DEV_GITHUB_TOKEN (or GITHUB_TOKEN / GH_TOKEN) or gh auth login
• Azure DevOps: FAB_DEV_AZDO_PAT (or AZURE_DEVOPS_EXT_PAT) or az login

🎯 Usage Examples

Authenticate and Verify Session

# Interactive sign-in
fab-dev auth login

# Service principal sign-in
fab-dev auth login -u <client_id> -p <client_secret> --tenant <tenant_id>

# Managed identity sign-in
fab-dev auth login --identity

# Verify current auth/session details
fab-dev auth status --json

# Sign out local auth context
fab-dev auth logout

Create and Provision

# Create from short feature name (expands to feat/my_feature)
fab-dev create my_feature --dev-branch dev

# Create from explicit branch name
fab-dev create feat/my_feature

# Override creator/capacity and grant access during create
fab-dev create my_feature \
  --creator [e-mail] \
  --capacity-id <fabric-capacity-guid> \
  --add-user [e-mail]:Contributor \
  --add-group data-eng:Viewer

Sync Workspace and Branch

# Check git sync status
fab-dev sync status <workspace-id|workspace-url|workspace-name>

# Pull latest branch snapshot into workspace
fab-dev sync pull <workspace-id|workspace-url|workspace-name>

# Pull and overwrite pending local workspace changes
fab-dev sync pull <workspace-id|workspace-url|workspace-name> --force

# Push workspace changes to branch
fab-dev sync push <workspace-id|workspace-url|workspace-name> --message "Update notebook"

# Push workspace changes with positional quoted message
fab-dev sync push <workspace-id|workspace-url|workspace-name> "Update notebook"

Manage Access

# Grant role assignments
fab-dev access grant <workspace-ref> --user [e-mail]:Contributor --group data-eng:Viewer

# Revoke assignments
fab-dev access revoke <workspace-ref> --group data-eng

Open Pull Requests

# Create PR from current branch to dev
fab-dev pr create

# Customize PR target/title/body
fab-dev pr create --target-branch dev --title "Add customer churn notebook" --body "Implements feature workflow"

Scaffold Environment Baseline

Prerequisites for scaffold: 0. Authenticate by running fab-dev auth login

1. Clone the repository and change directory into the local clone.
2. Resolve the Fabric capacity ID (GUID), or use capacity name.
   • Open an existing workspace on that capacity.
   • Copy the workspace ID from URL /groups/<workspaceId>.
   • Run fab-dev sync status <workspace-id|workspace-url|workspace-name> --json.
   • Use the capacityId field from output.

# Dry-run scaffold plan
fab-dev scaffold init --capacity-id <fabric-capacity-guid> --workspace-prefix contoso --dry-run

# Interactive scaffold: enter capacity ID or capacity name, choose env profile
# (dev/test/prod | dev/prod | dev only), then enter branch names and workspace prefix
fab-dev scaffold init

# Non-interactive scaffold env branches and workspaces (prod maps to main)
fab-dev scaffold init \
  --capacity-id <fabric-capacity-guid> \
  --workspace-prefix contoso \
  --env-branches dev,test,prod \
  --non-interactive \
  --yes

# Use capacity name as alternative input
fab-dev scaffold init \
  --capacity-name "Contoso Capacity" \
  --workspace-prefix contoso \
  --yes

# Allow remapping existing workspace branch links and prod sync
fab-dev scaffold init \
  --capacity-id <fabric-capacity-guid> \
  --workspace-prefix contoso \
  --rebind \
  --sync-prod \
  --yes

Notes:

• Workspace mapping is deterministic: <workspace-prefix>-<env>.
• If prefix contains spaces, env suffix is appended with a space (example: Scaffolding Try dev).
• If prefix uses _ separators, env suffix uses _ (example: scaffolding_try_dev).
• Interactive runs always show a dry-run review phase (including planned workspace names) before execution.
• Review phase includes a topology diagram (repo -> branch -> workspace -> capacity) for each environment.
• If main does not exist, scaffold bootstraps it with a minimal commit before creating env branches.
• If a workspace already exists but is mapped to a different branch, scaffold fails unless --rebind is provided.
• prod maps to main by default and is protected from auto-sync unless --sync-prod is set.

Cleanup

# Cleanup workspace resolved from current feature branch
fab-dev cleanup --yes

# Cleanup specific feature and delete branch locally/remotely
fab-dev cleanup feat/my_feature --yes --delete-branch

# Cleanup explicit workspace reference
fab-dev cleanup --workspace-ref <workspace-id|workspace-url|workspace-name> --yes

🧭 Command Groups

Command	Purpose
auth login	Authenticate for Fabric operations
auth status	Show current authentication status and token source
auth logout	Clear local authentication context
create	Create/publish feature branch and provision Fabric workspace
sync pull	Pull connected branch snapshot into workspace
sync push	Push workspace changes to connected branch
sync status	Show workspace sync status
access grant	Grant users/groups roles in workspace
access revoke	Revoke users/groups from workspace
workspace list	List visible workspaces
pr create	Create pull request in git provider
cleanup	Delete feature workspace and optionally branch
scaffold init	Bootstrap env branches and mapped Fabric workspaces
help	Show command-specific help

⚙️ Configuration

Common flags

• --dev-branch controls the baseline branch for create/cleanup flows (default dev).
• --feature-prefix controls feature branch naming (default feat/).
• --workspace-prefix provides fallback workspace naming when discovery is unavailable.

Environment variables

• FABRIC_ACCESS_TOKEN
• FABRIC_CAPACITY_ID
• FABRIC_WORKSPACE_PREFIX
• FABRIC_AZ_CLI_PATH
• FAB_DEV_AZ_SUBSCRIPTION
• FABRIC_PRINCIPAL_MAP_JSON
• FABRIC_USER_MAP_JSON
• FABRIC_GROUP_MAP_JSON
• FAB_DEV_GITHUB_TOKEN
• GITHUB_TOKEN
• GH_TOKEN
• FAB_DEV_AZDO_PAT
• AZURE_DEVOPS_EXT_PAT

🏗️ Architecture Notes

Current implementation is REST-first for deterministic request/response control and predictable automation behavior.

For a visual overview of branch-to-workspace relationships, open workspace-topology.html.

• Runtime entrypoint: fab_dev/main.py
• Parser wiring: fab_dev/core/parser_setup.py
• Command parsers: fab_dev/parsers/
• Command handlers: fab_dev/commands/
• Existing implementation core: fab_dev/cli.py

🛡️ Operational Design Principles

• Deterministic workspace naming and branch-to-workspace mapping
• Idempotent command behavior for retries and reruns
• Least-privilege access assignment defaults
• Capacity-aware provisioning and safe failure handling
• Auditable lifecycle operations (provision, sync, cleanup)

📄 Project Status

This repository is focused on the first production-ready iteration of the fab-devworkflow. Near-term evolution typically includes provider abstraction options and expanded parity tests for alternative execution paths.

🤝 Contributing

We welcome contributions from the community. Whether you are fixing bugs, adding features, improving documentation, or helping other users, your contributions are valuable.

Quick Start Contributing

1. Check existing issues - Look for issues labeled help-wanted.
2. Read our guidelines - See CONTRIBUTING.md for detailed instructions.
3. Fork and clone - Set up your development environment.
4. Create a pull request - Link it to the related issue.

Before contributing, please review our Contributing Guidelines and Code of Conduct.

🆘 Support & Community

Getting Help

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and community support
• Documentation - Usage guidance and examples in this repository
• Microsoft Community - Connect with other Fabric developers: https://community.fabric.microsoft.com/t5/Developer/bd-p/Developer

Feature Requests

• GitHub Issues - Technical feature requests
• Fabric Ideas Portal - Product-level feature suggestions: https://ideas.fabric.microsoft.com/

Enterprise Support

• Contact your Microsoft account manager.
• Microsoft Fabric Support - Official support: https://support.fabric.microsoft.com/

🔄 Release Notes

See VERSIONING.md for versioning policy and release workflow details.

📄 License

This project is licensed under the MIT License. See LICENSE for details.