### Run activate script for environment setup

Source: https://github.com/microsoft/fabric-cicd/blob/main/CONTRIBUTING.md

Execute this PowerShell script to install necessary tools like `uv` and `ruff`, and set up the default environment using `uv sync`. This script is optional as manual setup is also possible.

```powershell
.
activate.ps1
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/microsoft/fabric-cicd/wiki/How-to-sideload-the-Documentation

Installs all necessary dependencies for documentation development and building. Use this command to set up your environment.

```bash
uv sync --group dev
```

--------------------------------

### Example .schedules File

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This is an example of a `.schedules` file that can be parameterized. The `enabled` field will be replaced based on the environment.

```json
{
    "$schema": "https://developer.microsoft.com/json-schemas/fabric/gitIntegration/schedules/1.0.0/schema.json",
    "schedules": [
        {
            "enabled": true,
            "jobType": "Execute",
            "configuration": {
                "type": "Cron",
                "startDateTime": "2025-07-01T12:00:00",
                "endDateTime": "2029-07-01T12:00:00",
                "localTimeZoneId": "Pacific Standard Time",
                "interval": 15
            }
        }
    ]
}
```

--------------------------------

### GitHub Deployment Placeholder

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/deployment_variable.md

This is a placeholder for GitHub deployment examples. The Azure DevOps example is recommended as a starting point for implementation.

```python
'''Unconfirmed example at this time, however, the Azure DevOps example is a good starting point'''
```

--------------------------------

### Install fabric-cicd Library

Source: https://github.com/microsoft/fabric-cicd/wiki/How-to-build-and-run

Install the fabric-cicd library using uv.

```sh
uv pip install fabric-cicd
```

--------------------------------

### Install fabric-cicd with pip

Source: https://github.com/microsoft/fabric-cicd/blob/main/README.md

Use this command to install the fabric-cicd library. Ensure you have pip installed and configured.

```bash
pip install fabric-cicd
```

--------------------------------

### Selective Environment Configuration Example

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Demonstrates how to apply settings selectively across environments. For instance, excluding folders only in production or skipping a process in development.

```yaml
core:
    workspace_id:
        dev: "dev-workspace-id"
        test: "test-workspace-id"
        prod: "prod-workspace-id"
    repository_directory: "./workspace" # Same for all environments

publish:
    # Only exclude legacy folders in prod environment
    folder_exclude_regex:
        prod: "^/legacy_.*"
        # dev and test not specified - no folder exclusion applied

    # Skip publish in dev, run in test and prod
    skip:
        dev: true
        # test and prod default to false
```

--------------------------------

### Deploy with Custom Authentication

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

This example shows how to deploy using a custom credential, such as `ClientSecretCredential`, by providing tenant, client ID, and client secret. This is useful for service principal authentication.

```python
from fabric_cicd import deploy_with_config
from azure.identity import ClientSecretCredential

# Create a credential
credential = ClientSecretCredential(
    tenant_id="your-tenant-id",
    client_id="your-client-id",
    client_secret="your-client-secret"
)

# Deploy with custom credential
deploy_with_config(
    config_file_path="path/to/config.yml",
    token_credential=credential,
    environment="prod"
)
```

--------------------------------

### Run MkDocs Development Server

Source: https://github.com/microsoft/fabric-cicd/wiki/How-to-sideload-the-Documentation

Starts the MkDocs development server for live previewing of documentation. The server typically runs on http://127.0.0.1:8000.

```bash
uv run mkdocs serve
```

--------------------------------

### Install Specific Version of fabric-cicd

Source: https://github.com/microsoft/fabric-cicd/wiki/How-to-build-and-run

Install a specific version of the fabric-cicd library using uv.

```sh
uv pip install fabric-cicd==0.1.33
```

--------------------------------

### Example pipeline-content.json with Connection ID

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This is an example of a Data Pipeline's JSON content where a SQL Server Connection ID is hardcoded. This ID will be dynamically replaced during deployment based on the `parameter.yml` configuration.

```json
{
    "properties": {
        "activities": [
            {
                "name": "Copy Data",
                "type": "Copy",
                "dependsOn": [],
                "policy": {
                    "timeout": "0.12:00:00",
                    "retry": 0,
                    "retryIntervalInSeconds": 30,
                    "secureOutput": false,
                    "secureInput": false
                },
                "typeProperties": {
                    "source": {
                        "type": "AzureSqlSource",
                        "queryTimeout": "02:00:00",
                        "partitionOption": "None",
                        "datasetSettings": {
                            "annotations": [],
                            "type": "AzureSqlTable",
                            "schema": [],
                            "typeProperties": {
                                "schema": "Dataprod",
                                "table": "DIM_Calendar",
                                "database": "unified"
                            },
                            "externalReferences": {
                                "connection": "c517e095-ed87-4665-95fa-8cdb1e751fba"
                            }
                        }
                    },
                    "sink": {
                        "type": "LakehouseTableSink",
                        "tableActionOption": "Append",
                        "datasetSettings": {
                            "annotations": [],
                            "linkedService": {
                                "name": "Unified",
                                "properties": {
                                    "annotations": [],
                                    "type": "Lakehouse",
                                    "typeProperties": {
                                        "workspaceId": "2d2e0ae2-9505-4f0c-ab42-e76cc11fb07d",
                                        "artifactId": "31dd665e-95f3-4575-9f46-70ea5903d89b",
                                        "rootFolder": "Tables"
                                    }
                                }
                            },
                            "type": "LakehouseTable",
                            "schema": [],
                            "typeProperties": {
                                "schema": "Dataprod",
                                "table": "DIM_Calendar"
                            }
                        }
                    },
                    "enableStaging": false,
                    "translator": {
                        "type": "TabularTranslator",
                        "typeConversion": true,
                        "typeConversionSettings": {
                            "allowDataTruncation": true,
                            "treatBooleanAsNumber": false
                        }
                    }
                }
            }
        ]
    }
}
```

--------------------------------

### Example Sparkcompute.yml Configuration

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This `Sparkcompute.yml` file includes an `instance_pool_id` that can be parameterized using the `spark_pool` input in `parameter.yml`.

```yaml
enable_native_execution_engine: false
instance_pool_id: 72c68dbc-0775-4d59-909d-a47896f4573b
driver_cores: 16
driver_memory: 112g
executor_cores: 16
executor_memory: 112g
dynamic_executor_allocation:
    enabled: false
    min_executors: 31
    max_executors: 31
