Skip to content

Code Reference

Provides tools for managing and publishing items in a Fabric workspace.

Classes:

Name Description
DeploymentResult

Result of a config-based deployment operation.

DeploymentStatus

Enumeration of deployment status values for deploy_with_config results.

FabricWorkspace

A class to manage and publish workspace items to the Fabric API.

FeatureFlag

Enumeration of supported feature flags for fabric-cicd.

ItemType

Enumeration of supported Microsoft Fabric item types.

Functions:

Name Description
append_feature_flag

Append a feature flag to the global feature_flag set.

change_log_level

Sets the log level for all loggers within the fabric_cicd package. Currently only supports DEBUG.

configure_external_file_logging

Configure fabric_cicd package logging to integrate with an external logger's

deploy_with_config

Deploy items using YAML configuration file with environment-specific settings.

disable_file_logging

Disable file logging for the fabric_cicd package.

publish_all_items

Publishes all items defined in the item_type_in_scope list of the given FabricWorkspace object.

unpublish_all_orphan_items

Unpublishes all orphaned items not present in the repository except for those matching the exclude regex.

DeploymentResult dataclass

DeploymentResult(status: DeploymentStatus, message: str)

Result of a config-based deployment operation.

This class provides a structured way to return deployment results. Currently only returned on successful completion; failures raise exceptions.

Attributes:

Name Type Description
status DeploymentStatus

The deployment status (DeploymentStatus.COMPLETED on success).

message str

A human-readable message describing the result.

DeploymentStatus

Bases: str, Enum

Enumeration of deployment status values for deploy_with_config results.

COMPLETED class-attribute instance-attribute

COMPLETED = 'completed'

Deployment completed successfully without any errors.

FabricWorkspace

FabricWorkspace(
    repository_directory: str,
    item_type_in_scope: Optional[list[str]] = None,
    environment: str = "N/A",
    workspace_id: Optional[str] = None,
    workspace_name: Optional[str] = None,
    token_credential: TokenCredential = None,
    **kwargs,
)

A class to manage and publish workspace items to the Fabric API.

Parameters:

Name Type Description Default
workspace_id Optional[str]

The ID of the workspace to interact with. Either workspace_id or workspace_name must be provided. Considers only workspace_id if both are specified.

None
workspace_name Optional[str]

The name of the workspace to interact with. Either workspace_id or workspace_name must be provided. Considers only workspace_id if both are specified.

None
repository_directory str

Local directory path of the repository where items are to be deployed from.

required
item_type_in_scope Optional[list[str]]

Item types that should be deployed for a given workspace. If omitted, defaults to all available item types.

None
environment str

The environment to be used for parameterization.

'N/A'
token_credential TokenCredential

The token credential to use for API requests.

None
kwargs

Additional keyword arguments.

{}

Examples:

Basic usage

>>> from fabric_cicd import FabricWorkspace
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )

Basic usage with workspace_name

>>> from fabric_cicd import FabricWorkspace
>>> workspace = FabricWorkspace(
...     workspace_name="your-workspace-name",
...     repository_directory="/path/to/repo"
... )

With optional parameters

>>> from fabric_cicd import FabricWorkspace
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/your/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"],
...     environment="your-target-environment"
... )

With token credential

>>> from fabric_cicd import FabricWorkspace
>>> from azure.identity import ClientSecretCredential
>>> client_id = "your-client-id"
>>> client_secret = "your-client-secret"
>>> tenant_id = "your-tenant-id"
>>> token_credential = ClientSecretCredential(
...     client_id=client_id, client_secret=client_secret, tenant_id=tenant_id
... )
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/your/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"],
...     token_credential=token_credential
... )

base_api_url property

base_api_url: str

Construct the base API URL using constants.

FeatureFlag

Bases: str, Enum

Enumeration of supported feature flags for fabric-cicd.

CONTINUE_ON_SHORTCUT_FAILURE class-attribute instance-attribute

CONTINUE_ON_SHORTCUT_FAILURE = 'continue_on_shortcut_failure'

Set to allow deployment to continue even when shortcuts fail to publish.

DISABLE_PRINT_IDENTITY class-attribute instance-attribute

DISABLE_PRINT_IDENTITY = 'disable_print_identity'

Set to disable printing the executing identity name.

DISABLE_WORKSPACE_FOLDER_PUBLISH class-attribute instance-attribute

DISABLE_WORKSPACE_FOLDER_PUBLISH = 'disable_workspace_folder_publish'

Set to disable deploying workspace sub folders.

