Skip to content

Code Reference

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

Classes:

Name Description
DeploymentResult

Structured 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, responses: Optional[dict] = None
)

Structured result of a config-based deployment operation.

Returned by deploy_with_config on success. On failure, an instance is attached to the raised exception as e.deployment_result with status set to DeploymentStatus.FAILED.

Attributes:

Name Type Description
status DeploymentStatus

The deployment status.

message str

A human-readable message describing the result.

responses Optional[dict]

Optional dictionary of API response data from the deployment.

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.

FAILED class-attribute instance-attribute

FAILED = 'failed'

Deployment failed due to one or more 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, message, and responses (opt-in). The status will be DeploymentStatus.COMPLETED on success. The responses field contains API response data when the enable_response_collection feature flag is enabled and responses were collected, otherwise None.

Raises:

Type Description
InputError

If configuration is invalid, environment not found, or input validation fails.

ConfigValidationError

If configuration file is missing or fails structural validation.

Note

On failure, the raised exception will have a deployment_result attribute containing a DeploymentResult with status set to DeploymentStatus.FAILED, message set to the error description, and responses containing any partial API responses collected before the failure (requires the enable_response_collection feature flag, otherwise None).

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"
>>> print(result.responses) # API responses if collected and feature flag enabled

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
...             }
...         }
...     }
... )

Handling deployment failures

>>> from fabric_cicd import deploy_with_config
>>> try:
...     result = deploy_with_config(
...         config_file_path="workspace/config.yml",
...         environment="prod"
...     )
...     print(result.status)    # DeploymentStatus.COMPLETED
...     print(result.message)   # "Deployment completed successfully"
...     print(result.responses) # API responses if collected (feature flag enabled via config file)
... except Exception as e:
...     print(e.deployment_result.status)    # DeploymentStatus.FAILED
...     print(e.deployment_result.message)   # Original error message
...     print(e.deployment_result.responses) # Partial API responses or None

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)