runtime_version: 1.3
```

--------------------------------

### Example parameter.yml Structure

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This YAML file defines parameters for find-replace, key-value replacement, spark pool configuration, and semantic model binding, supporting different values for different environments like PPE and PROD.

```yaml
find_replace:
    - find_value: "your-dev-lakehouse-id"
      replace_value:
          PPE: "ppe-lakehouse-id"
          PROD: "prod-lakehouse-id"

key_value_replace:
    - find_key: $.variables[?(@.name=="Environment")].value
      replace_value:
          PPE: "PPE"
          PROD: "PROD"

spark_pool:
    - instance_pool_id: "your-dev-pool-instance-id"
      replace_value:
          PPE:
              type: "Capacity"
              name: "PPE-Pool-name"
          PROD:
              type: "Capacity"
              name: "PROD-Pool-name"

semantic_model_binding:
    default:
        connection_id:
            PPE: "PPE-connection_id"
            PROD: "PROD-connection_id"
    models:
        - semantic_model_name: "semantic_model_name"
          connection_id:
              PPE: "PPE-connection_id"
              PROD: "PROD-connection_id"
```

--------------------------------

### GitHub Actions Placeholder

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/release_pipeline.md

This is a placeholder for GitHub Actions configuration. The Azure DevOps example serves as a starting point for developing a similar pipeline for GitHub.

```yaml
# Unconfirmed example at this time. The Azure DevOps example is a good starting point.

```

--------------------------------

### Sample Dataflow mashup.pq file content

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This is the content of the `mashup.pq` file for the Sample Dataflow, showing the structure where GUIDs for workspace and lakehouse IDs are embedded.

```pq
[StagingDefinition = [Kind = "FastCopy"]]
section Section1;
[DataDestinations = {[Definition = [Kind = "Reference", QueryName = "Table_DataDestination", IsNewTarget = true], Settings = [Kind = "Automatic", TypeSettings = [Kind = "Table"]]]}]
shared Table = let
  Source = Table.FromRows(Json.Document(Binary.Decompress(Binary.FromText("i45WckksSUzLyS9X0lEyBGKP1JycfKVYHYhEQGZBak5mXipQwgiIw/OLclLAkn75JalJ+fnZQEFjmC4FhHRwam5iXklmsm9+SmoOUN4EiMFsBVTzoRabArGLG0x/LAA=", BinaryEncoding.Base64), Compression.Deflate)), let _t = ((type nullable text) meta [Serialized.Text = true]) in type table [Item = _t, Id = _t, Name = _t]),
  #"Changed column type" = Table.TransformColumnTypes(Source, {{"Item", type text}, {"Id", Int64.Type}, {"Name", type text}}),
  #"Added custom" = Table.TransformColumnTypes(Table.AddColumn(#"Changed column type", "IsDataflow", each if [Item] = "Dataflow" then true else false), {{"IsDataflow", type logical}}),
  #"Added custom 1" = Table.TransformColumnTypes(Table.AddColumn(#"Added custom", "ContainsHello", each if Text.Contains([Name], "Hello") then 1 else 0), {{"ContainsHello", Int64.Type}})
in
  #"Added custom 1";
shared Table_DataDestination = let
  Pattern = Lakehouse.Contents([CreateNavigationProperties = false, EnableFolding = false]),
  Navigation_1 = Pattern{[workspaceId = "e6a8c59f-4b27-48d1-ae03-7f92b1c6458d"]}[Data],
  Navigation_2 = Navigation_1{[lakehouseId = "3d72f90e-61b5-42a8-9c7e-b085d4e31fa2"]}[Data],

```

--------------------------------

### Advanced find_replace Parameterization

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This example demonstrates an advanced use case of parameterization with the find_replace function. It shows how to navigate and extract data from a table structure.

```Power Query M
TableNavigation = Navigation_2{[Id = "Items", ItemKind = "Table"]}?[Data]?
in
  TableNavigation;
