Closes #754 - Add Workspace Private Link troubleshooting documentation

[Copilot]

No documentation existed for deploying to workspaces with "Allow connections only from workspace level private links" enabled — a recurring pain point (issues #660, #754) requiring maintainer guidance each time.

Changes

• docs/how_to/troubleshooting.md — Added #### Workspace Private Link Connectivity under "Common Issues and Solutions" covering:
  • Symptom: 'Request is denied due to inbound communication policy'
  • FQDN format: https://{workspace_id_no_dashes}.z{first_2_chars}.w.api.fabric.microsoft.com
  • Python API fix: override constants.DEFAULT_API_ROOT_URL before instantiating FabricWorkspace
  • config.yml fix: set DEFAULT_API_ROOT_URL in the constants section (supports per-environment values)
  • Caveat: workspace_id must be used (not workspace_name) — name resolution calls the public API, which is blocked behind the private link
  • Link to Microsoft private link docs

Python API example:

import fabric_cicd.constants as constants

workspace_id = "your-workspace-id"
constants.DEFAULT_API_ROOT_URL = (
    f"https://{workspace_id.replace('-', '')}"
    f".z{workspace_id[0:2]}.w.api.fabric.microsoft.com"
)

config.yml example:

constants:
    DEFAULT_API_ROOT_URL:
        dev: "https://{dev_workspace_fqdn}"
        prod: "https://{prod_workspace_fqdn}"

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• releases.astral.sh
  • Triggering command: /home/REDACTED/.local/bin/uv uv sync --dev -q (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Problem

There is no documentation anywhere in docs/ about deploying to Fabric Workspaces that have workspace-level private links enabled. This has been a recurring pain point for users — at least two separate issues were filed (#660 and #754) by different users hitting this problem, both requiring maintainer guidance to resolve.

When a workspace has "Allow connections only from workspace level private links" enabled, the default public API endpoint (https://api.fabric.microsoft.com) is blocked. Users see the error:

"Request is denied due to inbound communication policy."

The workaround is to override constants.DEFAULT_API_ROOT_URL with the workspace's Fully Qualified Domain Name (FQDN), but this is non-obvious without reading source code or closed issues.

Requested Change

Add a new subsection under "Common Issues and Solutions" in docs/how_to/troubleshooting.md, after the existing "API Rate Limiting" section (around line 187). The new section should be titled something like #### Workspace Private Link Connectivity and follow the same Symptom/Solution pattern as the other entries in that section.

The section should cover:

1. Symptom: The error message users will see — "Request is denied due to inbound communication policy" when deploying to a workspace with private links enabled.

2. Explanation: When a workspace has "Allow connections only from workspace level private links" enabled, the default api.fabric.microsoft.com endpoint is inaccessible. The workspace-specific FQDN must be used instead.

3. FQDN URL format: https://{workspaceid_no_dashes}.z{first_2_chars}.w.api.fabric.microsoft.com — where {workspaceid_no_dashes} is the workspace ID with dashes removed, and {first_2_chars} are the first two characters of the workspace ID.

4. Solution using the Python API — override constants.DEFAULT_API_ROOT_URL before creating the FabricWorkspace object:

import fabric_cicd.constants as constants

workspace_id = "your-workspace-id"
constants.DEFAULT_API_ROOT_URL = (
    f"https://{workspace_id.replace('-', '')}"
    f".z{workspace_id[0:2]}.w.api.fabric.microsoft.com"
)

5. Solution using config.yml — set DEFAULT_API_ROOT_URL in the constants section, with environment-specific values if needed:

constants:
    DEFAULT_API_ROOT_URL:
        dev: "https://{dev_workspace_fqdn}"
        prod: "https://{prod_workspace_fqdn}"

6. Important caveat: Users must use workspace_id (not workspace_name) when initializing FabricWorkspace in a private link setup, because resolving a workspace name requires calling the public list-workspaces API which is blocked behind the private link.

7. Link to Microsoft docs: Workspace-level private links overview — Connecting to workspaces

References

• Issue Code migration with workspace level private link service is failing. #660: "Code migration with workspace level private link service is failing"
• Issue Support for using the workspace Fully Qualified Domain Name (FQDN) endpoint #754: "Support for using the workspace Fully Qualified Domain Name (FQDN) endpoint"

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Does fabric-cicd work for users who want to deploy items to a Fabric Workspace set up with private link?

Assistant: Yes, fabric-cicd works with Fabric Workspaces that use workspace-level private links, but it requires a workaround — you need to override the default API root URL to use the workspace's Fully Qualified Domain Name (FQDN) instead of the public api.fabric.microsoft.com endpoint.

The Problem

When a workspace has "Allow connections only from workspace level private links" enabled, the default public endpoint (https://api.fabric.microsoft.com/v1/workspaces/...) is blocked and returns:

"Request is denied due to inbound communication policy."

This was reported in #660 and #754, both of which are now closed.

The Workaround

Override constants.DEFAULT_API_ROOT_URL with the workspace's private link FQDN before creating the FabricWorkspace object:

from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items
import fabric_cicd.constants as constants

workspace_id = "your-workspace-id"

# Override the API root URL with the workspace FQDN
# Format: https://{workspace_id_no_dashes}.z{first_2_chars_of_workspace_id}.w.api.fabric.microsoft.com
constants.DEFAULT_API_ROOT_URL = f"https://{workspace_id.replace('-', '')}.z{workspace_id[0:2]}.w.api.fabric.microsoft.com"

target_workspace = FabricWorkspace(
    workspace_id=workspace_id,
    repository_directory="your-repo-directory",
    item_type_in_scope=["Notebook", "DataPipeline"],
)

publish_all_items(target_workspace)

The private link URL format is documented by Micro...

This pull request was created from Copilot chat.