Optional Features¶

fabric-cicd has an expected default flow; however, there will always be cases where overriding default behavior is required.

Feature Flags¶

For scenarios that aren't supported by default, fabric-cicd offers feature flags. Below is an exhaustive list of currently supported features, grouped by category.

Flags marked as Experimental (☑️) require the enable_experimental_features flag to be set in addition to the specific flag:

from fabric_cicd import append_feature_flag
append_feature_flag("enable_experimental_features")
append_feature_flag("<specific_flag>")

Publish behavior

Unpublish behavior

Selective deployment

Diagnostics

Example

from fabric_cicd import append_feature_flag
append_feature_flag("enable_lakehouse_unpublish")
append_feature_flag("enable_warehouse_unpublish")
append_feature_flag("enable_environment_variable_replacement")
append_feature_flag("enable_response_collection")

Debugging¶

If an error arises, or you want full visibility into the API calls the library makes, enable debug logging:

from fabric_cicd import change_log_level
change_log_level("DEBUG")

Note: The "DEBUG" parameter can be omitted as it is the default value.

This writes all API calls to the terminal. To additionally capture logs and full stack traces to a fabric_cicd.error.log file, set the FABRIC_CICD_FILE_LOGGING_ENABLED environment variable:

export FABRIC_CICD_FILE_LOGGING_ENABLED=1

$env:FABRIC_CICD_FILE_LOGGING_ENABLED = "1"

For comprehensive debugging information, including how to use the error log file and debug scripts, see the Troubleshooting Guide.

Bulk Publish¶

To enable bulk publish, set both enable_experimental_features and enable_bulk_publish feature flags:

from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag

append_feature_flag("enable_experimental_features")
append_feature_flag("enable_bulk_publish")

workspace = FabricWorkspace(
    workspace_id="your-workspace-id",
    repository_directory="/path/to/repo",
    item_type_in_scope=["Notebook", "DataPipeline", "Environment"],
    token_credential=token_credential,
)

publish_all_items(workspace)

core:
    workspace_id: "your-workspace-id"
    repository_directory: "/path/to/repo"
    item_types_in_scope:
        - Notebook
        - DataPipeline
        - Environment

features:
    - enable_experimental_features
    - enable_bulk_publish

from fabric_cicd import deploy_with_config
from azure.identity import AzureCliCredential

deploy_with_config(
    config_file_path="/path/to/config.yml",
    token_credential=AzureCliCredential(),
)

How it works¶

With bulk publishing, there is no predefined order of item types. The API leverages a dependency graph under the hood to determine the correct publishing sequence. As long as logical IDs are used to reference Fabric items, the API handles the rest — simplifying dependency management overhead. This may also reduce the complexity of your parameter file, though parameterization remains a key feature for edge cases and environment-specific customizations.

Since this feature is experimental, it is recommended for non-production environments only. We encourage you to use this period to provide feedback and help shape the bulk publish experience. The initial release does not support all fabric-cicd item types and lacks support for more advanced parameterization features, specifically dynamic replacement variables ($workspace, $items).

Authentication Requirements¶

When authenticating with a service principal or managed identity, all item types in a bulk call must support non-interactive authentication. If any item type in the batch does not, the entire call fails. Ensure your item_type_in_scope only includes item types with matching auth support.

Automatic Fallback to Standard Publish¶

Bulk publish will automatically fall back to standard publish mode when any of the following conditions are detected. A warning is logged when this occurs.

• Unsupported item types in scope: DataBuildToolJob and Warehouse are not supported. If either is included in item_type_in_scope, the entire deployment uses standard publish.
• No item_type_in_scope specified: Bulk publish requires an explicit item_type_in_scope. When omitted, all supported item types are included — which inevitably contains bulk unsupported types — so standard publish is used instead.
• Dynamic parameter variables: Parameter files containing $workspace or $items replacement variables require runtime resolution, which is incompatible with bulk publish.

Check your deployment logs for the message "Falling back to standard deployment..." to confirm whether bulk publish was actually used.

Other Limitations¶