```

--------------------------------

### Parameterize Lakehouse and Workspace GUIDs in Notebooks

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

Use `find_value` with `is_regex: "true"` to dynamically replace Lakehouse and Workspace GUIDs in Notebooks. The regex must include a capture group, and `find_value` must match group 1. This is useful for values not known until deployment time.

```yaml
find_replace:
    # lakehouse GUID matching group 1 of regex pattern to be replaced
    - find_value: "#\s*META\s+\"default_lakehouse\":\s*\"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\""
      replace_value:
          PPE: "$items.Lakehouse.Example_LH.$id" # PPE lakehouse GUID (dynamic)
          PROD: "$items.Lakehouse.Example_LH.$id" # PROD lakehouse GUID (dynamic)
      is_regex: "true"
      item_type: "Notebook" # filter on notebook files
      item_name: ["Hello World", "Goodbye World"] # filter on specific notebook files
    # workspace ID matching group 1 of regex pattern to be replaced
    - find_value: "#\s*META\s+\"default_lakehouse_workspace_id\":\s*\"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\""
      replace_value:
          PPE: "$workspace.$id" # PPE workspace ID (dynamic)
          PROD: "$workspace.$id" # PROD workspace ID (dynamic)
      is_regex: "true"
      file_path: # filter on notebook files with these paths
          - "/Hello World.Notebook/notebook-content.py"
          - "\\Goodbye World.Notebook\\notebook-content.py"
```

--------------------------------

### Run MkDocs Development Server on Custom Port

Source: https://github.com/microsoft/fabric-cicd/wiki/How-to-sideload-the-Documentation

Starts the MkDocs development server on a different port if the default port 8000 is already in use. This allows concurrent running of multiple services.

```bash
uv run mkdocs serve -a 127.0.0.1:8001
```

--------------------------------

### Notebook with default lakehouse configuration

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This Python notebook contains metadata with default lakehouse GUIDs that can be parameterized using find_replace.

```python
# Fabric notebook source

# METADATA ********************

# META {
#META   "kernel_info": {
#META     "name": "synapse_pyspark"
#META   },
#META   "dependencies": {
#META     "lakehouse": {
#META       "default_lakehouse": "47592d55-9a83-41a8-9b21-e1ef44264161",
#META       "default_lakehouse_name": "Example_LH",
#META       "default_lakehouse_workspace_id": "2190baad-a374-4114-addd-0dcf0533e69d"
#META     },
#META     "environment": {
#META       "environmentId": "a277ea4a-e87f-8537-4ce0-39db11d4aade",
#META       "workspaceId": "00000000-0000-0000-0000-000000000000"
#META     }
#META   }
#META }

# CELL ********************

df = spark.sql("SELECT * FROM Example_LH.Table1 LIMIT 1000")
display(df)

# METADATA ********************

#META {
#META   "language": "python",
#META   "language_group": "synapse_pyspark"
#META }

```

--------------------------------

### Sample Workspace Directory Structure

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/troubleshooting.md

Demonstrates the recommended repository structure for Fabric item source control files, including metadata and definition files.

```text
sample/workspace/
├── Sample Pipeline.DataPipeline/
│   ├── .platform
│   └── pipeline-content.json
├── Sample_Notebook.Notebook/
│   ├── .platform
│   └── notebook-content.py
...
└── parameter.yml
```

--------------------------------

### Serve MkDocs Documentation

Source: https://github.com/microsoft/fabric-cicd/wiki/Common-Flows

Use this command to test and validate documentation changes locally during development.

```sh
uv run mkdocs serve

```

--------------------------------

### Deploy with Basic Configuration

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Use this snippet to deploy Fabric artifacts using a configuration file and Azure CLI credentials. Ensure the config file path and environment are correctly specified.

```python
from fabric_cicd import deploy_with_config
from azure.identity import AzureCliCredential

# Deploy using a config file
deploy_with_config(
    config_file_path="path/to/config.yml",  # required
    token_credential=AzureCliCredential(),  # required
    environment="dev"  # optional (recommended)
)
```

--------------------------------

### Environment Variable Replacement in find_replace

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

Use this to replace values in `parameter.yml` with pipeline/environment variables when `enable_environment_variable_replacement` is set. Only variables starting with '$ENV:' are used.

```yaml
find_replace:
    # Lakehouse GUID
    - find_value: "db52be81-c2b2-4261-84fa-840c67f4bbd0"
      replace_value:
          PPE: "$ENV:ppe_lakehouse"
          PROD: "$ENV:prod_lakehouse"
```

--------------------------------

### Configure Configuration-Based Deployment

Source: https://github.com/microsoft/fabric-cicd/wiki/Development-Tools

Enable experimental features and configuration deployment, then specify the path to your config.yml file and the target environment. This script validates configuration file parsing and deployment.

```python
# 1. Enable debug logging (optional)
# change_log_level()

# 2. Enable required feature flags
append_feature_flag("enable_experimental_features")
append_feature_flag("enable_config_deploy")

# 3. Point to your config file
config_file = "path/to/config.yml"

# 4. Set environment
environment = "dev"