ENABLE_ENVIRONMENT_VARIABLE_REPLACEMENT class-attribute instance-attribute

ENABLE_ENVIRONMENT_VARIABLE_REPLACEMENT = (
    "enable_environment_variable_replacement"
)

Set to enable the use of pipeline variables.

ENABLE_EVENTHOUSE_UNPUBLISH class-attribute instance-attribute

ENABLE_EVENTHOUSE_UNPUBLISH = 'enable_eventhouse_unpublish'

Set to enable the deletion of Eventhouses.

ENABLE_EXCLUDE_FOLDER class-attribute instance-attribute

ENABLE_EXCLUDE_FOLDER = 'enable_exclude_folder'

Set to enable folder-based exclusion during publish operations.

ENABLE_EXPERIMENTAL_FEATURES class-attribute instance-attribute

ENABLE_EXPERIMENTAL_FEATURES = 'enable_experimental_features'

Set to enable experimental features, such as selective deployments.

ENABLE_INCLUDE_FOLDER class-attribute instance-attribute

ENABLE_INCLUDE_FOLDER = 'enable_include_folder'

Set to enable folder-based inclusion during publish operations.

ENABLE_ITEMS_TO_INCLUDE class-attribute instance-attribute

ENABLE_ITEMS_TO_INCLUDE = 'enable_items_to_include'

Set to enable selective publishing/unpublishing of items.

ENABLE_KQLDATABASE_UNPUBLISH class-attribute instance-attribute

ENABLE_KQLDATABASE_UNPUBLISH = 'enable_kqldatabase_unpublish'

Set to enable the deletion of KQL Databases (attached to Eventhouses).

ENABLE_LAKEHOUSE_UNPUBLISH class-attribute instance-attribute

ENABLE_LAKEHOUSE_UNPUBLISH = 'enable_lakehouse_unpublish'

Set to enable the deletion of Lakehouses.

ENABLE_RESPONSE_COLLECTION class-attribute instance-attribute

ENABLE_RESPONSE_COLLECTION = 'enable_response_collection'

Set to enable collection of API responses during publish operations.

ENABLE_SHORTCUT_EXCLUDE class-attribute instance-attribute

ENABLE_SHORTCUT_EXCLUDE = 'enable_shortcut_exclude'

Set to enable selective publishing of shortcuts in a Lakehouse.

ENABLE_SHORTCUT_PUBLISH class-attribute instance-attribute

ENABLE_SHORTCUT_PUBLISH = 'enable_shortcut_publish'

Set to enable deploying shortcuts with the lakehouse.

ENABLE_SQLDATABASE_UNPUBLISH class-attribute instance-attribute

ENABLE_SQLDATABASE_UNPUBLISH = 'enable_sqldatabase_unpublish'

Set to enable the deletion of SQL Databases.

ENABLE_WAREHOUSE_UNPUBLISH class-attribute instance-attribute

ENABLE_WAREHOUSE_UNPUBLISH = 'enable_warehouse_unpublish'

Set to enable the deletion of Warehouses.

ItemType

Bases: str, Enum

Enumeration of supported Microsoft Fabric item types.

append_feature_flag

append_feature_flag(feature: str) -> None

Append a feature flag to the global feature_flag set.

Parameters:

Name Type Description Default
feature str

The feature flag to be included.

required

Examples:

Basic usage

>>> from fabric_cicd import append_feature_flag
>>> append_feature_flag("enable_lakehouse_unpublish")

change_log_level

change_log_level(level: str = 'DEBUG') -> None

Sets the log level for all loggers within the fabric_cicd package. Currently only supports DEBUG.

Parameters:

Name Type Description Default
level str

The logging level to set (e.g., DEBUG).

'DEBUG'

Examples:

Basic usage

>>> from fabric_cicd import change_log_level
>>> change_log_level("DEBUG")

configure_external_file_logging

configure_external_file_logging(external_logger: Logger) -> None

Configure fabric_cicd package logging to integrate with an external logger's file handler. This is an advanced alternative to the default file logging configuration when level is set to DEBUG via change_log_level().

Extracts the file handler from the provided logger and configures fabric_cicd to append only DEBUG logs (e.g., API request/response details) to the same file. The external logger retains full ownership of the handler, including file rotation (if applicable) and lifecycle management.

Note
  • This function resets logging configuration. Use as an alternative to change_log_level() or disable_file_logging(), not in combination

  • Only DEBUG logs from the fabric_cicd package are written to the log file. Exception messages are displayed on the console, but full stack traces are not written to the external log file

  • Console output remains at INFO level (default fabric_cicd console behavior)