• Item count limit: A maximum of 1,000 items can be published in a single bulk call. Exceeding this limit raises an error. Publish time may increase with higher item counts.
• Items without logical IDs: Items that do not have a logical ID assigned (indicated by an all-zeros GUID in the item's .platform file) are not supported by bulk publish. Connect your workspace via git integration to ensure logical IDs are properly assigned before using bulk publish.
• Preview item types: Supported item types still in preview (e.g., Ontology) may produce errors for certain item definitions.

For common bulk publish errors and their solutions, see the Troubleshooting Guide.

Selective Deployment Features¶

By default, fabric-cicd performs a full deployment of all repository items. Selective deployment is an experimental feature due to the risk of deploying Fabric items that have dependencies on other items, which can result in broken deployments. These features support a range of filtering options, from broader folder-based selection to more granular item-level and shortcut-level filtering. To use these features, you must enable both the enable_experimental_features flag and the specific feature flag (if applicable). All selective deployment features are supported in both standard and bulk publish modes.

Warning: Selective deployment is not recommended due to potential issues with dependency management.

Folder-Level Filtering¶

A subset of items in the repository that exist within a Fabric workspace folder can be published using one of the following experimental features. Only one of these features can be applied during a deployment. Use case: selectively deploy a group of Fabric items (must be contained within folders). Folder-based item exclusion/inclusion is not supported in the unpublish scenario.

1. folder_path_exclude_regex

   • Optional parameter in publish_all_items(), set to a regex pattern that matches Fabric folder path(s) containing items in the repository.
   • Requires the enable_exclude_folder feature flag.
   • The folder path(s) and items contained within that match the regex will be excluded from the publish operation.
   • When using folder_path_exclude_regex, the pattern is matched using search() (substring match), so a pattern like subfolder1 will match any folder path containing "subfolder1" (e.g., /subfolder1, /subfolder1/subfolder2, /other/subfolder1).
   • To target a specific folder, use an anchored pattern (e.g., ^/subfolder1$) — this ensures only the exact folder path matches.
   • Child folders like /subfolder1/subfolder2 will also be excluded automatically since their parent folder was excluded, preserving a consistent folder hierarchy.

2. folder_path_to_include

   • Optional parameter in publish_all_items(), set to a list of strings that exactly match the folder path(s) containing items in the repository.
   • Requires the enable_include_folder feature flag.
   • Folder paths must start with / (e.g., /folder_name or /folder_name/nested_folder). The matching folder path(s) and their contained items will be included in the publish operation; any other items contained within Fabric folders will be excluded.
   • When using folder_path_to_include with nested paths (e.g., /subfolder1/subfolder2), ancestor folders (e.g., /subfolder1) are automatically created to preserve the correct folder hierarchy, but items directly under the ancestor folder are not published unless the ancestor folder is also explicitly included in the list.

Note: folder_path_exclude_regex and folder_path_to_include are mutually exclusive and cannot be used together for the same deployment. These filters are ignored when the disable_workspace_folder_publish feature flag is set. Root-level items (items not in any folder) are not impacted by either folder-level filter.

Item-Level Filtering¶

A subset of items in the repository can be published/unpublished using one of the following features. Both features are technically supported, but it is recommended to use one feature per deployment to avoid unexpected results.

1. item_name_exclude_regex

   • Optional parameter in publish_all_items() and unpublish_all_orphan_items(), set to a regex pattern that matches item name(s) found in the repository.
   • This feature does not require any feature flags.
   • Fabric items that match the regex will be excluded from the publish/unpublish operation.

2. items_to_include

   • Optional parameter in publish_all_items() and unpublish_all_orphan_items(), set to a list of strings that exactly match items in the repository.
   • Requires the enable_items_to_include feature flag.
   • Must be in the format: "item_name.item_type". The matching item(s) will be included in the publish/unpublish operation.

Note: item_name_exclude_regex and items_to_include can be applied to items within Fabric folders or standalone items. Item-level filtering can be combined with folder-level filtering, but be cautious when using both to avoid unexpected results.

Filter Precedence¶

Filters are evaluated in the following order:

1. items_to_include — Scope is narrowed upfront; only explicitly listed items proceed to further checks
2. item_name_exclude_regex — Items matching the regex are excluded
3. folder_path_exclude_regex — Items in matching folders are excluded
4. folder_path_to_include — Only items in specified folders are published

Note: folder_path_exclude_regex and folder_path_to_include are mutually exclusive — only one can be used per deployment. Root-level items (items not in any folder) are not impacted by either folder-level filter. When items_to_include is combined with exclusion filters, an item must first be in the include list before exclusion filters are evaluated against it.

Lakehouse Shortcut Filtering¶

Shortcuts are items associated with Lakehouse items and can be selectively published using the following experimental feature:

1. shortcut_exclude_regex
   • Optional parameter in publish_all_items(), set to a regex pattern that matches the shortcut name(s) found within Lakehouse item(s) in the repository.
   • Requires the enable_shortcut_exclude feature flag.
   • The matching shortcut(s) will be excluded from publishing.

Note: This feature can be applied along with the other selective deployment features — please be cautious when using to avoid unexpected results.

Git-Based Change Detection¶

get_changed_items() is a public utility function that uses git diff to detect which Fabric items have been added, modified, or renamed relative to a given git reference. It returns a list of strings in "item_name.item_type" format that can be passed directly to items_to_include in publish_all_items().

While get_changed_items() itself requires no feature flags, passing its output to items_to_include requires the experimental feature flags.

Important: If get_changed_items() returns an empty list (no changes detected), do not call publish_all_items() without an explicit items_to_include list, as this would default to a full deployment. Always guard against the empty-list case:

from fabric_cicd import FabricWorkspace, publish_all_items, get_changed_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=["Notebook", "DataPipeline"],
    token_credential=token_credential,  # or any other TokenCredential
)

changed = get_changed_items(workspace.repository_directory)

if changed:
    publish_all_items(workspace, items_to_include=changed)
else:
    print("No changed items detected — skipping deployment.")

To compare against a branch or a specific commit instead of the previous commit, pass a custom git_compare_ref:

changed = get_changed_items(workspace.repository_directory, git_compare_ref="main")

Note: get_changed_items() returns only items that were modified or added (i.e., candidates for publishing). It does not return deleted items. Passing items_to_include to publish_all_items() requires enabling the enable_experimental_features and enable_items_to_include feature flags.