# 5. Run deployment
deploy_with_config(
    config_file_path=config_file,
    environment=environment
)
```

--------------------------------

### Basic Configuration-Based Deployment

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Use this function to deploy Fabric items based on a configuration file. Ensure `config_file_path` and `token_credential` are provided. Other parameters must be passed as keyword arguments.

```python
from fabric_cicd import deploy_with_config
from azure.identity import AzureCliCredential

# Deploy using a config file
deploy_with_config(
    config_file_path="C:/dev/workspace/config.yml",  # required
    token_credential=AzureCliCredential(),  # required
    environment="dev"
)
```

--------------------------------

### Configure Local Deployment with Fabric CI/CD

Source: https://github.com/microsoft/fabric-cicd/wiki/Development-Tools

Set up your workspace ID, environment, and repository directory to test full deployment workflows locally. Authentication and feature flags can also be configured.

```python
# 1. Set your workspace ID, environment, and repository directory path
workspace_id = "your-workspace-id"
environment = "DEV"  # Must match environment in parameter.yml
repository_directory = "root/sample/workspace" # In this example, our workspace content sits within the root/sample/workspace directory

# 2. Configure authentication (optional)
# Uncomment to use Service Principal authentication
# token_credential = ClientSecretCredential(
#     client_id="your-client-id",
#     client_secret="your-client-secret",
#     tenant_id="your-tenant-id"
# )

# 3. Enable debug logging (optional)
# change_log_level()

# 4. Set required feature flags, if any (optional)
# append_feature_flag("feature_flag_1")
# append_feature_flag("feature_flag_2")

# 5. Select item types to deploy (optional, otherwise deploys all supported item types)
# item_type_in_scope = ["Notebook", "DataPipeline", "Environment"]

# 6. Create the FabricWorkspace object
target_workspace = FabricWorkspace(
    workspace_id=workspace_id,
    environment=environment,
    repository_directory=repository_directory,
    # Uncomment to deploy specific item types
    # item_type_in_scope=item_type_in_scope,
    # Uncomment to use SPN auth
    # token_credential=token_credential,
)

# 7. Uncomment publish operation to test
# publish_all_items(target_workspace)

