git-integration-operations-cli

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.

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.

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.

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.

Connect a workspace to an Azure DevOps or GitHub repo, then initialize the connection to establish the sync direction.

# 1. Connect (Azure DevOps example). Body goes in a file, passed with -i.
cat > connect.json <<'JSON'
{
  "gitProviderDetails": {
    "gitProviderType": "AzureDevOps",
    "organizationName": "myorg",
    "projectName": "MyProject",
    "repositoryName": "fabric",
    "branchName": "main",
    "directoryName": "/workspace-a"
  }
}
JSON
fab api -X post "workspaces/${WORKSPACE_ID}/git/connect" -i connect.json

# 2. Initialize the connection (choose which side wins on first sync)
printf '{"initializationStrategy":"PreferWorkspace"}' > init.json
fab api -X post "workspaces/${WORKSPACE_ID}/git/initializeConnection" -i init.json

Use PreferWorkspace when the workspace already has the authoritative items; PreferRemote when the Git branch is authoritative.

The target directoryName must already exist on the branch. Unlike the Fabric portal — which silently creates a missing folder by committing a README.md placeholder into it — the git/connect API does not create the folder. Connecting to a directoryName that does not exist on the branch fails with 404 GitProviderResourceNotFound. The repo and branch must exist too (connect never creates a branch). If the folder is new, create it first by committing a placeholder file to the branch through the Git provider's API (not a Fabric API), then connect. Match the portal's convention with a README.md whose body is This is an auto-created file via Fabric skills for <workspace-name>.

Copy

# GitHub: create <DIR>/README.md on <BRANCH> (reuse the PAT behind the Git connection)
DIR="workspace-a"; WS_NAME="My Workspace"
CONTENT=$(printf 'This is an auto-created file via Fabric skills for %s\n' "$WS_NAME" | base64)
cat > mkfolder.json <<JSON
{ "message": "Create ${DIR} folder for Fabric Git connect", "branch": "${BRANCH}", "content": "${CONTENT}" }
JSON
curl -fsS -X PUT -H "Authorization: Bearer ${GITHUB_PAT}" \
  "https://api.github.com/repos/${OWNER}/${REPO}/contents/${DIR}/README.md" -d @mkfolder.json
# Azure DevOps equivalent: POST .../_apis/git/repositories/${REPO}/pushes with an
# "add" change for "/${DIR}/README.md" on refs/heads/${BRANCH} (same body content).

Two authentication modes (both providers use myGitCredentials for automation). A workspace authenticates to git in one of two ways:

• Automatic git credential (Azure DevOps only): the connecting user's SSO identity, established from workspace settings. Secondary contributors with at least Contributor reuse it. Not available for GitHub, and not usable for headless / service-principal automation.
• Configured credential (Azure DevOps and GitHub): a Fabric cloud connection referenced in the connect body. This is the required path for any service principal or unattended run:
  Copy

  "myGitCredentials": { "source": "ConfiguredConnection", "connectionId": "<connection-guid>" }

  For Azure DevOps, the connection's credentialType can be either ServicePrincipal (headless automation) or OAuth2 (a stored delegated user token); both are valid ConfiguredConnection credentials per the Create Connection API and both support multitenant scenarios. For GitHub, connecting a workspace requires a Personal Access Token (PAT): the cloud connection stores a fine-grained token with Contents Read (plus Write to commit), or a classic token with the repo scope. GitHub has no automatic credential mode, so a PAT is mandatory even for an interactive user connect. The distinction is not "GitHub needs credentials, ADO does not". ADO also requires a ConfiguredConnection whenever a service principal drives the connect; the automatic mode only covers interactive user SSO. (Learn: fabric/cicd/git-integration/automate-git-integration-with-service-principal; rest/api/fabric/core/git/connect.)

