Add Pixies with Git

BI Pixie can add Pixies to your target reports in three ways, and this article covers the second one, Git:

1. Manually or externally: You bring your reports and semantic models to a local folder, and then you run BI Pixie Desktop (bi-pixie.exe) on that target folder, as described in Add Pixies to your reports.
2. Using Git: You connect BI Pixie Desktop to your Git or GitHub repository. BI Pixie Desktop pulls the definitions of your reports and semantic models, and can commit and push the reports with Pixies to the repository and to the Power BI workspaces that are connected to Git.
3. Via Microsoft Fabric API: You tell BI Pixie which workspaces and reports to use. BI Pixie loads the definitions of the reports and semantic models with the Get Item Definition API and stores the files locally. BI Pixie then adds Pixies to the reports and semantic models and updates their definitions in their workspaces, as described in Add Pixies with the Fabric API.

BI Pixie fits into your existing report deployment process. If you already use Git in Azure DevOps or GitHub as the source control for your reports, you no longer need to bring Power BI project files to BI Pixie Desktop by hand or with external scripts, and you no longer need to publish the reports with Pixies back to the Power BI service by hand.

In this article, you connect BI Pixie to your Git repository, so that adding Pixies becomes part of your application lifecycle management or CI/CD process.

Once you set up BI Pixie Desktop for Git, BI Pixie can do the following:

1. Pull the definition files of your reports and semantic models from your Git or GitHub repository.
2. Commit the definitions with Pixies and push them back to your repository.
3. If your repository is connected to Power BI workspaces, send an update request, so that the workspaces fetch the changes from your Git or GitHub repository.

To pull the definitions without committing any change, you leave git_commit_changes and git_sync_changes_to_workspaces set to false. The reports with Pixies are then available in the local Git folder, and you can import the files by hand or with external scripts. To commit and push the changes to the repository without updating the workspaces, you set git_commit_changes to true and leave git_sync_changes_to_workspaces set to false.

BI Pixie works with Git in two modes:

1. Workspace Git integration: You use the Git integration of Power BI and Fabric workspaces, as Microsoft describes in Get started with Git integration. In this mode, you can connect a Git repository in Azure DevOps, GitHub or GitHub Enterprise to several workspaces in Power BI.
2. Git only, without syncing the workspaces: You use Git outside the workspace integration, and the Power BI reports in your Git repository are stored as Power BI project files.

The following table summarizes what BI Pixie can do with Git in each mode:

To add Pixies through Git, install Git for Windows on the computer where 'bi-pixie.exe' runs. You don't need to bring Power BI project files to the target folder, because BI Pixie does it for you.

The first time you run 'bi-pixie.exe' from a target folder, it creates the configuration file 'bi_pixie_config.json'. You then add the required fields, as described in Add Pixies to your reports:

• project_name
• subscription_email
• license_key
• pixies_flow_endpoint_url

If your Git repository groups several reports in folders, you set the use_report_folder_as_project field to true.

"use_report_folder_as_project": true,

With use_report_folder_as_project set, BI Pixie uses the folder name of each report as the project field in every event it collects from that report.

If you name each Git folder after its workspace, BI Pixie reports the actual workspaces in the collected events.

To turn on the Git integration, you set "git_enabled" to true in the "git_settings" section, as shown in the following example:

"git_settings" : {
  "git_enabled": true,
  ...
},

You enter the URL of your Git repository as the value of "git_url", as shown in the following example.

"git_settings" : {
  "git_enabled": true,
  "git_url": "https://...",
  ...
},

If you use Git in Azure DevOps, the Git URL has the following format:

"https://[your-domain].visualstudio.com/[project]/_git/[Repository name]"

If you use GitHub, the URL has the following format:

"https://github.com/[Username]/[Repository].git"

You enter the username of your Git repository or your GitHub account name in the "git_username" field, and the password of your Git repository or the personal access token of your GitHub account in the "git_password_or_key" field.

"git_settings" : {
  "git_enabled": true,
  "git_url": "https://...",
  "git_username": "[Git username]",
  "git_password_or_key": "[Git password or Github personal access token]"
  ...
},

If you don't want BI Pixie to commit the changes, you can leave the rest of the fields as they are.

When you run bi-pixie.exe, it creates the folder 'BI Pixie Repository' under the target folder and clones your Git repository there. Later runs of bi-pixie.exe pull the files from the repository into that folder.

When BI Pixie Desktop finishes its run, the files carry Pixies. You can review the changes and commit them by hand.

To have BI Pixie Desktop commit and push the reports with Pixies, you set "git_commit_changes" to true under "git_settings". By default the commit message is "BI Pixie instrumentation". To use a different message, you enter it in the "git_commit_message" field.

With commits turned on, the git_settings section looks like this:

"git_settings" : {
  "git_enabled": true,
  "git_url": "https://...",
  "git_username": "[Git username]",
  "git_password_or_key": "[Git password or Github personal access token]"
  "git_commit_changes": true,
  "git_commit_message": "BI Pixie instrumentation",
  "git_sync_changes_to_workspaces": false
},

If your Power BI or Fabric workspaces are connected to Git through the workspace Git integration, BI Pixie can also sync the committed changes back to the workspaces.

To sync the changes to the workspaces, BI Pixie needs to know which Git folder belongs to which workspace, so you name each workspace's Git folder after the workspace.

BI Pixie syncs the changes with the Microsoft Update From Git API, which requires a signed-in user. To give BI Pixie that user, you install Azure CLI for Windows on the machine where you run 'bi-pixie.exe', and a Power BI administrator signs in with "az login".

To turn on the workspace sync, you set "git_sync_changes_to_workspaces" to true in "git_settings", and "use_report_folder_as_project" to true.

"use_report_folder_as_project": true,
"git_settings" : {
  "git_enabled": true,
  "git_url": "https://...",
  "git_username": "[Git username]",
  "git_password_or_key": "[Git password or Github personal access token]"
  "git_commit_changes": true,
  "git_commit_message": "BI Pixie instrumentation",
  "git_sync_changes_to_workspaces": true
},

What's Next

Add Pixies with the Fabric API

Collect user feedback