Implementing Power BI Deployment Pipelines with Git Integration and Azure DevOps for Automated CI/CD of Enterprise Reports

Introduction

Picture this: your analytics team just spent three weeks building a critical sales performance report. The stakeholder signs off, you manually publish it to the Production workspace, and two days later a developer accidentally overwrites the semantic model with a half-finished experimental version. No version history, no rollback, no audit trail. The stakeholder is furious, the data is wrong, and you're rebuilding from memory.

This is the story of almost every Power BI team that hasn't implemented a proper CI/CD pipeline. The tools to fix this problem exist right now — Power BI's native Deployment Pipelines, Git integration, Azure DevOps, and the Power BI REST API — but they require you to wire them together deliberately. Out of the box, none of these systems talk to each other automatically. That's what this lesson is for.

By the end of this lesson, you will have built a complete, production-grade CI/CD workflow that automatically validates, stages, and deploys Power BI reports through Development, Test, and Production environments whenever a developer pushes changes to a Git branch. You'll understand not just the mechanics but the why behind each architectural decision, so you can adapt the pattern to your organization's specific governance requirements.

What you'll learn:

• How to connect a Power BI workspace to an Azure DevOps Git repository and manage the .pbip file format
• How to configure Power BI Deployment Pipelines programmatically via the REST API
• How to write an Azure DevOps YAML pipeline that triggers on pull requests and deploys through environments
• How to implement deployment rules to manage connection strings and parameter changes across environments
• How to handle semantic model refresh orchestration as part of the deployment process

---

Prerequisites

Before diving in, you'll need:

• A Power BI Premium capacity or Fabric capacity workspace (Deployment Pipelines require Premium Per User at minimum)
• An Azure DevOps organization with a project where you have Project Administrator rights
• A Service Principal in Azure Active Directory with the Power BI API permissions: Pipeline.ReadWrite.All, Workspace.ReadWrite.All, Dataset.ReadWrite.All
• Power BI Desktop installed, with the Power BI Project (.pbip) format enabled (File > Options > Preview Features > Power BI Project format)
• Familiarity with YAML, basic Git branching strategies, and the concept of Power BI workspaces

If you haven't worked with Service Principals for Power BI before, the short version is: you create an App Registration in Azure AD, grant it Power BI API permissions, add it as a workspace Admin, and use its client ID and secret to authenticate against the REST API. We'll reference this pattern repeatedly.

---

Understanding the Architecture Before You Build It

Before touching a single setting, you need to understand what you're building and why these components are arranged the way they are.

The full CI/CD architecture consists of four layers:

Layer 1 — Source Control (Azure DevOps Git): Your .pbip files live here. Every change to a report or semantic model is a Git commit. Pull requests trigger pipeline validation. The main branch represents what's been promoted to Production.

Layer 2 — Power BI Git Integration: Power BI workspaces can be synced directly to an Azure DevOps repo. When a developer commits a change to the feature/sales-ytd-fix branch, Power BI Desktop pushes .pbip files to Git. The Dev workspace reads from a connected branch.

Layer 3 — Power BI Deployment Pipelines: Three linked workspaces — Dev, Test, Production — managed by Power BI's built-in promotion engine. Deployment Pipelines understand Power BI artifacts natively and handle the complexity of promoting reports, semantic models, and dataflows without you manually re-binding connections.

Layer 4 — Azure DevOps Pipeline (YAML): This is the orchestration layer. It listens to Git events (PR opened, PR merged), calls the Power BI REST API to trigger deployments, applies deployment rules, kicks off semantic model refreshes, and handles approvals before Production deployment.

The key insight is that Power BI Deployment Pipelines and Azure DevOps YAML pipelines are complementary, not competing. Power BI Deployment Pipelines handle the artifact-level promotion logic (they know about report-to-model bindings, deployment rules, etc.). Azure DevOps handles the workflow logic (branching strategy, approvals, notifications, test gates).

---

Setting Up the `.pbip` Format and Repository Structure

Why `.pbip` Instead of `.pbix`

The .pbix format is a binary blob. You can't diff it in Git, you can't review changes in a pull request, and merge conflicts are unresolvable without specialized tools. The .pbip format, introduced as part of Microsoft Fabric's developer mode, stores your report and semantic model as a folder of JSON and TMDL files. This makes every DAX measure change, every visual property, every table relationship reviewable in a standard code review.