Handle the initialize response. initializeConnection returns requiredAction (UpdateFromGit, CommitToGit, or None) plus workspaceHead and remoteCommitHash, and can itself return 202. After it settles, call the sync operation named by requiredAction with the returned hashes, or the workspace stays connected but not fully synced. (Learn: rest/api/fabric/core/git/initialize-connection.)

Push workspace items to the connected branch. Read the head first, then commit.

# Read current head. git/status can return 202 (LRO) with no body — capture the
# status code with --show_headers and poll before reading, or workspaceHead comes
# back as "null" and the commit below fails with a misleading 400.
RESP=$(fab api "workspaces/${WORKSPACE_ID}/git/status" --show_headers)
if [ "$(echo "$RESP" | jq -r '.status_code')" = "202" ]; then
  OP=$(echo "$RESP" | jq -r '.headers["x-ms-operation-id"]')
  until [ "$(fab api "operations/${OP}" | jq -r '.text.status')" = "Succeeded" ]; do sleep 5; done
  RESP=$(fab api "workspaces/${WORKSPACE_ID}/git/status" --show_headers)   # now 200 with body
fi
HEAD=$(echo "$RESP" | jq -r '.text.workspaceHead')

# Commit all pending changes. Build the body with jq so the comment is always
# valid JSON even if it contains a quote, backslash, or newline.
jq -n --arg head "$HEAD" --arg msg "Author items" \
  '{mode:"All", workspaceHead:$head, comment:$msg}' > commit.json
RESP=$(fab api -X post "workspaces/${WORKSPACE_ID}/git/commitToGit" -i commit.json --show_headers)
# commitToGit may complete synchronously (200) or async (202). Only poll when async.
if [ "$(echo "$RESP" | jq -r '.status_code')" = "202" ]; then
  OP=$(echo "$RESP" | jq -r '.headers["x-ms-operation-id"]')
  until [ "$(fab api "operations/${OP}" | jq -r '.text.status')" = "Succeeded" ]; do sleep 5; done
fi

Use "mode": "Selective" with an items array to commit a subset. commitToGit completes either synchronously (200, already settled) or asynchronously (202 with an x-ms-operation-id to poll) — branch on .status_code as above rather than assuming 202.

Pull committed items into a workspace (for example, a downstream or target workspace connected to the same branch/folder).

# Read both hashes from the target workspace
STATUS=$(fab api "workspaces/${TARGET_WS}/git/status")
TH=$(echo "$STATUS" | jq -r '.text.workspaceHead')
REMOTE=$(echo "$STATUS" | jq -r '.text.remoteCommitHash')

cat > update.json <<JSON
{
  "workspaceHead": "${TH}",
  "remoteCommitHash": "${REMOTE}",
  "conflictResolution": {
    "conflictResolutionType": "Workspace",
    "conflictResolutionPolicy": "PreferRemote"
  },
  "options": { "allowOverrideItems": true }
}
JSON
fab api -X post "workspaces/${TARGET_WS}/git/updateFromGit" -i update.json

Poll until the workspace and remote heads match. Both commitToGit and updateFromGit are asynchronous, so this loop is how you know they finished.

for i in $(seq 1 30); do
  S=$(fab api "workspaces/${WORKSPACE_ID}/git/status")
  WH=$(echo "$S" | jq -r '.text.workspaceHead')
  RC=$(echo "$S" | jq -r '.text.remoteCommitHash')
  CH=$(echo "$S" | jq -r '.text.changes | length')
  # Success = heads match AND no residual changes. Heads matching alone can still
  # leave uncommitted/unapplied diffs; validate both before declaring "synced".
  [ "$WH" = "$RC" ] && [ "$CH" = "0" ] && { echo "synced at $WH"; break; }
  sleep 8
done

For an operation still in flight (a 202 from commit/update), poll the LRO directly instead of guessing from heads:

# Capture x-ms-operation-id from the 202, then poll until Succeeded
OP_ID=$(fab api -X post "workspaces/${WORKSPACE_ID}/git/commitToGit" -i commit.json \
  --show_headers | jq -r '.headers["x-ms-operation-id"]')
