---

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.

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 — Mandatory for resolving workspace/item IDs by name.
• COMMON-CORE.md § Authentication & Token Acquisition — wrong audience = 401; read before any auth issue.
• COMMON-CLI.md § Authentication Recipes — az login flows and token acquisition for CLI.
• 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 — pagination, long-running-operation polling, rate limiting.

Table of Contents

| Task | Reference | |---|---| | Pre-flight checks before connecting | SKILL.md § Pre-Flight (before you connect) | | Connect a workspace to Git | SKILL.md § Connect a Workspace to Git | | Create a git connection (service principal) | SKILL.md § Create the Git provider connection (service principal) | | Commit workspace items to Git | SKILL.md § Commit to Git | | Update a workspace from Git | SKILL.md § Update from Git | | Check sync status | SKILL.md § Check Sync Status | | Resolve update conflicts | SKILL.md § Resolve Conflicts | | Disconnect from Git | SKILL.md § Disconnect from Git | | Link a branch workspace to its base (workspace relations) | SKILL.md § Link a Branch Workspace to its Base (Workspace Relations) | | Git integration concepts (sync model, status, permissions) | references/git-integration-concepts.md § Concepts | | Tenant admin prerequisites (switches) | references/git-integration-concepts.md § Tenant admin prerequisites | | Supported Git providers | references/git-integration-concepts.md § Supported Git providers | | Supported item types | references/git-integration-concepts.md § Supported item types | | Avoiding formatting-only diffs (trailing newline / line endings) | references/git-integration-concepts.md § Avoiding formatting-only diffs | | Service principal / CI-CD pipeline templates | references/automation-templates.md | | Gotchas, Rules, Troubleshooting | SKILL.md § Gotchas, Rules, Troubleshooting |

Must/Prefer/Avoid

MUST DO

• Read git/status and pass the current workspaceHead into every commitToGit and updateFromGit call.
• Poll git/status after each async operation until workspaceHead == remoteCommitHash and the changes array is empty. A 202/Succeeded status is not proof of a correct sync — validate the state.
• Deploy an item together with the items it references in the same commit, so logical IDs can resolve inside the target workspace.

MUST NEVER

• Never run two Git operations concurrently on the same workspace — a second commitToGit/updateFromGit while one is still Running corrupts head tracking. Serialize: poll the first to Succeeded before starting the next.
• Never treat a workspace as both a source of truth and a CI/CD push target on the same branch. Pick one writer per branch: either humans commit from the workspace, or automation pushes to Git — not both at once.

PREFER

• fab api (after fab auth login) as the primary driver: it sets the base URL and Fabric token audience automatically, avoiding the 401 wrong-audience trap. Use az rest with --resource "https://api.fabric.microsoft.com" as the fallback when fab is unavailable or you need fine-grained header control.
• PreferRemote conflict resolution for a clean "pull latest from Git" into a downstream/target workspace.

AVOID

• Reusing a stale workspaceHead (causes 400 WorkspaceHeadMismatch).
• Passing request bodies via stdin to fab api (use -i <file.json> or -i '<inline JSON>').

---

CLI: fab primary, az rest fallback

Every operation below is shown with fab api. Run fab auth login once (it supports service principals for automation); fab then handles the base URL and token audience for you. The identical call on the az rest fallback is a mechanical translation:

Authenticate fab for the identity you are running as:

fab auth login                                              # interactive user (SSO)
fab auth login -u <client-id> -p <client-secret> --tenant <tenant-id>   # service principal (CI/CD)
fab auth login --identity                                   # managed identity (Azure compute)

A service principal or managed identity must be workspace Admin to connect or disconnect (at least Contributor with write on all items is enough for commit/update) and (for the ConfiguredConnection path) hold the git provider credentials. See references/automation-templates.md for full pipeline scripts.

• fab api <endpoint> becomes az rest --method GET --url "https://api.fabric.microsoft.com/v1/<endpoint>" --resource "https://api.fabric.microsoft.com".
• fab api -X post <endpoint> -i body.json adds --method POST --headers "Content-Type=application/json" --body @body.json.

fab api reads a request body via -i from either a file path or an inline JSON string (e.g. -i '{"displayName":"..."}') — never from stdin. It prints {"status_code": <code>, "text": <parsed body>} (add --show_headers for a top-level headers object), so read response fields with jq -r '.text.<field>' and the LRO id with jq -r '.headers["x-ms-operation-id"]'. See Example 2 for a full az rest pair.

---

Pre-Flight (before you connect)

Run these Git-relevant checks in order before git/connect. Each failure has a specific fix — resolving them up front avoids the most common connect-time errors.

| Check | Command | Pass = proceed / Fail = fix | |---|---|---| | Auth + Fabric token | fab auth login then fab api workspaces | 401 → re-login (fab sets the correct audience automatically) | | Caller is workspace Admin | fab api "workspaces/${WORKSPACE_ID}/roleAssignments" | Connect/disconnect require the Admin role | | Workspace has capacity | fab api "workspaces/${WORKSPACE_ID}" → check capacityId | WorkspaceHasNoCapacityAssigned → assign a capacity (Git requires one) | | Git credential for the SP path | fab api connections (reuse if one already fits) | SP connect needs a ConfiguredConnection. If none exists, the skill creates it from your ADO org/project/repo + SP tenant/client/secret — see Create the Git provider connection (needs the tenant toggle "service principals can create connections"). The interactive-user SSO path uses Automatic and needs no connection. | | Target directoryName exists on the branch | GitHub: curl -fsS -H "Authorization: Bearer $PAT" "https://api.github.com/repos/$OWNER/$REPO/contents/$DIR?ref=$BRANCH" — ADO: Items API on the repo | The API (unlike the portal) does not create a missing folder — connecting to a directoryName that doesn't exist fails with 404 GitProviderResourceNotFound. If the folder is new,