When you save a file in .pbip format, you get a folder structure like this:

/SalesPerformance.Report/
  definition/
    pages/
      ReportSection1/
        visuals/
          ...
    bookmarks/
    ...
  .pbi/
    localSettings.json

/SalesPerformance.SemanticModel/
  definition/
    tables/
      Sales/
        measures.tmdl
        columns.tmdl
      DimDate/
        ...
    relationships.tmdl
    model.tmdl
  .pbi/
    localSettings.json

The localSettings.json file contains developer-specific settings (like your local connection string). This file must be in .gitignore — it is never committed.

Repository Structure

Create your Azure DevOps repository with this structure from the start:

/
├── .gitignore
├── README.md
├── deployment/
│   ├── pipelines/
│   │   ├── pr-validation.yml
│   │   ├── deploy-dev.yml
│   │   ├── deploy-test.yml
│   │   └── deploy-production.yml
│   ├── scripts/
│   │   ├── deploy-pipeline.ps1
│   │   ├── apply-deployment-rules.ps1
│   │   ├── trigger-refresh.ps1
│   │   └── get-pipeline-status.ps1
│   └── config/
│       ├── dev-deployment-rules.json
│       ├── test-deployment-rules.json
│       └── prod-deployment-rules.json
├── SalesPerformance.Report/
├── SalesPerformance.SemanticModel/
├── FinanceOverview.Report/
└── FinanceOverview.SemanticModel/

Your .gitignore must include:

# Power BI local settings — never commit these
**/.pbi/localSettings.json

# Desktop autosave files
*.pbix.autosave

# Temp files
*.tmp
*.log

Warning: If localSettings.json gets committed even once, you'll need to purge it from Git history using git filter-branch or BFG Repo Cleaner. It can contain local data source credentials. Add the .gitignore before your first commit.

---

Connecting Power BI Workspaces to Git

Creating the Three Workspaces

Navigate to your Power BI service (app.powerbi.com) and create three workspaces. Use a consistent naming convention that signals environment clearly:

• Analytics - Sales [DEV]
• Analytics - Sales [TEST]
• Analytics - Sales [PROD]

Each workspace needs a Premium Per User, Premium, or Fabric capacity assigned. Without capacity, the Git integration and Deployment Pipeline features simply won't appear in the workspace settings.

Add your Service Principal as an Admin on all three workspaces. This is what allows the Azure DevOps pipeline to call the REST API on behalf of automation. You add a Service Principal to a workspace the same way you add a user — in Workspace Settings, under the Access tab, paste the Service Principal's Application ID.

Connecting the Dev Workspace to Git

In the Analytics - Sales [DEV] workspace, navigate to Workspace Settings, then the Git Integration tab. Connect to your Azure DevOps organization, select the repository you created, and set the branch to dev. Choose the folder where your Power BI files live — if you followed the structure above, this is the repository root /.

When you click Connect, Power BI will read the current state of the dev branch and show you an initial sync screen. If the workspace is empty and the branch has your .pbip files, it will import them. If the workspace already has content, it will show you a comparison and let you choose direction.

Tip: For a greenfield project, always push your .pbip files to the branch first, then connect the workspace. Going the other direction (connecting an existing workspace and letting it push to Git) works, but the initial commit is large and unstructured.

The Branching Strategy

For Power BI CI/CD, a simplified GitFlow works well:

• main — represents Production. Protected branch, no direct commits.
• dev — the integration branch. The Dev workspace is connected to this branch.
• feature/* — developer branches. Developers create feature branches from dev, make changes in Power BI Desktop, commit their .pbip files, and open a PR back to dev.

When a developer wants to make changes, they:

1. Pull the latest dev branch
2. Create a new branch: git checkout -b feature/add-regional-breakdown
3. Open the .pbip file in Power BI Desktop
4. Make changes and save
5. Commit the changed .pbip files: git commit -m "feat: add regional breakdown by territory"
6. Push and open a PR to dev

The Azure DevOps pipeline triggers on that PR, validates the changes, and if approved, merges to dev, which automatically syncs to the Dev workspace.

---

Configuring Power BI Deployment Pipelines

Creating the Pipeline via REST API

You could create the Deployment Pipeline manually in the UI, but doing it via REST API means you can recreate it from scratch if needed, document it in code, and integrate it with your infrastructure-as-code practices.

Here's the PowerShell script to create the pipeline and assign your three workspaces:

# deployment/scripts/create-deployment-pipeline.ps1

param(
    [string]$TenantId,
    [string]$ClientId,
    [string]$ClientSecret,
    [string]$PipelineName = "Sales Analytics Pipeline",
    [string]$DevWorkspaceId,
    [string]$TestWorkspaceId,
    [string]$ProdWorkspaceId
)

# Authenticate as Service Principal
$tokenUrl = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$tokenBody = @{
    grant_type    = "client_credentials"
    client_id     = $ClientId
    client_secret = $ClientSecret
    scope         = "https://analysis.windows.net/powerbi/api/.default"
}

$tokenResponse = Invoke-RestMethod -Uri $tokenUrl -Method POST -Body $tokenBody
$accessToken = $tokenResponse.access_token

$headers = @{
    Authorization  = "Bearer $accessToken"
    "Content-Type" = "application/json"
}

# Create the deployment pipeline
$createPipelineBody = @{
    displayName = $PipelineName
    description = "CI/CD pipeline for Sales Analytics reports"
} | ConvertTo-Json

$pipeline = Invoke-RestMethod `
    -Uri "https://api.powerbi.com/v1.0/myorg/pipelines" `
    -Method POST `
    -Headers $headers `
    -Body $createPipelineBody

$pipelineId = $pipeline.id
Write-Host "Created pipeline with ID: $pipelineId"

# Assign workspaces to stages
# Stage 0 = Development, Stage 1 = Test, Stage 2 = Production
$stages = @(
    @{ stageOrder = 0; workspaceId = $DevWorkspaceId },
    @{ stageOrder = 1; workspaceId = $TestWorkspaceId },
    @{ stageOrder = 2; workspaceId = $ProdWorkspaceId }
)

foreach ($stage in $stages) {
    $assignBody = @{
        workspaceId = $stage.workspaceId
    } | ConvertTo-Json

    Invoke-RestMethod `
        -Uri "https://api.powerbi.com/v1.0/myorg/pipelines/$pipelineId/stages/$($stage.stageOrder)/assignWorkspace" `
        -Method POST `
        -Headers $headers `
        -Body $assignBody

    Write-Host "Assigned workspace to stage $($stage.stageOrder)"
}

# Output the pipeline ID for use in subsequent scripts
Write-Output $pipelineId

Run this once to provision your pipeline infrastructure. Store the resulting pipeline ID as a variable in your Azure DevOps Variable Group (more on that shortly).

Configuring Deployment Rules

Deployment rules are how you tell Power BI: "when you promote this semantic model to Test, replace the connection string with the Test SQL Server, not the Dev one." Without deployment rules, you'd be pointing your Production reports at Development databases.

Create the deployment rules configuration file:

// deployment/config/prod-deployment-rules.json
{
  "rules": [
    {
      "id": "SalesPerformance_DataSource_Rule",
      "ruleType": "DataSourceRule",
      "objectId": "SalesPerformance.SemanticModel",
      "targetRuleConfiguration": {
        "datasourceSelector": {
          "datasourceType": "Sql",
          "connectionDetails": {
            "server": "dev-sqlserver.database.windows.net",
            "database": "SalesDB_Dev"
          }
        },
        "targetDatasourceConfiguration": {
          "connectionDetails": {
            "server": "prod-sqlserver.database.windows.net",
            "database": "SalesDB_Prod"
          }
        }
      }
    },
    {
      "id": "SalesPerformance_Parameter_DateRange",
      "ruleType": "ParameterRule",
      "objectId": "SalesPerformance.SemanticModel",
      "targetRuleConfiguration": {
        "name": "HistoricalDataYears",
        "newValue": "3"
      }
    }
  ]
}

The PowerShell script to apply these rules before a deployment:

# deployment/scripts/apply-deployment-rules.ps1

param(
    [string]$AccessToken,
    [string]$PipelineId,
    [int]$TargetStage,        # 1 for Test, 2 for Production
    [string]$RulesConfigPath
)

$headers = @{
    Authorization  = "Bearer $AccessToken"
    "Content-Type" = "application/json"
}

$rules = Get-Content $RulesConfigPath | ConvertFrom-Json

foreach ($rule in $rules.rules) {
    $ruleBody = @{
        type                      = $rule.ruleType
        targetRuleConfiguration   = $rule.targetRuleConfiguration
    } | ConvertTo-Json -Depth 10

    # Get artifacts in the stage to find the right dataset ID
    $stageArtifacts = Invoke-RestMethod `
        -Uri "https://api.powerbi.com/v1.0/myorg/pipelines/$PipelineId/stages/$TargetStage/artifacts" `
        -Method GET `
        -Headers $headers

    # Find the semantic model by display name
    $semanticModel = $stageArtifacts.datasets | 
        Where-Object { $_.displayName -eq $rule.objectId.Replace(".SemanticModel", "") }

    if ($null -eq $semanticModel) {
        Write-Warning "Semantic model not found for rule: $($rule.id). Skipping."
        continue
    }

    Write-Host "Applying rule '$($rule.id)' to semantic model '$($semanticModel.displayName)'"
    
    Invoke-RestMethod `
        -Uri "https://api.powerbi.com/v1.0/myorg/pipelines/$PipelineId/stages/$TargetStage/datasets/$($semanticModel.artifactId)/deploymentRules" `
        -Method POST `
        -Headers $headers `
        -Body $ruleBody
}

Tip: Deployment rules are applied per-stage and persist until changed. You only need to run apply-deployment-rules.ps1 when the rules themselves change, not on every deployment. However, it's safe (and good practice) to apply them idempotently on every run.

---

Writing the Azure DevOps YAML Pipelines

This is where everything comes together. You'll write four YAML pipeline definitions: one for PR validation, and one each for Dev, Test, and Production deployment.

The Core Deploy Script

First, the reusable PowerShell deployment function that all pipelines will call:

# deployment/scripts/deploy-pipeline.ps1

param(
    [string]$TenantId,
    [string]$ClientId,
    [string]$ClientSecret,
    [string]$PipelineId,
    [int]$SourceStage,
    [int]$TargetStage,
    [string]$DeploymentNote = "Automated deployment via Azure DevOps"
)

# Authenticate
$tokenBody = @{
    grant_type    = "client_credentials"
    client_id     = $ClientId
    client_secret = $ClientSecret
    scope         = "https://analysis.windows.net/powerbi/api/.default"
}

$tokenResponse = Invoke-RestMethod `
    -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" `
    -Method POST `
    -Body $tokenBody

$accessToken = $tokenResponse.access_token
$headers = @{
    Authorization  = "Bearer $accessToken"
    "Content-Type" = "application/json"
}

# Get all artifacts in the source stage
$artifacts = Invoke-RestMethod `
    -Uri "https://api.powerbi.com/v1.0/myorg/pipelines/$PipelineId/stages/$SourceStage/artifacts" `
    -Method GET `
    -Headers $headers

# Build deploy request with all reports and datasets
$deployItems = @()

foreach ($dataset in $artifacts.datasets) {
    $deployItems += @{
        type       = "Dataset"
        sourceId   = $dataset.artifactId
    }
}

foreach ($report in $artifacts.reports) {
    $deployItems += @{
        type       = "Report"
        sourceId   = $report.artifactId
    }
}

$deployBody = @{
    sourceStageOrder = $SourceStage
    targetStageOrder = $TargetStage
    items            = $deployItems
    options          = @{
        allowOverwriteArtifact        = $true
        allowCreateArtifact           = $true
        allowOverwriteTargetWorkspace = $false
        allowSkipTilesWithMissingPrerequisites = $false
    }
    note             = $DeploymentNote
} | ConvertTo-Json -Depth 5

Write-Host "Starting deployment from stage $SourceStage to stage $TargetStage..."

$deployResponse = Invoke-RestMethod `
    -Uri "https://api.powerbi.com/v1.0/myorg/pipelines/$PipelineId/deploy" `
    -Method POST `
    -Headers $headers `
    -Body $deployBody

$operationId = $deployResponse.id
Write-Host "Deployment operation started. Operation ID: $operationId"

# Poll for completion
$maxWaitSeconds = 300
$elapsed = 0
$pollInterval = 10

do {
    Start-Sleep -Seconds $pollInterval
    $elapsed += $pollInterval

    $status = Invoke-RestMethod `
        -Uri "https://api.powerbi.com/v1.0/myorg/pipelines/$PipelineId/operations/$operationId" `
        -Method GET `
        -Headers $headers

    Write-Host "Status: $($status.status) — elapsed: ${elapsed}s"

    if ($status.status -eq "Failed") {
        Write-Error "Deployment failed: $($status.error.message)"
        exit 1
    }

} while ($status.status -ne "Succeeded" -and $elapsed -lt $maxWaitSeconds)

if ($elapsed -ge $maxWaitSeconds) {
    Write-Error "Deployment timed out after $maxWaitSeconds seconds"
    exit 1
}

Write-Host "Deployment completed successfully."
Write-Output $accessToken  # Pass token to subsequent steps

The PR Validation Pipeline

# deployment/pipelines/pr-validation.yml

trigger: none

pr:
  branches:
    include:
      - dev
      - main
  paths:
    include:
      - "*.Report/**"
      - "*.SemanticModel/**"

pool:
  vmImage: "windows-latest"

variables:
  - group: "PowerBI-Service-Principal"  # Contains TenantId, ClientId, ClientSecret

steps:
  - checkout: self

  - task: PowerShell@2
    displayName: "Validate .pbip file structure"
    inputs:
      targetType: "inline"
      script: |
        $errors = @()
        
        # Find all semantic model folders
        $semanticModels = Get-ChildItem -Path "$(Build.SourcesDirectory)" `
            -Filter "*.SemanticModel" -Directory
        
        foreach ($model in $semanticModels) {
            $modelFile = Join-Path $model.FullName "definition\model.tmdl"
            if (-not (Test-Path $modelFile)) {
                $errors += "Missing model.tmdl in $($model.Name)"
            }
            
            # Check for accidentally committed localSettings
            $localSettings = Join-Path $model.FullName ".pbi\localSettings.json"
            if (Test-Path $localSettings) {
                $errors += "SECURITY: localSettings.json committed in $($model.Name)"
            }
        }
        
        # Find all report folders
        $reports = Get-ChildItem -Path "$(Build.SourcesDirectory)" `
            -Filter "*.Report" -Directory
        
        foreach ($report in $reports) {
            $reportFile = Join-Path $report.FullName "definition"
            if (-not (Test-Path $reportFile)) {
                $errors += "Missing definition folder in $($report.Name)"
            }
        }
        
        if ($errors.Count -gt 0) {
            foreach ($error in $errors) {
                Write-Error $error
            }
            exit 1
        }
        
        Write-Host "✓ All .pbip file structures validated successfully"

  - task: PowerShell@2
    displayName: "Validate TMDL syntax (measure expressions)"
    inputs:
      targetType: "inline"
      script: |
        # Parse TMDL measure files for obvious syntax issues
        $measureFiles = Get-ChildItem -Path "$(Build.SourcesDirectory)" `
            -Filter "measures.tmdl" -Recurse
        
        $errors = @()
        foreach ($file in $measureFiles) {
            $content = Get-Content $file.FullName -Raw
            
            # Check for unclosed parentheses (common DAX error)
            $openParens = ([regex]::Matches($content, '\(')).Count
            $closeParens = ([regex]::Matches($content, '\)')).Count
            
            if ($openParens -ne $closeParens) {
                $errors += "Unbalanced parentheses in: $($file.FullName)"
            }
        }
        
        if ($errors.Count -gt 0) {
            $errors | ForEach-Object { Write-Error $_ }
            exit 1
        }
        
        Write-Host "✓ TMDL syntax validation passed"

The Main Deployment Pipeline

# deployment/pipelines/deploy-production.yml

trigger:
  branches:
    include:
      - main
  paths:
    include:
      - "*.Report/**"
      - "*.SemanticModel/**"

pool:
  vmImage: "windows-latest"

variables:
  - group: "PowerBI-Service-Principal"
  - group: "PowerBI-Pipeline-Config"  # Contains PipelineId, workspace IDs

stages:
  - stage: DeployToTest
    displayName: "Deploy to Test Environment"
    jobs:
      - job: DeployTest
        displayName: "Promote Dev → Test"
        steps:
          - checkout: self

          - task: PowerShell@2
            displayName: "Apply Test deployment rules"
            inputs:
              filePath: "deployment/scripts/apply-deployment-rules.ps1"
              arguments: >
                -TenantId "$(TenantId)"
                -ClientId "$(ClientId)"
                -ClientSecret "$(ClientSecret)"
                -PipelineId "$(PipelineId)"
                -TargetStage 1
                -RulesConfigPath "deployment/config/test-deployment-rules.json"

          - task: PowerShell@2
            displayName: "Deploy Dev to Test"
            name: deployToTest
            inputs:
              filePath: "deployment/scripts/deploy-pipeline.ps1"
              arguments: >
                -TenantId "$(TenantId)"
                -ClientId "$(ClientId)"
                -ClientSecret "$(ClientSecret)"
                -PipelineId "$(PipelineId)"
                -SourceStage 0
                -TargetStage 1
                -DeploymentNote "Automated deploy — commit $(Build.SourceVersion)"

          - task: PowerShell@2
            displayName: "Trigger semantic model refresh in Test"
            inputs:
              filePath: "deployment/scripts/trigger-refresh.ps1"
              arguments: >
                -TenantId "$(TenantId)"
                -ClientId "$(ClientId)"
                -ClientSecret "$(ClientSecret)"
                -WorkspaceId "$(TestWorkspaceId)"
                -WaitForCompletion $true

  - stage: DeployToProduction
    displayName: "Deploy to Production"
    dependsOn: DeployToTest
    jobs:
      - deployment: DeployProd
        displayName: "Promote Test → Production"
        environment: "PowerBI-Production"  # This environment has approval gates
        strategy:
          runOnce:
            deploy:
              steps:
                - checkout: self

                - task: PowerShell@2
                  displayName: "Apply Production deployment rules"
                  inputs:
                    filePath: "deployment/scripts/apply-deployment-rules.ps1"
                    arguments: >
                      -TenantId "$(TenantId)"
                      -ClientId "$(ClientId)"
                      -ClientSecret "$(ClientSecret)"
                      -PipelineId "$(PipelineId)"
                      -TargetStage 2
                      -RulesConfigPath "deployment/config/prod-deployment-rules.json"

                - task: PowerShell@2
                  displayName: "Deploy Test to Production"
                  inputs:
                    filePath: "deployment/scripts/deploy-pipeline.ps1"
                    arguments: >
                      -TenantId "$(TenantId)"
                      -ClientId "$(ClientId)"
                      -ClientSecret "$(ClientSecret)"
                      -PipelineId "$(PipelineId)"
                      -SourceStage 1
                      -TargetStage 2
                      -DeploymentNote "Production release — PR #$(System.PullRequest.PullRequestNumber)"

                - task: PowerShell@2
                  displayName: "Trigger semantic model refresh in Production"
                  inputs:
                    filePath: "deployment/scripts/trigger-refresh.ps1"
                    arguments: >
                      -TenantId "$(TenantId)"
                      -ClientId "$(ClientId)"
                      -ClientSecret "$(ClientSecret)"
                      -WorkspaceId "$(ProdWorkspaceId)"
                      -WaitForCompletion $true

The environment: "PowerBI-Production" declaration in the Production deployment stage is the key to requiring human approval. In Azure DevOps, navigate to Pipelines > Environments, create an environment named PowerBI-Production, and add an Approval check. Now every deployment to Production will pause and wait for a named approver before executing.

The Semantic Model Refresh Script

Deployment doesn't automatically refresh data. After promoting a semantic model, you need to trigger a refresh — especially for Test and Production where stakeholders expect current data:

# deployment/scripts/trigger-refresh.ps1

param(
    [string]$TenantId,
    [string]$ClientId,
    [string]$ClientSecret,
    [string]$WorkspaceId,
    [bool]$WaitForCompletion = $true,
    [int]$TimeoutMinutes = 60
)

$tokenBody = @{
    grant_type    = "client_credentials"
    client_id     = $ClientId
    client_secret = $ClientSecret
    scope         = "https://analysis.windows.net/powerbi/api/.default"
}

$tokenResponse = Invoke-RestMethod `
    -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" `
    -Method POST -Body $tokenBody

$headers = @{
    Authorization  = "Bearer $($tokenResponse.access_token)"
    "Content-Type" = "application/json"
}

# Get all datasets in the workspace
$datasets = Invoke-RestMethod `
    -Uri "https://api.powerbi.com/v1.0/myorg/groups/$WorkspaceId/datasets" `
    -Method GET -Headers $headers

foreach ($dataset in $datasets.value) {
    # Skip DirectQuery-only datasets (no refresh needed)
    if ($dataset.isRefreshable -eq $false) {
        Write-Host "Skipping non-refreshable dataset: $($dataset.name)"
        continue
    }

    Write-Host "Triggering refresh for: $($dataset.name)"

    $refreshBody = @{
        notifyOption = "NoNotification"
    } | ConvertTo-Json

    Invoke-RestMethod `
        -Uri "https://api.powerbi.com/v1.0/myorg/groups/$WorkspaceId/datasets/$($dataset.id)/refreshes" `
        -Method POST -Headers $headers -Body $refreshBody

    if ($WaitForCompletion) {
        $timeout = [DateTime]::Now.AddMinutes($TimeoutMinutes)
        
        do {
            Start-Sleep -Seconds 30
            
            $refreshHistory = Invoke-RestMethod `
                -Uri "https://api.powerbi.com/v1.0/myorg/groups/$WorkspaceId/datasets/$($dataset.id)/refreshes" `
                -Method GET -Headers $headers
            
            $latestRefresh = $refreshHistory.value | Select-Object -First 1
            Write-Host "Refresh status for '$($dataset.name)': $($latestRefresh.status)"
            
            if ($latestRefresh.status -eq "Failed") {
                Write-Error "Refresh failed for '$($dataset.name)': $($latestRefresh.serviceExceptionJson)"
                exit 1
            }
            
        } while ($latestRefresh.status -eq "Unknown" -and [DateTime]::Now -lt $timeout)
        
        if ([DateTime]::Now -ge $timeout) {
            Write-Warning "Refresh timed out for '$($dataset.name)' — continuing pipeline"
        }
    }
}

---

Hands-On Exercise: Wire Up a Complete Pipeline Run

You've read the theory. Now let's walk through a complete deployment scenario from a developer's first commit to a Production release.

Scenario: A data analyst named Priya has added a new "Year-over-Year Growth %" measure to the Sales Performance semantic model and wants to deploy it to Production.

Step 1: Priya creates a feature branch

git checkout dev
git pull origin dev
git checkout -b feature/yoy-growth-measure

Step 2: Priya makes changes in Power BI Desktop She opens SalesPerformance.SemanticModel in Desktop, adds the measure to the Sales table, and saves. The measures.tmdl file for the Sales table now contains her new DAX:

measure 'YoY Growth %' = 
    VAR CurrentYear = [Total Sales]
    VAR PriorYear = CALCULATE([Total Sales], SAMEPERIODLASTYEAR('DimDate'[Date]))
    RETURN
        DIVIDE(CurrentYear - PriorYear, PriorYear, BLANK())
    formatString: "0.0%"

Step 3: Priya commits and pushes

git add SalesPerformance.SemanticModel/
git commit -m "feat: add YoY Growth % measure to Sales table"
git push origin feature/yoy-growth-measure

Step 4: PR validation runs automatically Priya opens a Pull Request from feature/yoy-growth-measure into dev in Azure DevOps. The pr-validation.yml pipeline triggers immediately. Within two minutes, she sees green checks: file structure validated, TMDL syntax passed.

Step 5: Reviewer examines the actual DAX change The reviewer opens the PR and sees, in plain diff format, exactly what changed in measures.tmdl. They can see the DAX formula, comment on it, and approve — just like reviewing any other code change.

Step 6: Merge to dev triggers Dev workspace sync After approval, the PR is merged to dev. Power BI's Git integration automatically syncs the Dev workspace within a few minutes. Priya can now verify her measure works correctly against Dev data.

Step 7: Merge to main triggers the full deployment pipeline When the team is ready to promote to higher environments, they open a PR from dev to main. After approval and merge, the deploy-production.yml pipeline triggers:

• Test deployment rules are applied (pointing to test SQL Server)
• Dev artifacts are promoted to the Test workspace
• Test semantic model refreshes with live data
• Pipeline pauses and sends approval notification to designated approvers
• After approval, Production deployment rules are applied
• Test artifacts are promoted to Production
• Production semantic model refreshes

The entire journey from code commit to Production is tracked, auditable, and reversible.

---

Common Mistakes and Troubleshooting

Mistake 1: Service Principal lacks the right permissions

The most common first-run failure. The REST API calls return 401 or 403 errors that look like authentication failures but are actually authorization failures.

Checklist: In the Azure AD App Registration, under API Permissions, ensure you have Power BI Service > Pipeline.ReadWrite.All, Workspace.ReadWrite.All, and Dataset.ReadWrite.All granted with Admin consent. Also verify the Service Principal is added as a workspace Admin (not Member) in each of the three workspaces. API permissions alone are not enough.

Mistake 2: Deployment rules not applying to the right artifact

If your rule references a semantic model by display name and that name contains spaces, special characters, or has been renamed, the Where-Object filter in apply-deployment-rules.ps1 will silently fail (return null) and skip the rule.

Fix: Switch to matching by artifact ID rather than display name. After your first deployment, log the artifact IDs and store them in your config file. IDs are stable across deployments.

Mistake 3: Git sync conflict between Desktop and the pipeline

If two developers both have the same workspace connected to their feature branches and both try to commit simultaneously, you can get a workspace sync conflict. The workspace only has one state.

Fix: The Dev workspace should only ever be connected to the dev branch, not feature branches. Individual developers work locally in Desktop and commit .pbip files to their feature branches. Only the merged dev branch state is reflected in the Dev workspace.

Mistake 4: localSettings.json gets committed

You'll know this happened when colleagues pull your branch and suddenly their Desktop is connecting to your local data source path.

Fix: Add a pre-commit hook to your repository:

# .git/hooks/pre-commit
#!/bin/sh
if git diff --cached --name-only | grep -q "localSettings.json"; then
    echo "ERROR: Attempted to commit localSettings.json"
    echo "Remove this file from staging: git reset HEAD **/localSettings.json"
    exit 1
