Automate Git integration by using APIs

Article
2025-04-01

The Microsoft Fabric Git integration tool enables teams to work together using source control to build an efficient and reusable release process for their Fabric content.

With Microsoft Fabric REST APIs, you can automate Fabric procedures and processes to complete tasks faster and with fewer errors. This efficiency leads to cost savings and improved productivity.

This article describes how to use the Git integration REST APIs to automate Git integration in Microsoft Fabric.

Prerequisites

To work with Fabric Git APIs, you need:

The same prerequisites you need to use Git integration in the UI.
A Microsoft Entra token for Fabric service. Use that token in the authorization header of the API call. For information about how to get a token, see Fabric API quickstart.
If you're using a GitHub service principal, it needs the same permissions as a user principal.

You can use the REST APIs without PowerShell, but the scripts in this article use PowerShell. To run the scripts, take the following steps:

Install PowerShell.
Install the Azure PowerShell Az module.

Git integration API functions

The Git integration REST APIs can help you achieve the continuous integration and continuous delivery (CI/CD) of your content. Here are a few examples of what can be done by using the APIs:

Connect and disconnect a specific workspace from the Git repository and branch connected to it. (Connect requires the connectionId of the Git provider credentials.)
Get connection details for the specified workspace.
Get or create Git provider credentials connection.
Update my Git credentials to update your Git credentials configuration details. Requires the connectionId of the Git provider credentials.
Get my Git credentials to get your Git credentials configuration details.
Initialize a connection for a workspace that is connected to Git.
See which items have incoming changes and which items have changes that weren't yet committed to Git with the Git status API.
Commit the changes made in the workspace to the connected remote branch.
Update the workspace with commits pushed to the connected branch.

Examples

Use the following PowerShell scripts to understand how to perform several common automation processes. To view or copy the text in a PowerShell sample, use the links in this section. You can also see all the examples in the Fabric Git integration samples GitHub repo.

Connect and update

This section describes the steps involved in connecting and updating a workspace with Git.

For the complete script, see Connect and update from Git.

Connect to Azure account and get access token - Sign in to Fabric as a user (or, if using GitHub, a user or a service principal). Use the Connect-AzAccount command to connect. To get an access token, use the Get-AzAccessToken command, and convert the secure string token to plain text

Your code should look something like this:

User principal
Service principal (GitHub only)

 $global:resourceUrl = "https://api.fabric.microsoft.com"

 $global:fabricHeaders = @{}

 function SetFabricHeaders() {

    #Login to Azure
    Connect-AzAccount | Out-Null

    # Get authentication
    $secureFabricToken = (Get-AzAccessToken -AsSecureString -ResourceUrl $global:resourceUrl).Token

    # Convert secure string to plain test
    $ssPtr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureFabricToken)
    try {
        $fabricToken = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($ssPtr)
    } finally {
        [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ssPtr)
   }

  $global:fabricHeaders = @{
     'Content-Type' = "application/json"
     'Authorization' = "Bearer {0}" -f $fabricToken
 }
}

$global:resourceUrl = "https://api.fabric.microsoft.com"
$global:fabricHeaders = @{}

function SetFabricHeaders() {

   $clientId = "<CLIENT ID>"
   $tenantId = "<TENANT ID>"
   $secret = "<SECRET VALUE>"

   $secureSecret  = ConvertTo-SecureString -String $secret -AsPlainText -Force
   $credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $clientId, $secureSecret

   #Login to Azure using service principal
   Connect-AzAccount -ServicePrincipal -TenantId $tenantId -Credential $credential | Out-Null

   # Get authentication
   $secureFabricToken = (Get-AzAccessToken -AsSecureString -ResourceUrl $global:resourceUrl).Token

   # Convert secure string to plain text
   $ssPtr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureFabricToken)
   try {
       $fabricToken = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($ssPtr)
   } finally {
      [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ssPtr)
   }

  $global:fabricHeaders = @{
     'Content-Type' = "application/json"
     'Authorization' = "Bearer {0}" -f $fabricToken
  }
}

Call the Connect API to connect the workspace to a Git repository and branch.

Azure DevOps (User principal)
GitHub (User or service principal)

$global:baseUrl = "https://api.fabric.microsoft.com/v1"
$workspaceName = "<WORKSPACE NAME>"
$getWorkspacesUrl = "{0}/workspaces" -f $global:baseUrl 
$workspaces = (Invoke-RestMethod -Headers $global:fabricHeaders -Uri $getWorkspacesUrl -Method GET).value

# Find the workspace by display name
$workspace = $workspaces | Where-Object {$_.DisplayName -eq $workspaceName}