Parameters:

Name Type Description Default
external_logger Logger

The external logger instance that has a FileHandler or RotatingFileHandler attached.

required

Raises:

Type Description
ValueError

If no file handler is found on the provided logger.

Examples:

General usage:

>>> import logging
>>> from logging.handlers import RotatingFileHandler
>>> from fabric_cicd import configure_external_file_logging
...
>>> # Set up your own logger with a file handler
>>> my_logger = logging.getLogger("MyApp")
>>> handler = RotatingFileHandler("app.log", maxBytes=5*1024*1024, backupCount=7)
>>> handler.setFormatter(logging.Formatter("%(asctime)s - %(levelname)s - %(message)s"))
>>> my_logger.addHandler(handler)
...
>>> # Configure fabric_cicd to use the same file
>>> configure_external_file_logging(my_logger)

deploy_with_config

deploy_with_config(
    config_file_path: str,
    environment: str = "N/A",
    token_credential: Optional[TokenCredential] = None,
    config_override: Optional[dict] = None,
) -> DeploymentResult

Deploy items using YAML configuration file with environment-specific settings. This function provides a simplified deployment interface that loads configuration from a YAML file and executes deployment operations based on environment-specific settings. It constructs the necessary FabricWorkspace object internally and handles publish/unpublish operations according to the configuration.

Parameters:

Name Type Description Default
config_file_path str

Path to the YAML configuration file as a string.

required
environment str

Environment name to use for deployment (e.g., 'dev', 'test', 'prod'), if missing defaults to 'N/A'.

'N/A'
token_credential Optional[TokenCredential]

Optional Azure token credential for authentication.

None
config_override Optional[dict]

Optional dictionary to override specific configuration values.

None

Returns:

Name Type Description
DeploymentResult DeploymentResult

A result object containing the deployment status and message. The status will be DeploymentStatus.COMPLETED on success.

Raises:

Type Description
InputError

If configuration file is invalid or environment not found.

FileNotFoundError

If configuration file doesn't exist.

Examples:

Basic usage

>>> from fabric_cicd import deploy_with_config
>>> result = deploy_with_config(
...     config_file_path="workspace/config.yml",
...     environment="prod"
... )
>>> print(result.status)  # DeploymentStatus.COMPLETED
>>> print(result.message) # "Deployment completed successfully"

With custom authentication

>>> from fabric_cicd import deploy_with_config
>>> from azure.identity import ClientSecretCredential
>>> credential = ClientSecretCredential(tenant_id, client_id, client_secret)
>>> result = deploy_with_config(
...     config_file_path="workspace/config.yml",
...     environment="prod",
...     token_credential=credential
... )

With override configuration

>>> from fabric_cicd import deploy_with_config
>>> from azure.identity import ClientSecretCredential
>>> credential = ClientSecretCredential(tenant_id, client_id, client_secret)
>>> result = deploy_with_config(
...     config_file_path="workspace/config.yml",
...     environment="prod",
...     config_override={
...         "core": {
...             "item_types_in_scope": ["Notebook"]
...         },
...         "publish": {
...             "skip": {
...                 "prod": False
...             }
...         }
...     }
... )

disable_file_logging

disable_file_logging() -> None

Disable file logging for the fabric_cicd package.

When called, no log file will be created and only console logging will occur at the default INFO level.

Note
  • This function is intended to be used as an alternative to change_log_level() or configure_external_file_logging(), not in combination with them as this will reset logging configurations to INFO-level console output only.
  • Exception messages will still be displayed on the console, but full stack traces will not be written to any log file or console.

Examples:

Basic usage

>>> from fabric_cicd import disable_file_logging
>>> disable_file_logging()

publish_all_items

publish_all_items(
    fabric_workspace_obj: FabricWorkspace,
    item_name_exclude_regex: Optional[str] = None,
    folder_path_exclude_regex: Optional[str] = None,
    folder_path_to_include: Optional[list[str]] = None,
    items_to_include: Optional[list[str]] = None,
    shortcut_exclude_regex: Optional[str] = None,
) -> Optional[dict]

Publishes all items defined in the item_type_in_scope list of the given FabricWorkspace object.

Parameters:

Name Type Description Default
fabric_workspace_obj FabricWorkspace

The FabricWorkspace object containing the items to be published.

required
item_name_exclude_regex Optional[str]

Regex pattern to exclude specific items from being published.

None
folder_path_exclude_regex Optional[str]