# 8. Uncomment unpublish operation to test
# unpublish_all_orphan_items(target_workspace)
```

--------------------------------

### Parameterize Dataflow Workspace and Lakehouse IDs

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

Use regex patterns in `parameter.yml` to find and replace workspace and lakehouse GUIDs within the `mashup.pq` file. This allows for dynamic substitution of environment-specific IDs.

```yaml
find_replace:
    # Lakehouse workspace ID regex - matches the workspaceId GUID
    - find_value: Navigation_1\s*=\s*Pattern\{\[workspaceId\s*=\s*"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})"\}
      replace_value:
          PPE: "$workspace.$id" # PPE workspace ID (dynamic)
          PROD: "$workspace.$id"
      is_regex: "true" # Activate find_value regex matching
      file_path: "/Sample Dataflow.Dataflow/mashup.pq"

    # Lakehouse ID regex - matches the lakehouseId GUID
    - find_value: Navigation_2\s*=\s*Navigation_1\{\[lakehouseId\s*=\s*"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})"\}
      replace_value:
          PPE: "$items.Lakehouse.Sample_LH.$id" # Sample_LH Lakehouse ID in PPE (dynamic)
          PROD: "$items.Lakehouse.Sample_LH.$id"
      is_regex: "true" # Activate find_value regex matching
      file_path: "/Sample Dataflow.Dataflow/mashup.pq"

    # Connection ID - Cluster ID
    - find_value: "8e4f92a7-3c18-49d5-b6d0-7f2e591ca4e8"
      replace_value:
          PPE: "76a8f5c3-e4b2-48d1-9c7f-382d69a5e7b0" # PPE Cluster ID
          PROD: "f297e14d-6c83-42a5-b718-59d40e3f8c2d" # PROD Cluster ID
      file_path: "/Sample Dataflow.Dataflow/queryMetadata.json"

    # Connection ID - Datasource ID
    - find_value: "d12c5f7b-90a3-47e6-8d2c-3fb59e01d47a"
      replace_value:
          PPE: "25b9a417-3d8e-4f62-901c-75de6ba84f35" # PPE Datasource ID
          PROD: "cb718d96-5ae2-47fc-8b93-1d24c0f5e8a7" # PROD Datasource ID
      file_path: "/Sample Dataflow.Dataflow/queryMetadata.json"
```

--------------------------------

### Core Settings in Configuration File (Single Value)

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Defines essential deployment settings using single values applicable to all environments. The `repository_directory` is required and can be a relative or absolute path.

```yaml
core:
    # Only one workspace identifier field is required
    workspace: <workspace_name>

    workspace_id: <workspace_id>

    # Required - path to the directory containing Fabric items
    repository_directory: <rel_or_abs_path_of_repo_dir>

    # Optional - specific item types to include in deployment
    item_types_in_scope:
        - <item_type_1>
        - <item_type_2>
        - <item_type..>

    # Optional - path to parameter file
    parameter: <rel_or_abs_path_of_param_file>
```

--------------------------------

### Initialize FabricWorkspace and Publish Items

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/deployment_variable.md

Initializes a FabricWorkspace object with provided credentials and configuration, then publishes and unpublishes items based on the repository content. Ensure 'workspace_id', 'environment', 'repository_directory', 'item_type_in_scope', and 'token_credential' are correctly set.

```python
environment = "PROD"
else:
    raise ValueError("Invalid branch to deploy from")

# Sample values for FabricWorkspace parameters
repository_directory = str(root_directory / "your-workspace-directory")
item_type_in_scope = ["Notebook", "DataPipeline", "Environment"]

# Initialize the FabricWorkspace object with the required parameters
target_workspace = FabricWorkspace(
    workspace_id=workspace_id,
    environment=environment,
    repository_directory=repository_directory,
    item_type_in_scope=item_type_in_scope,
    token_credential=token_credential,  # or any other TokenCredential
)

# Publish all items defined in item_type_in_scope
publish_all_items(target_workspace)

# Unpublish all items defined in item_type_in_scope not found in repository
unpublish_all_orphan_items(target_workspace)
```

--------------------------------

### Azure DevOps Release Pipeline with Azure PowerShell

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/release_pipeline.md

This Azure DevOps YAML configuration deploys a Fabric workspace using Azure PowerShell. It requires the 'fabric-cicd' package to be installed and a valid Azure service connection.

```yaml
trigger:
  branches:
    include:
      - dev
      - main
stages:
  - stage: Build_Release
    jobs:
      - job: Build
        pool:
          vmImage: windows-latest
        steps:
          - checkout: self
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.12'
              addToPath: true
          - script: |
              pip install fabric-cicd
            displayName: 'Install fabric-cicd'
          - task: AzurePowerShell@5
            displayName: "Deploy Fabric Workspace"
            inputs:
              azureSubscription: "your-service-connection"
              scriptType: "InlineScript"
              scriptLocation: "inlineScript"
              pwsh: true
              Inline: |
                python -u $(System.DefaultWorkingDirectory)/.deploy/fabric_workspace.py
```

--------------------------------

### Sample config.yml File

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

This is a sample YAML configuration file used for Fabric CI/CD deployments. It defines workspace settings, item scopes, publishing rules, and feature flags.

```yaml
core:
    workspace:
        dev: "Fabric-Dev-Engineering"
        test: "Fabric-Test-Engineering"
        prod: "Fabric-Prod-Engineering"

    workspace_id:
        dev: "8b6e2c7a-4c1f-4e3a-9b2e-7d8f2e1a6c3b"
        test: "2f4b9e8d-1a7c-4d3e-b8e2-5c9f7a2d4e1b"
        prod: "7c3e1f8b-2d4a-4b9e-8f2c-1a6c3b7d8e2f"

    repository_directory: "." # relative path

    item_types_in_scope:
        - Notebook
        - DataPipeline
        - Environment
        - Lakehouse

    parameter: "parameter.yml" # relative path

publish:
    # Don't publish items matching this pattern (no feature flag required)
    exclude_regex: "^DONT_DEPLOY.*"

    # Use folder_exclude_regex OR folder_path_to_include, not both for the same environment
    folder_exclude_regex:
        dev: "^/DONT_DEPLOY_FOLDER"

    folder_path_to_include:
        prod:
            - "/DEPLOY_FOLDER"
            - "/DEPLOY_FOLDER/DEPLOY_NESTED_FOLDER"

    items_to_include:
        - "Hello World.Notebook"
        - "Run Hello World.DataPipeline"

    shortcut_exclude_regex:
        test: "^temp_.*"

    skip:
        dev: true
        test: false
        prod: false

unpublish:
    # Don't unpublish items matching this pattern (no feature flag required)
    exclude_regex: "^DEBUG.*"

    skip:
        dev: false
        test: false
        prod: true

features:
    - enable_shortcut_publish
    - enable_experimental_features
    - enable_items_to_include
    - enable_exclude_folder
    - enable_include_folder
    - enable_shortcut_exclude

constants:
    DEFAULT_API_ROOT_URL: "https://api.fabric.microsoft.com"

```

--------------------------------

### Azure DevOps Release Pipeline with Azure CLI

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/release_pipeline.md

Use this YAML snippet in Azure DevOps to deploy a Fabric workspace using the Azure CLI. Ensure the 'fabric-cicd' package is installed and an Azure service connection is configured.

```yaml
trigger:
  branches:
    include:
      - dev
      - main
stages:
  - stage: Build_Release
    jobs:
      - job: Build
        pool:
          vmImage: windows-latest
        steps:
          - checkout: self
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.12'
              addToPath: true
          - script: |
              pip install fabric-cicd
            displayName: 'Install fabric-cicd'
          - task: AzureCLI@2
            displayName: "Deploy Fabric Workspace"
            inputs:
              azureSubscription: "your-service-connection"
              scriptType: "ps"
              scriptLocation: "inlineScript"
              inlineScript: |
                python -u $(System.DefaultWorkingDirectory)/.deploy/fabric_workspace.py
```

--------------------------------

### Execute Configuration Deployment Script

Source: https://github.com/microsoft/fabric-cicd/wiki/Development-Tools

Run the configuration-based deployment script using the 'uv run python' command, ensuring the correct path to the script is provided. This command executes the debug_local config.py script.

```powershell
uv run python "devtools/debug_local config.py"
```

--------------------------------

### Azure DevOps Release Pipeline Configuration

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/release_pipeline.md

Configure an Azure DevOps pipeline to deploy Fabric items. This example uses variable groups linked to Azure Key Vault for secrets and other variables for deployment configuration. It injects these variables into a Python script for execution.

```yaml
trigger:
  branches:
    include:
      - dev
      - main

parameters:
- name: items_in_scope
  displayName: Enter Fabric items to be deployed
  type: string
  default: '["Notebook","DataPipeline","Environment"]'

variables:
- group: Fabric_Deployment_Group_KeyVault # Linked to Azure Key Vault and contains tenant id, SPN client id, and SPN secret
- group: Fabric_Deployment_Group  # Contains workspace_name and repository directory name

stages:
  - stage: Build_Release
    jobs:
      - job: Build
        pool:
          vmImage: windows-latest
        steps:
          - checkout: self
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.12'
              addToPath: true
          - script: |
              pip install fabric-cicd
            displayName: 'Install fabric-cicd'
          - task: PythonScript@0
            inputs:
              scriptSource: 'filePath'
              scriptPath: '.deploy/fabric_workspace.py'
              arguments: >-
                --spn_client_id $(client_id) # from Fabric_Deployment_Group_KeyVault
                --spn_client_secret $(client_secret) # from Fabric_Deployment_Group_KeyVault
                --tenant_id $(tenant_id) # from Fabric_Deployment_Group_KeyVault
                --workspace_id $(workspace_id) # from Fabric_Deployment_Group
                --environment $(environment_name) # from Fabric_Deployment_Group
                --repository_directory $(repository_directory) # from Fabric_Deployment_Group
                --item_types_in_scope ${{ parameters.items_in_scope }}

```

--------------------------------

### Sample Dataflow queryMetadata.json file content

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

This is the content of the `queryMetadata.json` file for the Sample Dataflow, illustrating the structure of connection details that may require parameterization.

```json
{
    "formatVersion": "202502",
    "computeEngineSettings": {},
    "name": "Sample Dataflow",
    "queryGroups": [],
    "documentLocale": "en-US",
    "queriesMetadata": {
        "Table": {
            "queryId": "ba67667b-14c0-4536-a92d-feafc73baa4b",
            "queryName": "Table",
            "loadEnabled": false
        },
        "Table_DataDestination": {
            "queryId": "a157a378-b510-4d95-bb82-5a7c80df8b4c",
            "queryName": "Table_DataDestination",
            "isHidden": true,
            "loadEnabled": false
        }
    },
    "connections": [
        {
            "path": "Lakehouse",
            "kind": "Lakehouse",
            "connectionId": "{\"ClusterId\":\"8e4f92a7-3c18-49d5-b6d0-7f2e591ca4e8\",\"DatasourceId\":\"d12c5f7b-90a3-47e6-8d2c-3fb59e01d47a\"}"
        }
    ]
}
```

--------------------------------

### Main parameter.yml File Structure

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

Define template file paths using the 'extend' key. Paths are relative to the main parameter file.

```yaml
extend:
    - "./templates/nb_parameters.yml"
    # - "./templates/pl_parameters.yml"
    # - "./templates/df_parameters.yml"

find_replace:
    # Lakehouse Connection Guid
    - find_value: "db52be81-c2b2-4261-84fa-840c67f4bbd0"
      replace_value:
          PPE: "81bbb339-8d0b-46e8-bfa6-289a159c0733"
          PROD: "5d6a1b16-447f-464a-b959-45d0fed35ca0"
      # Optional fields:
      item_type: "Notebook"
      item_name: ["Hello World", "Hello World Subfolder"]
      file_path:
          - "/Hello World.Notebook/notebook-content.py"
          - "/subfolder/Hello World Subfolder.Notebook/notebook-content.py"

spark_pool:
    # CapacityPool_Large
    - instance_pool_id: "72c68dbc-0775-4d59-909d-a47896f4573b"
      replace_value:
          PPE:
              type: "Capacity"
              name: "CapacityPool_Large_PPE"
          PROD:
              type: "Capacity"
              name: "CapacityPool_Large_PROD"
      # Optional field:
      item_name: "World"

```

--------------------------------

### Configure FabricWorkspace with Repository Directory

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

Instantiate the FabricWorkspace object, specifying the workspace ID, repository directory, environment, and item types. The `repository_directory` should contain the `parameter.yml` file.

```python
from azure.identity import AzureCliCredential
from fabric_cicd import FabricWorkspace

token_credential = AzureCliCredential()
workspace = FabricWorkspace(
    workspace_id="your-workspace-id",
    repository_directory="C:/dev/workspace",
    environment="PROD",
    item_type_in_scope=["Notebook"],
    token_credential=token_credential,  # or any other TokenCredential
)
```

--------------------------------

### Local Deployment with Arguments

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/deployment_variable.md

Use this script for local deployments where you need to pass workspace ID, environment, and repository directory as arguments. It configures FabricWorkspace and publishes/unpublishes items.

```python
'''Accepts parameters passed into Python during execution'''

import argparse
from azure.identity import AzureCliCredential
from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items

# Use Azure CLI credential to authenticate
token_credential = AzureCliCredential()

# Accept parsed arguments
parser = argparse.ArgumentParser(description='Process deployment arguments.')
parser.add_argument('--workspace_id', type=str, required=True)
parser.add_argument('--environment', type=str)
parser.add_argument('--repository_directory', type=str, required=True)
parser.add_argument('--items_in_scope', type=str)
args = parser.parse_args()

# Sample values for FabricWorkspace parameters
workspace_id = args.workspace_id
environment = args.environment
repository_directory = args.repository_directory
item_type_in_scope = args.items_in_scope.split(",") if args.items_in_scope else ["Notebook", "DataPipeline", "Environment"]

# Initialize the FabricWorkspace object with the required parameters
target_workspace = FabricWorkspace(
    workspace_id=workspace_id,
    environment=environment,
    repository_directory=repository_directory,
    item_type_in_scope=item_type_in_scope,
    token_credential=token_credential,  # or any other TokenCredential
)

# Publish all items defined in item_type_in_scope
publish_all_items(target_workspace)

# Unpublish all items defined in item_type_in_scope not found in repository
unpublish_all_orphan_items(target_workspace)
```

--------------------------------

### Key-Value Replacement Configuration (parameter.yml)

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

Define replacement rules for connection strings in a parameter.yml file. Specify the JSON path to the key, the environment-specific values, and the item type and name to which the rule applies.

```yaml
key_value_replace:
    - find_key: $.datasetReference.byConnection.connectionString
      replace_value:
          PPE: "Data Source=powerbi://api.powerbi.com/v1.0/myorg/ppe-workspace-guid;initial catalog=ppe-semantic-model;access mode=readonly;integrated security=ClaimsToken;semanticmodelid=ppe-model-guid"
          PROD: "Data Source=powerbi://api.powerbi.com/v1.0/myorg/prod-workspace-guid;initial catalog=prod-semantic-model;access mode=readonly;integrated security=ClaimsToken;semanticmodelid=prod-model-guid"
      item_type: "Report"
      item_name: "MyReport"
```

--------------------------------

### Core Settings in Configuration File (Environment Mapping)

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Configures deployment settings with environment-specific values. This allows different workspaces, directories, item types, or parameter files per environment.

```yaml
core:
    # Only one workspace identifier field is required
    workspace:
        <env_1>: <env_1_workspace_name>
        <env..>: <env.._workspace_name>

    workspace_id:
        <env_1>: <env_1_workspace_id>
        <env..>: <env.._workspace_id>

    # Required - path to the directory containing Fabric items
    repository_directory:
        <env_1>: <rel_or_abs_path_of_repo_dir_1>
        <env..>: <rel_or_abs_path_of_repo_dir..>

    # Optional - specific item types to include in deployment
    item_types_in_scope:
        <env_1>:
            - <item_type_1>
            - <item_type..>
        <env..>:
            - <item_type_1>
            - <item_type..>

    # Optional - path to parameter file
    parameter:
        <env_1>: <rel_or_abs_path_of_param_file_1>
        <env..>: <rel_or_abs_path_of_param_file..>
```

--------------------------------

### Configure Publish Settings

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Use the `publish` section to control item publishing behavior. Omit this section for default behavior where all items are published without exclusions. Settings include regex for exclusions, specific folder or item inclusions, and shortcut exclusions.

```yaml
publish:
    # Optional - pattern to exclude items from publishing (no feature flag required)
    exclude_regex: <regex_pattern_string>

    # Optional - pattern to exclude specific folder paths with items from publishing (requires feature flags)
    folder_exclude_regex: <regex_pattern_string>

    # Optional - specific folder paths with items to publish (requires feature flags)
    folder_path_to_include:
        - </subfolder_1>
        - </subfolder_2>
        - </subfolder_2/subfolder_3> # publish items found in nested folder - subfolder_3

    # Optional - specific items to publish (requires feature flags)
    items_to_include:
        - <item_name.item_type_1>
        - <item_name.item_type..>

    # Optional - pattern to exclude Lakehouse shortcuts from publishing (requires feature flags)
    shortcut_exclude_regex: <regex_pattern_string>

    # Optional - control publishing by environment
    skip: <bool_value>
```

--------------------------------

### Deploy with Configuration Override

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Dynamically modify configuration values at runtime using the `config_override` parameter. This is useful for debugging or temporary adjustments without altering the base configuration file. Note that overrides for production environments require extra caution.

```python
from fabric_cicd import deploy_with_config
from azure.identity import AzureCliCredential

config_override_dict = {
    "core": {
        "item_types_in_scope": ["Notebook", "DataPipeline"]
    },
    "publish": {
        "skip": {
            "dev": False
        }
    }
}

# Deploy with configuration override
deploy_with_config(
    config_file_path="path/to/config.yml",
    token_credential=AzureCliCredential(),
    environment="dev",
    config_override=config_override_dict
)
```

--------------------------------

### Basic Fabric Workspace CI/CD Automation

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/index.md

Initialize a FabricWorkspace object and publish/unpublish items. All parameters for FabricWorkspace must be passed as keyword arguments. The environment parameter is required for parameter replacement.

```python
from azure.identity import AzureCliCredential
from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items

token_credential = AzureCliCredential()

# Initialize the FabricWorkspace object with the required parameters
target_workspace = FabricWorkspace(
    workspace_id="your-workspace-id",
    environment="your-target-environment",
    repository_directory="your-repository-directory",
    item_type_in_scope=["Notebook", "DataPipeline", "Environment"],
    token_credential=token_credential,  # or any other TokenCredential
)

# Publish all items defined in item_type_in_scope
publish_all_items(target_workspace)

# Unpublish all items defined in item_type_in_scope not found in repository
unpublish_all_orphan_items(target_workspace)
```

--------------------------------

### Run Integration Tests with Mock Server

Source: https://github.com/microsoft/fabric-cicd/blob/main/tests/fixtures/README.md

Validate that your integration tests work correctly with the mock Fabric API server. This command runs a specific integration test for publishing all items.

```bash
uv run pytest -v -s --log-cli-level=INFO tests/test_integration_publish.py::test_publish_all_items_integration
```

--------------------------------

### Configure Publish Settings with Environment Mapping

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Configure environment-specific publish settings by mapping environment names to exclusion or inclusion patterns. This allows for granular control over publishing behavior across different deployment targets.

```yaml
publish:
    # Optional - pattern to exclude items from publishing
    exclude_regex:
        <env_1>: <regex_pattern_string_1>
        <env..>: <regex_pattern_string..>

    # Optional - pattern to exclude specific folder paths with items from publishing (requires feature flags)
    folder_exclude_regex:
        <env_1>: <regex_pattern_string_1>
        <env..>: <regex_pattern_string..>

    # Optional - specific folder paths with items to publish (requires feature flags)
    folder_path_to_include:
        <env_1>:
            - </subfolder_1>
            - </subfolder_2/subfolder_3>
        <env..>:
            - </subfolder_1>

    # Optional - specific items to publish (requires feature flags)
    items_to_include:
        <env_1>:
            - <item_name.item_type_1>
            - <item_name.item_type..>
        <env..>:
            - <item_name.item_type_1>
            - <item_name.item_type..>

    # Optional - pattern to exclude Lakehouse shortcuts from publishing (requires feature flags)
    shortcut_exclude_regex:
        <env_1>: <regex_pattern_string_1>
        <env..>: <regex_pattern_string..>

    # Optional - control publishing by environment
    skip:
        <env_1>: <bool_value>
        <env..>: <bool_value>
```

--------------------------------

### Create a New Change Entry

Source: https://github.com/microsoft/fabric-cicd/blob/main/CONTRIBUTING.md

Run this command in the terminal to create a new change entry for the changelog. Select the appropriate change type and provide a clear, user-focused description.

```bash
changie new
```

--------------------------------

### Configure Features Setting

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/config_deployment.md

Use the `features` section to specify a list of feature flags to be enabled. This allows for controlling specific functionalities within the deployment.

```yaml
features:
    - <feature_flag_1>
    - <feature_flag..>
```

--------------------------------

### Publish and Unpublish Fabric Items

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/example/authentication.md

This snippet demonstrates publishing and unpublishing all items within a specified scope using token credentials. It also handles the cleanup of temporary directories after operations.

```python
        item_type_in_scope=item_type_in_scope,
        token_credential=token_credential,
    )

    # Publish all items defined in item_type_in_scope
    publish_all_items(target_workspace)

    # Unpublish all items defined in item_type_in_scope not found in repository
    unpublish_all_orphan_items(target_workspace)

# Directory automatically cleaned up here
print("Cleaned up temporary directory")
```

--------------------------------

### nb_parameters.yml Template File

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/parameterization.md

Use 'is_regex: "true"' for regular expression find and replace operations. Define replacement values for different environments like PPE and PROD.

```yaml
find_replace:
    # Lakehouse Connection Guid regex
    - find_value: "#\s*META\s+\"default_lakehouse\":\s*\"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\""
      replace_value:
          # Variable: $items.type.name.attribute (Note: item type and name values are CASE SENSITIVE; id attribute returns the deployed item's id/guid)
          PPE: "$items.Lakehouse.WithoutSchema.id"
          PROD: "$items.Lakehouse.WithoutSchema.id"
      # Optional fields:
      is_regex: "true"
      file_path: "/Example Notebook.Notebook/notebook-content.py"
    # Lakehouse workspace id regex
    - find_value: "#\s*META\s+\"default_lakehouse_workspace_id\":\s*\"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\""
      replace_value:
          # Variable: $workspace.id -> target workspace id
          PPE: "$workspace.id"
          PROD: "$workspace.id"
      # Optional fields:
      is_regex: "true"
      file_path: "/Example Notebook.Notebook/notebook-content.py"

```

--------------------------------

### Azure CLI Credential for Local Development

Source: https://github.com/microsoft/fabric-cicd/blob/main/docs/how_to/troubleshooting.md

Authenticates using Azure CLI credentials. Ensure you are logged in via `az login`.

```python
# For local development with Azure CLI
from azure.identity import AzureCliCredential
token_credential = AzureCliCredential()
```