# Connect to Git
Write-Host "Connecting the workspace '$workspaceName' to Git."

$connectUrl = "{0}/workspaces/{1}/git/connect" -f $global:baseUrl, $workspace.Id

# AzureDevOps details
$azureDevOpsDetails = @{
    gitProviderType = "AzureDevOps"
    organizationName = "<ORGANIZATION NAME>"
    projectName = "<PROJECT NAME>"
    repositoryName = "<REPOSITORY NAME>"
    branchName = "<BRANCH NAME>"
    directoryName = "<DIRECTORY NAME>"
}

$connectToGitBody = @{
    gitProviderDetails = $azureDevOpsDetails
} | ConvertTo-Json

Invoke-RestMethod -Headers $global:fabricHeaders -Uri $connectUrl -Method POST -Body $connectToGitBody

$global:baseUrl = "https://api.fabric.microsoft.com/v1"
$workspaceName = "<WORKSPACE NAME>"
$getWorkspacesUrl = "{0}/workspaces" -f $global:baseUrl 
$workspaces = (Invoke-RestMethod -Headers $global:fabricHeaders -Uri $getWorkspacesUrl -Method GET).value

# Find the workspace by display name
$workspace = $workspaces | Where-Object {$_.DisplayName -eq $workspaceName}

# Connect to Git
Write-Host "Connecting the workspace '$workspaceName' to Git."

$connectUrl = "{0}/workspaces/{1}/git/connect" -f $global:baseUrl, $workspace.Id

# GitHub details
$gitHubDetails = @{
    gitProviderType = "GitHub"
    ownerName = "<OWNER NAME>"
    repositoryName = "<REPOSITORY NAME>"
    branchName = "<BRANCH NAME>"
    directoryName = "<DIRECTORY NAME>"
}

$connectionName = "<CONNECTION Name>"

# Get connections 
$getConnectionsUrl = "$global:baseUrl/connections"
$connections = (Invoke-RestMethod -Headers $global:fabricHeaders -Uri $getConnectionsUrl -Method GET).value

# Find the connection by name
$connection = $connections | Where-Object {$_.DisplayName -eq $connectionName}

$connectToGitBody = @{
    gitProviderDetails = $gitHubDetails
    myGitCredentials = @{
        source = "ConfiguredConnection"
        connectionId = $connection.id
    }
} | ConvertTo-Json

Invoke-RestMethod -Headers $global:fabricHeaders -Uri $connectUrl -Method POST -Body $connectToGitBody

For information on how to obtain the Connection Id, refer to Get or create Git provider credentials connection.

Call the Initialize Connection API to initialize the connection between the workspace and the Git repository/branch.

# Initialize Connection

Write-Host "Initializing Git connection for workspace '$workspaceName'."

$initializeConnectionUrl = "{0}/workspaces/{1}/git/initializeConnection" -f $global:baseUrl, $workspace.Id
$initializeConnectionResponse = Invoke-RestMethod -Headers $global:fabricHeaders -Uri $initializeConnectionUrl -Method POST -Body "{}"

Based on the response from the Initialize Connection API, call either the Update From Git API to complete the update, or do nothing if no action required.

The following script updates and monitors the progress:

if ($initializeConnectionResponse.RequiredAction -eq "UpdateFromGit") {

    # Update from Git
    Write-Host "Updating the workspace '$workspaceName' from Git."

    $updateFromGitUrl = "{0}/workspaces/{1}/git/updateFromGit" -f $global:baseUrl, $workspace.Id

    $updateFromGitBody = @{ 
        remoteCommitHash = $initializeConnectionResponse.RemoteCommitHash
  workspaceHead = $initializeConnectionResponse.WorkspaceHead
    } | ConvertTo-Json

    $updateFromGitResponse = Invoke-WebRequest -Headers $global:fabricHeaders -Uri $updateFromGitUrl -Method POST -Body $updateFromGitBody

    $operationId = $updateFromGitResponse.Headers['x-ms-operation-id']
    $retryAfter = $updateFromGitResponse.Headers['Retry-After']
    Write-Host "Long Running Operation ID: '$operationId' has been scheduled for updating the workspace '$workspaceName' from Git with a retry-after time of '$retryAfter' seconds." -ForegroundColor Green

    # Poll Long Running Operation
    $getOperationState = "{0}/operations/{1}" -f $global:baseUrl, $operationId
    do
    {
        $operationState = Invoke-RestMethod -Headers $global:fabricHeaders -Uri $getOperationState -Method GET

        Write-Host "Update from Git operation status: $($operationState.Status)"

        if ($operationState.Status -in @("NotStarted", "Running")) {
            Start-Sleep -Seconds $retryAfter
        }
    } while($operationState.Status -in @("NotStarted", "Running"))
}

