CI/CD for org apps in Fabric

This article explains how Git integration and deployment pipelines work for org apps in Microsoft Fabric. Learn how to set up a connection to your repository, manage your org app through Git, and deploy it across different environments.

Org apps and Git integration

Connect to a Git repository

From your workspace settings, set up a connection to your repo to commit and sync changes. To set up the connection, see Get started with Git integration article.

After you connect, the workspace displays information about source control that allows you to view the connected branch, the status of each item in the branch, and the time of the last sync.

Org apps representation in Git

Each org app is a set of artifacts:

• Org App artifact controls the content and the appearance of the app.
• Org App audience (one or more) helps share different sets of app contents to users or groups.

When you commit the org app item to the Git repo, you create a folder for each item and name it {display name}.OrgApp. It contains two files and a subfolder:

• .platform file which is auto generated by the system. Learn more from system file.
• definition.json file which is the definition of the org app item.
• .children folder containing audience artifacts. Each artifact is stored in a subfolder named {display name}.OrgAppAudience. Each audience subfolder has a .platform and a definition.json file.

Org app artifact

The definition file is divided into two sections:

• Static settings: describe the app's external appearance, such as the theme, logo, and experience settings.
• Elements: describe the app's internal structure.
  • Section elements: Container elements that have their own collection of elements.
  • Item elements: Power BI items.

The following diagram shows the structure of the org app.

The definition file contains:

• settings
  • logo
  • theme
    • background
    • foreground
    • backgroundHover
    • backgroundSelected
    • backgroundPressed
  • experienceSettings
    • navigationPane
      • isHidden
      • isCollapsed
      • independentPageNavigation
  • itemTypeSettings
    • report
      • hidePagePane
  • audienceSettings
    • hideAudienceTabs
    • hideAllTab
• elements
  • elementType (can be: overview, section, item, or link)
  • elementId
  • itemType (only for elementType: item)
  • itemLogicalId (only for elementType: item)
  • isHidden (not for elementType: overview)
  • displayName
  • header (only for elementType: overview)
    • title
    • body
    • showTheme
  • elements (only for elementType: section)
  • url (only for elementType: link)
  • linkType (only for elementType: link. Values are embedded or newtab)

The following JSON code is an example of the definition.json file for an org app item:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/orgapp/definition/orgAppDefinition/2.0.0/schema.json",
  "settings": {
    "theme": {
      "background": "#2fb136",
      "foreground": "#000000",
      "backgroundHover": "#59c15e",
      "backgroundSelected": "#82d086",
      "backgroundPressed": "#ace0af"
    }
  },
  "elements": [
    {
      "elementType": "item",
      "elementId": "08e649a9-0fe6-40bd-b0c3-7fc900b7550f",
      "itemType": "Report",
      "itemLogicalId": "e0fa7df4-5528-4c37-bf2c-9ec02ffef18d",
      "isHidden": false,
      "displayName": "Daily Dashboard"
    },
    {
      "elementType": "item",
      "elementId": "410f87ee-8402-49b0-abbb-31cb69dc1ebc",
      "itemType": "SemanticModel",
      "itemLogicalId": "8f633535-6fb4-467f-a668-6bc55c5735b8",
      "isHidden": false,
      "displayName": "410f87ee-8402-49b0-abbb-31cb69dc1ebc"
    }
  ]
}

Org app audience artifact

The definition file is divided into three sections:

• Parent App reference: Must match the logicalId of the parent org app (under config/logicalId in the .platform file in the org app's folder).
• Static settings: Describe the audience's access to hidden content and location on the audience tab.
• Element references: The list of app contents shown by the audience
  • App item elements: Overview or link items.
  • Content Item elements: Power BI items.

The following diagram shows the structure of the org app.

The definition file contains:

• parentAppId
• settings
  • hasAccessToHiddenContent
  • tabOrder
• elementReferences
  • elementId
  • itemType (only for PowerBI items)
  • itemLogicalId (only for PowerBI items)

The following JSON code is an example of the definition.json file for an org app audience:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/orgappaudience/definition/orgAppAudienceDefinition/1.0.0/schema.json",
  "settings": {
    "hasAccessToHiddenContent": false,
    "tabOrder": 0
  },
  "parentAppId": "cea5237d-6504-9e91-4fe5-d8e93bf777d2",
  "elementReferences": [
    {
      "elementId": "e0adef79-72b1-47eb-afb6-e95631a1f101",
      "itemType": "Report",
      "itemLogicalId": "a1356cbb-204a-8f31-4f5e-76dacd53a9b5"
    },
    {
      "elementId": "9a9f988d-73f1-4c9e-8a71-2ccd3d38c2ec"
    }
  ]
}

