Common Flows

Onboarding New Item Types

Here are some guidelines when adding support for a new item type in fabric-cicd:

1. Create a new issue, titled: "Support {new item type}" and add the "new item type" label
2. Check the Microsoft public API docs to see if the item type is supported by the Fabric REST APIs
3. If not clear on whether it is supported or if there are any concerns/blockers, start a discussion in the designated issue (the "blocked" label may be added if actual blockers are confirmed)
4. If no blockers, you may proceed to create a PR upon receiving acknowledgement in the issue from an admin of fabric-cicd
5. Before adding code, it is recommended to use the debug scripts available, such as debug_api.py and debug_local.py to understand the source control structure and item definition for the given item type, test a basic deployment, and determine whether additional logic is required to deploy the item type.

Adding new item types:

• Create a new file for the new item type under the _items module following the naming convention _{itemtype}.py
• Reference other item type files to understand the flow, at a minimum the file should contain the following:

 """Functions to process and deploy {Item Type} item."""

import logging

from fabric_cicd import FabricWorkspace

logger = logging.getLogger(__name__)


def publish_{itemtype-plural}(fabric_workspace_obj: FabricWorkspace) -> None:
    """
    Publishes all {item type} items from the repository.

    Args:
        fabric_workspace_obj: The FabricWorkspace object containing the items to be published
    """
    item_type = "{Item Type}"

    for item_name in fabric_workspace_obj.repository_items.get(item_type, {}):
        fabric_workspace_obj._publish_item(item_name=item_name, item_type=item_type)

• It's possible the specific item type may require additional parameters added to _publish_item(). If custom logic is required for pre/post-processing of items during deployment, it should be added in the applicable item type file. For custom logic that needs to be used within FabricWorkspace, use the following function:

# Inside publish_{itemtype-plural} function
fabric_workspace_obj._publish_item(
            item_name=item_name,
            item_type=item_type,
            func_process_file=func_process_file,
        )

def func_process_file(workspace_obj: FabricWorkspace, item_obj: Item, file_obj: File) -> str:
    """
    Custom file processing for report items.

    Args:
        workspace_obj: The FabricWorkspace object.
        item_obj: The item object.
        file_obj: The file object.
    """
    # Insert custom logic here that modifies the file content
    ####
    ####
    # Return the modified file contents
    return file_obj.contents

• Add the new publish_{itemtype-plural}() function to _init_.py in _items
• Then add the function to publish_all_items() in the publish.py file. Ensure the publish_{itemtype-plural}() function is added in a logical order, it must be called BEFORE any item types that can reference this particular item type, ex: Environments published before Notebooks and Notebooks published before Data Pipelines
• Once order is set in publish_all_items() add the item type to a list defined within unpublish_all_orphan_items() in publish.py. The order of item types follows the reverse ordering defined in publish_all_items() so the item type should be added in a specific position in the list, ex: Data Pipeline gets unpublished before Notebooks and Notebooks get unpublished before Environments
• Be sure to use the debugging scripts available in devtools to test end to end deployment scenarios of the new item type
• Document the new item type support in the item_types.md page under how_to. Include information on parameterization requirements and other critical points relevant to deploying this item type

Updating Documentation

The public documentation for fabric-cicd currently lives on GitHub pages. Here's a breakdown of the pages:

Home:

• Provides an overview of the project, base expectations, supported item types, installation, and example usage

How To:

• Provides guidance on how to get started with fabric-cicd (including installation, authentication requirements, repository directory set up, and background on GIT flow)
• Information on supported item types
• How to use configuration deployment approach
• How to use parameterization
• Information on optional features

Examples:

• Code samples of how to use fabric-cicd library within the context of authentication, deployment variables, and release pipeline

Code Reference:

• Provides information on key code blocks in fabric-cicd, including FabricWorkspace class, publish_all_items(), unpublish_all_orphan_items(), deploy_with_config() functions, etc.

Contribution:

• Information on the open-source contribution process in fabric-cicd

Changelog:

• Release notes for fabric-cicd

About:

• Information about the fabric-cicd project, including topics on project support, security, and license

When making documentation updates, create a new GitHub issue using the documentation issue template. Ensure the new/updated documentation information is placed in the relevant page(s). Use the following command to test and validate documentation changes during development:

uv run mkdocs serve