fi

For team enforcement, add a .gitattributes rule and validate in the PR pipeline as shown in the pr-validation.yml above.

Mistake 5: Deployment polling times out for large semantic models

The default 300-second timeout in deploy-pipeline.ps1 is insufficient for semantic models with large numbers of tables or complex row-level security configurations.

Fix: Increase the timeout parameter and ensure your Azure DevOps pipeline step timeout is also configured appropriately (timeoutInMinutes at the job level). For very large models (>1GB), consider breaking the deployment into separate pipeline runs per model.

Mistake 6: Deployment fails because the target workspace is in use

Power BI will reject a deployment if someone is actively editing a report in the target workspace. This is especially common for the Test environment.

Fix: Implement a workspace lock check before deployment:

# Check if any user has the workspace open
$workspaceUsers = Invoke-RestMethod `
    -Uri "https://api.powerbi.com/v1.0/myorg/groups/$TargetWorkspaceId/users" `
    -Method GET -Headers $headers

Write-Host "Current workspace users: $($workspaceUsers.value.Count)"
Write-Warning "Ensure no one is actively editing in the Test workspace before proceeding."

You can't programmatically force users out, but you can add a notification step in the pipeline that posts to Teams or Slack before deployment begins.

---

Summary and Next Steps

You've built a production-grade CI/CD system for Power BI that treats your reports and semantic models with the same rigor as application code. Here's what the architecture gives you:

• Auditability: Every change is a Git commit. Every deployment is a logged pipeline run. You can answer "who changed that DAX measure on Thursday and when was it deployed?" with a thirty-second search.
• Safety: The Deployment Pipelines engine handles the complexity of cross-workspace artifact promotion. Azure DevOps environments with approval gates prevent accidental Production deployments.
• Developer experience: Reviewers can read actual DAX changes in PRs. Developers don't need to manually remember which workspace to publish to.
• Rollback: If a Production deployment breaks something, you can redeploy the previous Git tag through the same pipeline, with the same deployment rules applied consistently.

Where to go next:

• Add semantic model testing: Explore DAX Query View and tools like Tabular Editor's Best Practice Analyzer to add automated semantic model quality checks to your PR validation pipeline. These can catch modeling errors before they reach Production.

• Implement workspace-level RLS testing: Extend the pipeline to test row-level security rules by querying the deployed Test semantic model as specific security principals and validating the returned row counts.

• Add pipeline notifications: Integrate Azure DevOps Service Hooks to send Teams notifications with deployment status, including which reports changed and which approvers need to act.

• Explore Microsoft Fabric Git integration: If your organization is moving toward Microsoft Fabric, the Git integration features are deeper and the .pbip format is fully native. The deployment patterns in this lesson translate directly — the API endpoints and YAML patterns are nearly identical.

• Consider Terraform for workspace provisioning: The create-deployment-pipeline.ps1 script is a start, but for managing dozens of pipelines across multiple teams, Infrastructure as Code with the azurerm Terraform provider (or the powerbi community provider) gives you declarative, idempotent workspace and pipeline management.

The system you've built in this lesson is the foundation. The next level of maturity is making it smarter — auto-detecting which semantic models actually changed in a commit and only deploying those, rather than deploying everything on every run. That optimization alone can cut your average deployment time in half for large workspaces.