Org app and audiences example

The following folder structure is an example of an org app with two audiences. Each audience selects a different report while sharing the app's overview page.

workspace-content/
├── Daily shipping.OrgApp/
│   ├── .platform
│   ├── definition.json
│   └── .children/
│       ├── Sales reports.OrgAppAudience/
│       │   ├── .platform
│       │   └── definition.json
│       └── Shipping and handling.OrgAppAudience/
│           ├── .platform
│           └── definition.json
...
├── Sales report.Report/
│   └── ...
└── Sales report.SemanticModel/
    └── ...

Sample .platform file for the Daily shipping org app:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/gitIntegration/platformProperties/2.0.0/schema.json",
  "metadata": {
    "type": "OrgApp",
    "displayName": "Daily shipping"
  },
  "config": {
    "version": "2.0",
    "logicalId": "193cf882-7b74-86f8-43f2-c65a47e56572"
  }
}

Sample definition.json file for org app:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/orgapp/definition/orgAppDefinition/2.0.0/schema.json",
  "settings": {},
  "elements": [
    {
      "elementType": "overview",
      "elementId": "2a63e2de-9213-4eac-940d-c134ce313ae8",
      "header": {
        "title": "Daily shipping",
        "body": "Sales and shipping reports",
        "showTheme": false
      },
      "displayName": "Overview"
    },
    {
      "elementType": "item",
      "elementId": "f1a59431-0f00-4ac0-9aa6-593e9b6ca8f6",
      "itemType": "Report",
      "itemLogicalId": "8083d2fb-13f7-9109-4814-781cb921b6dc",
      "displayName": "Sales report"
    },
    {
      "elementType": "item",
      "elementId": "a2567bc3-4aed-49a4-a147-7d90d318c70a",
      "itemType": "Report",
      "itemLogicalId": "334e1731-4f3d-a873-4c6c-03fd2a65adc7",
      "displayName": "Shipping report"
    }
  ]
}

Sample .platform file for the Sales reports audience:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/gitIntegration/platformProperties/2.0.0/schema.json",
  "metadata": {
    "type": "OrgAppAudience",
    "displayName": "Sales reports"
  },
  "config": {
    "version": "2.0",
    "logicalId": "d14d28b2-7afb-a0ab-43db-32fe11e19884"
  }
}

The following sample definition.json file for Sales reports audience shows how audience refers to its parent org app artifact using parentAppId property that matches the logicalId in its parent's .platform file.

Also note the matching elementId properties between audience and org app definition.json files: Sales reports audience shares two items with its users:

• the overview item
• Sales report with elementId matching the elementId in the org app definition, and itemLogicalId matching the report's logicalId in the report's .platform file.

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/orgappaudience/definition/orgAppAudienceDefinition/1.0.0/schema.json",
  "settings": {
    "hasAccessToHiddenContent": false,
    "tabOrder": 0
  },
  "parentAppId": "193cf882-7b74-86f8-43f2-c65a47e56572",
  "elementReferences": [
    {
      "elementId": "2a63e2de-9213-4eac-940d-c134ce313ae8"
    },
    {
      "elementId": "f1a59431-0f00-4ac0-9aa6-593e9b6ca8f6",
      "itemType": "Report",
      "itemLogicalId": "8083d2fb-13f7-9109-4814-781cb921b6dc"
    }
  ]
}

The .platform and definition.json files for Shipping and handling audience look similar.

Org apps in deployment pipelines

You can use Fabric deployment pipeline to deploy your org app across different environments, such as development, test, and production. And you can use deployment rules to customize the org app.

To learn how to use deployment pipelines, see Introduction to deployment pipelines.

For complex multi-workspace deployments or Git-based CI/CD workflows with environment-specific configurations, you can also use the fabric-cicd tool, which can consume org app definitions from Git and apply transformations across Dev/Test/Prod stages.

Related content

• Get started with Org Apps
• Introduction to the CI/CD process as part of application lifecycle management (ALM) in Microsoft Fabric