Regex pattern matched against folder paths (e.g., "/folder_name") to exclude folders and their items from being published.

None
folder_path_to_include Optional[list[str]]

List of folder paths in the format "/folder_name"; only the specified folders and their items will be published.

None
items_to_include Optional[list[str]]

List of items in the format "item_name.item_type" that should be published.

None
shortcut_exclude_regex Optional[str]

Regex pattern to exclude specific shortcuts from being published in lakehouses.

None

Returns:

Type Description
Optional[dict]

Dict containing all API responses if the "enable_response_collection" feature flag is enabled and responses were collected, otherwise None.

folder_path_exclude_regex

This is an experimental feature in fabric-cicd. Use at your own risk as selective deployments are not recommended due to item dependencies. Cannot be used together with folder_path_to_include for the same environment. To enable this feature, see How To -> Optional Features for information on which flags to enable.

folder_path_to_include

This is an experimental feature in fabric-cicd. Use at your own risk as selective deployments are not recommended due to item dependencies. Cannot be used together with folder_path_exclude_regex for the same environment. To enable this feature, see How To -> Optional Features for information on which flags to enable.

items_to_include

This is an experimental feature in fabric-cicd. Use at your own risk as selective deployments are not recommended due to item dependencies. To enable this feature, see How To -> Optional Features for information on which flags to enable.

shortcut_exclude_regex

This is an experimental feature in fabric-cicd. Use at your own risk as selective shortcut deployments may result in missing data dependencies. To enable this feature, see How To -> Optional Features for information on which flags to enable.

Examples:

Basic usage

>>> from fabric_cicd import FabricWorkspace, publish_all_items
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)

With regex name exclusion

>>> from fabric_cicd import FabricWorkspace, publish_all_items
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> exclude_regex = ".*_do_not_publish"
>>> publish_all_items(workspace, item_name_exclude_regex=exclude_regex)

With folder exclusion

>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_exclude_folder")
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> folder_exclude_regex = "^/legacy"
>>> publish_all_items(workspace, folder_path_exclude_regex=folder_exclude_regex)

With folder inclusion

>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_include_folder")
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> folder_path_to_include = ["/subfolder"]
>>> publish_all_items(workspace, folder_path_to_include=folder_path_to_include)

With items to include

>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_items_to_include")
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> items_to_include = ["Hello World.Notebook", "Hello.Environment"]
>>> publish_all_items(workspace, items_to_include=items_to_include)

With shortcut exclusion

>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_shortcut_exclude")
>>> append_feature_flag("enable_shortcut_publish")
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Lakehouse"]
... )
>>> shortcut_exclude_regex = "^temp_.*"  # Exclude shortcuts starting with "temp_"
>>> publish_all_items(workspace, shortcut_exclude_regex=shortcut_exclude_regex)

With response collection

>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_response_collection")
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> responses = publish_all_items(workspace)
>>> # Access all responses
>>> print(responses)
>>> # Access individual item responses
>>> notebook_response = workspace.responses["Notebook"]["Hello World"]

unpublish_all_orphan_items

unpublish_all_orphan_items(
    fabric_workspace_obj: FabricWorkspace,
    item_name_exclude_regex: str = "^$",
    items_to_include: Optional[list[str]] = None,
) -> None

Unpublishes all orphaned items not present in the repository except for those matching the exclude regex.

Parameters:

Name Type Description Default
fabric_workspace_obj FabricWorkspace

The FabricWorkspace object containing the items to be published.

required
item_name_exclude_regex str

Regex pattern to exclude specific items from being unpublished. Default is '^$' which will exclude nothing.

'^$'
items_to_include Optional[list[str]]

List of items in the format "item_name.item_type" that should be unpublished.

None
items_to_include

This is an experimental feature in fabric-cicd. Use at your own risk as selective unpublishing is not recommended due to item dependencies. To enable this feature, see How To -> Optional Features for information on which flags to enable.

Examples:

Basic usage

>>> from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)
>>> unpublish_orphaned_items(workspace)

With regex name exclusion

>>> from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)
>>> exclude_regex = ".*_do_not_delete"
>>> unpublish_orphaned_items(workspace, item_name_exclude_regex=exclude_regex)

With items to include

>>> from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_items_to_include")
>>> workspace = FabricWorkspace(
...     workspace_id="your-workspace-id",
...     repository_directory="/path/to/repo",
...     item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)
>>> items_to_include = ["Hello World.Notebook", "Run Hello World.DataPipeline"]
>>> unpublish_orphaned_items(workspace, items_to_include=items_to_include)