/git-integration-operations-cli

name: git-integration-operations-cli
description: "Runs the Fabric Git integration lifecycle through fab api or az rest, including connecting a workspace to Azure DevOps or GitHub, committing, updating from Git, reading sync status, resolving conflicts, disconnecting a connected workspace, and automating sync with a service principal. For stage promotion use deployment-pipelines-authoring-cli. Branch switching, fab deploy, fabric-cicd and cross-workspace rebinding are out of scope."
metadata:
  maturity: experimental
  owner: yaron

> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry > `x-ms-fabric-skill: git-integration-operations-cli` (`az rest`: `--headers "x-ms-fabric-skill=git-integration-operations-cli"`), > including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.

> **CRITICAL NOTES** > 1. To find a workspace ID from its name: list all workspaces, then filter by > `displayName` with JMESPath. To find an item ID: list items of that type in the > workspace, then filter by `displayName`. > 2. All Git operations are **control plane** calls against > `https://api.fabric.microsoft.com`. Run `fab auth login` once and `fab api` > sets the base URL and Fabric token audience automatically. With the `az rest` > fallback you must pass the matching `--resource` yourself, or you get a 401. > 3. `commitToGit`, `updateFromGit`, and even `git/status` can return **HTTP 202 > (long-running operation)**, not just a synchronous body. On `202`, poll the > operation: with `fab`, read `x-ms-operation-id` from `--show_headers` and poll > `fab api operations/{id}` until `status` is `Succeeded`; with the `az rest` > fallback, poll the `Location` / `x-ms-operation-id` header (see COMMON-CORE > long-running operation polling). THEN read `git/status` to confirm > `workspaceHead == remoteCommitHash`. Prefer the operation poll to confirm > completion; if you poll `git/status` instead, treat an in-progress (`202`) or > not-yet-synced response as "still running" and do not act on its `changes` > until the heads match. (Learn: rest/api/fabric/core/git and > fabric/cicd/git-integration/git-automation.) > 4. `updateFromGit` requires the workspace's **current** `workspaceHead`; a stale > value returns `400 WorkspaceHeadMismatch`. Always read `git/status` first. > 5. **Prerequisites for every Git operation:** the workspace must be assigned to a > **capacity** (an unassigned workspace fails with `WorkspaceHasNoCapacityAssigned`), > and the caller (user or service principal) must hold the right workspace > role: **connect and disconnect require Admin**; **commit and update require at > least Contributor** with write permission on all items; **branch switching > requires Admin** (or Contributor when the workspace opt-in setting *Allow users > with at least Contributor role to change Git branch* is on). Only one Git > operation may run against a workspace at a time. > 6. **Tenant admin switches** gate Git integration and are a common cause of an > unexplained failure. The **GitHub** sync switch is **off by default** (enable it > before any GitHub connect); Azure DevOps sync is on by default. Cross-region > workspace-to-*Azure*-repo needs the **cross-geo export** switch (GitHub does not > enforce it). See [references/git-integration-concepts.md § Tenant admin prerequisites](references/git-integration-concepts.md#tenant-admin-prerequisites).

Git Integration Operations — CLI Skill

Automate the Fabric Git integration lifecycle (connect, commit, update, status, disconnect) from CLI environments. Whether cross-workspace item references rebind after promotion is a separate concern, determined by the item definition format (logical vs object IDs) rather than the Git lifecycle itself.

Prerequisite Knowledge

Read these shared references first (paths assume this skill lives under `skills/git-integration-operations-cli/` in `skills-for-fabric`; adjust when drafting outside the repo):

• [COMMON-CLI.md § Finding Workspaces and Items in Fabric](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) — **Mandatory** for resolving workspace/item IDs by name.
• [COMMON-CORE.md § Authentication & Token Acquisition](../../common/COMMON-CORE.md#authentication--token-acquisition) — wrong audience = 401; read before any auth issue.
• [COMMON-CLI.md § Authentication Recipes](../../common/COMMON-CLI.md#authentication-recipes) — `az login` flows and token acquisition for CLI.
• [COMMON-CLI.md § Fabric Control-Plane API via az rest](../../common/COMMON-CLI.md#fabric-control-plane-api-via-az-rest) — the `az rest` **fallback** path (**always pass `--resource`**); includes LRO polling helpers.
• [COMMON-CORE.md § Core Control-Plane REST APIs](../../common/COMMON-CORE.md#core-control-plane-rest-apis) — pagination, long-running-operation polling, rate limiting.

Table of Contents

| Task | Reference | |---|---| | Pre-flight checks before connecting | [SKILL.md § Pre-Flight (before you connect)](#pre-flight-before-you-connect) | | Connect a workspace to Git | [SKILL.md § Connect a Workspace to Git](#connect-a-workspace-to-git) | | Create a git connection (service principal) | [SKILL.md § Create the Git provider connection (service principal)](#create-the-git-provider-connection-service-principal) | | Commit workspace items to Git | [SKILL.md § Commit to Git](#commit-to-git) | | Update a workspace from Git | [SKILL.md § Update from Git](#update-from-git) | | Check sync status | [SKILL.md § Check Sync Status](#check-sync-status) | | Resolve update conflicts | [SKILL.md § Resolve Conflicts](#resolve-conflicts) | | Disconnect from Git | [SKILL.md § Disconnect from Git](#disconnect-from-git) | | Link a branch workspace to its base (workspace relations) | [SKILL.md § Link a Branch Workspace to its Base (Workspace Relations)](#link-a-branch-workspace-to-its-base-workspace-relations) | | Git integrat