while :; do
  ST=$(fab api "operations/${OP_ID}" | jq -r '.text.status')
  case "$ST" in Succeeded) break ;; Failed) echo "op failed"; break ;; *) sleep 5 ;; esac
done

git/status also returns a changes array — a non-empty array means there are uncommitted (workspace) or unapplied (remote) differences.

A genuine conflict is changed-on-both-sides: after the last sync, the same item was modified in the workspace (an uncommitted local edit) and on the branch (a new commit). git/status flags that item in its changes array with conflictType: "Conflict" (both workspaceChange and remoteChange show Modified). This is distinct from a one-sided diff, where only updateFromGit (remote-only change) or commitToGit (workspace-only change) is needed with no policy.

When both sides changed an item, updateFromGit requires a conflict policy — calling it without a conflictResolution block returns 400 MissingWorkspaceConflictResolution:

• conflictResolutionPolicy: "PreferRemote" — the Git branch wins (typical for pull-into-target deployment); the local edit is discarded.
• conflictResolutionPolicy: "PreferWorkspace" — the live workspace wins; to push the workspace version to Git instead use commitToGit, which does not take a conflict policy.

Set options.allowOverrideItems: true to let the update overwrite items that already exist in the target workspace (required whenever the conflicting item is already present in the workspace, which it is by definition in a both-sides conflict).

Which policy to pick:

Preview. The Git workspace relations APIs are part of the Fabric Git surface and are in preview. They record a lineage link between a branch workspace and the base workspace it was branched from, so the base↔branch relationship is visible in the Fabric portal. Use them when a branch workspace was created before the built-in branch-out feature shipped, or when branch workspaces are provisioned by your own automation (not the portal branch-out UX) and you still want that lineage to show in the UI. Creating a relation does not connect either workspace to Git, move items, or start a sync — it only records the link.

Precondition — both workspaces must point at the same Git root. Create fails with WorkspaceRelationRootDirectoryMismatch unless the base and branch workspaces are connected to the same repository root, differing only by branch:

• Azure DevOps: same organizationName, projectName, repositoryName, and directoryName — only branchName differs.
• GitHub: same repository URL and directoryName — only branchName differs.

So connect (and initialize) both workspaces to Git first; the relation just makes the existing branch/base pair visible.

Updating a target workspace from the same branch promotes items into it. Whether each item-to-item reference rebinds automatically (logical IDs) or breaks (object IDs / hardcoded endpoints) is a property of the item definition format, not of the Git lifecycle, and applies equally to fabric-cicd and the Bulk Import API. To predict a specific dependency's verdict, read the evidence-tagged compatibility matrix, or empirically validate an uncertain reference, use the cross-workspace-item-binding skill (a planned companion skill, not yet available in this repo) — it is a distinct concern from the connect/commit/update lifecycle this skill drives.

To manage the connect side declaratively (infrastructure as code) instead of with imperative fab api calls, use the git-integration-terraform skill (a planned companion skill, not yet available in this repo). It covers the microsoft/fabric provider's fabric_connection and fabric_workspace_git resources (Azure DevOps service principal or automatic, GitHub PAT, init strategy, plan/apply/import). In that pattern Terraform owns the connection, while the commit / update-from-git / status operations in this skill remain the imperative runtime path — so a common setup is Terraform for the connection plus a CLI step for update-from-git.

Git integration moves item definitions across workspaces, but it does not by itself parameterize values that must differ per stage (dev/test/prod) — connection strings, endpoints, capacity IDs, feature flags. That per-environment parameterization is the job of a Variable Library: define the variables once, provide a value set per stage, and have items resolve the stage-appropriate value. When a Git-synced workspace needs values that vary by environment, use the variable-library-cli companion skill for the variable/value-set modeling instead of hardcoding or duplicating that logic here — this skill owns the source-control lifecycle, the Variable Library skill owns the parameterization it feeds.