Update from Git

In this section, we describe the steps involved in updating a workspace with the changes from Git. In this script, we update the workspace items with changes from Git, but we leave the Git repository unchanged.

For the complete script, see Update workspace from Git.

Log into Git and get authentication.
Call the Get Status API to build the update from Git request body.
Call the Update From Git API to update the workspace with commits pushed to the connected branch.

Commit all

This section gives a step by step description of how to programmatically commit all changes from the workspace to Git.

For the complete script, see Commit all changes to Git.

Log into Git and get authentication.
Connect to workspace.
Call the Commit to Git REST API.
Get the Long Running OperationId for polling the status of the operation.

Selective Commit

This section describes the steps involved in committing only specific changes from the workspace to Git.

For the complete script, see Commit select changes to Git.

Log into Git and get authentication.
Connect to workspace.
Call the Get status API to see which items workspace were changed.
Select the specific items to commit.
Call the Commit to Git API to commit the selected changes from the workspace to the connected remote branch.

Monitor the progress of long running operations

For the complete script, see Poll a long running operation.

Retrieve the operationId from the Update From Git or the Commit to Git script.
Call the Get LRO Status API at specified intervals (in seconds) and print the status.

Get or create Git provider credentials connection

In order to connect to a Git repository or update your Git credentials you need to provide a connectionId. The connectionId can come from either a new connection that you create, or an existing connection.

Create a new connection with your Git provider credentials
Use an existing connection that you have permissions for.

Create a new connection that stores your GitHub credentials

Use your Personal Access Token (PAT) to create a GitHub connection.

If you provide the name of a specific repo, your connection is scoped to that repo. If you don't provide the name of any repo, you get access to all repos you have permission for.

To create a connection that stores your GitHub credentials, call the Create connection API with the following request body. The parameters section is optional and only needed if you want your connection scoped to a specific repo.

Sample request

POST https://api.fabric.microsoft.com/v1/connections

{
 "connectivityType": "ShareableCloud",
 "displayName": "MyGitHubPAT",
 "connectionDetails": {
  "type": "GitHubSourceControl",
  "creationMethod": "GitHubSourceControl.Contents",
  "parameters": [
   {
    "dataType": "Text",
    "name": "url",
    "value": "https://github.com/OrganizationName/RepositoryName"
   }
  ]
 },
 "credentialDetails": {
  "credentials": {
   "credentialType": "Key",
   "key": "*********"  //Enter your GitHub Personal Access Token
  }
 }
}

Sample response:

{
  "id": "3aba8f7f-d1ba-42b1-bb41-980029d5a1c1",
   "connectionDetails": {
       "path": "https://github.com/OrganizationName/RepositoryName",
       "type": "GitHubSourceControl"
   },
   "connectivityType": "ShareableCloud",
   "credentialDetails": {
       "connectionEncryption": "NotEncrypted",
       "credentialType": "Key",
       "singleSignOnType": "None",
       "skipTestConnection": false
   },
   "displayName": "MyGitHubPAT",
   "gatewayId": null,
   "privacyLevel": "Organizational"
}

Copy the ID and use it in the Git - Connect or Git - Update My Git Credentials API.

Get a list of existing connections

Use the List connections API to get a list of existing connections that you have permissions for, and their properties.

Sample request

GET https://api.fabric.microsoft.com/v1/connections

Sample response

{
 "value": [
  {
   "id": "e3607d15-6b41-4d11-b8f4-57cdcb19ffc8",
   "displayName": "MyGitHubPAT1",
   "gatewayId": null,
   "connectivityType": "ShareableCloud",
   "connectionDetails": {
    "path": "https://github.com",
    "type": "GitHubSourceControl"
   },
   "privacyLevel": "Organizational",
   "credentialDetails": {
    "credentialType": "Key",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
   }
  },
  {
   "id": "3aba8f7f-d1ba-42b1-bb41-980029d5a1c1",
   "displayName": "MyGitHubPAT2",
   "gatewayId": null,
   "connectivityType": "ShareableCloud",
   "connectionDetails": {
    "path": "https://github.com/OrganizationName/RepositoryName",
    "type": "GitHubSourceControl"
   },
   "privacyLevel": "Organizational",
   "credentialDetails": {
    "credentialType": "Key",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
   }
  }
 ]
}

Copy the ID of the connection you want and use it in the Git - Connect or Git - Update My Git Credentials API.

Considerations and limitations

Git integration using APIs is subject to the same limitations as the Git integration user interface.
Service principal is only supported for GitHub.
Refreshing a semantic model using the Enhanced refresh API causes a Git diff after each refresh.

Share via