microsoft/onelake-catalog-govern-cli

Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry x-ms-fabric-skill: onelake-catalog-govern-cli (az rest: --headers "x-ms-fabric-skill=onelake-catalog-govern-cli"), including every LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.

CRITICAL NOTES

1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

OneLake Catalog Govern — CLI (mode dispatcher)

One skill for the whole OneLake Catalog Govern family. The governance persona detail lives in four mode references loaded on demand. This top-level file exists to do three things and nothing else:

1. Pick the mode (the table below).
2. Surface the safety boundary and the irreversible-write gates so they are never diluted inside a large reference (see Irreversible operations).
3. Load exactly one mode reference and follow it.

Must/Prefer/Avoid

MUST DO

• Start with the audit cell for the caller's permission tier before any remediation.
• Apply the operation-specific confirmation gate in Step 2 before every destructive, irreversible, or broad write.
• Use the exact Fabric Admin, Core, Power BI, or Graph API surface documented for the selected procedure; do not treat a 401 or 403 as permission to bypass RBAC.
• State scope, exclusions, pagination completeness, and freshness caveats with every governance statistic.

PREFER

• Use least-privileged Core or Power BI APIs for data-owner actions instead of requiring tenant-admin rights.
• Report findings as evidence, consequence, recommended action, priority, and effort rather than returning an inventory dump.
• Sequence ownership and access-scope fixes before bulk assignment or labeling.

AVOID

• Do not mutate a tenant from an audit mode.
• Do not invent write APIs for endorsement, DLP policy, admin item deletion, or third-party item-identity assignment.
• Do not report asynchronous 202 responses as successful completion.

Step 1 — Pick the mode

Two axes → a 2×2 grid. Tier (which API surface you can reach) × action (audit vs. remediate). Each cell covers all three Govern pillars (health / protect / trust).

| | Audit (read-only) | Remediate (write) | |---|---|---| | Fabric Admin — /v1/admin/*, Fabric tenant admin only | admin-audit | admin-remediate | | Data owner / Operational admin — Core API + workspace/domain/capacity admins, no tenant admin | dataowner-audit | dataowner-remediate |

| Mode | Load this reference | Persona / permission tier | Scope | Reads | Writes | |---|---|---|---|---|---| | admin-audit | references/admin-audit.md | Fabric tenant admin (/v1/admin/*) | Whole tenant | ✅ | ❌ | | admin-remediate | references/admin-remediate.md | Fabric tenant admin only — every /v1/admin/* write requires the Fabric administrator role; domain & capacity admins do NOT qualify | Whole tenant | ✅ | ✅ | | dataowner-audit | references/dataowner-audit.md | Non-admin workspace or domain owner (Core API only) | Workspaces the caller administers (widen to accessible on request) | ✅ | ❌ | | dataowner-remediate | references/dataowner-remediate.md | Data owner who is also a domain / workspace / capacity admin — Core & Power BI API writes, no tenant admin | Objects the caller has the role on | ✅ | ✅ (self-service) |

Routing rules

• Start with an audit mode. Never remediate before establishing the current state. Audit → remediate within the same tier unless the caller's rights change.
• Choose the tier by the API surface the caller can reach, not by job title: a Fabric tenant admin who needs /v1/admin/* → the admin-* cell; a data owner acting through workspace/domain/capacity roles → the dataowner-* cell.
• "Fix / assign / apply / create / delete" → a remediate cell. Tenant-wide writes (create/delete domain, bulk domain assignment, domain roles, bulk labels, certification) → admin-remediate. Single-workspace assignToDomain or assignToCapacity, applying tags, setting descriptions, refresh, and item identity → dataowner-remediate (these need object-scoped roles, not tenant admin).
• The read/write split is a safety boundary: an audit mode must not mutate a tenant even if a prompt asks it to. If you are in an audit mode and the user asks for a write, switch to the matching remediate mode explicitly — do not improvise a write.

Tier = API surface, not role title. The admin-* modes call /v1/admin/* and require the Fabric tenant administrator role (Fabric admin / Power Platform admin / M365 global admin) — domain, capacity and workspace admins do NOT qualify, even for their own domain. The dataowner-* modes use the Core/Power BI APIs scoped to roles the caller already holds on specific objects. A domain/WS/capacity admin who is not a Fabric tenant admin therefore lives entirely in the dataowner-* cells; they cross into admin-* only if they are separately granted the Fabric tenant admin role. Roles are scope branches inside a mode; only a different API surface justifies a separate mode.

⚠️ Known Fabric gap — scoped governance has no non-admin API. A domain admin or workspace admin who is not a Fabric tenant admin currently has no API path to their scoped governance posture: /v1/admin/* rejects them (it needs the tenant Fabric admin role — see the Assign Domain Workspaces permission note), and the Core API has no endpoint that lists the workspaces in a domain or returns a domain's governance state. dataowner-audit can only report on workspaces the caller can directly access — not "my whole domain." If a domain/WS admin asks for their scoped govern details, state this limitation up front and do not route them into an admin-* mode that will 401/403.

Step 2 — Irreversible operations — MUST-DO gates (read before any write)

⚠️ Why this lives here and not only in the mode reference. These are terminal, hard-to-undo acts. When such an instruction sits as one line among dozens inside a large reference file, it gets read but silently skipped. It is repeated here, in the auto-loaded dispatcher body, so the gate fires before the write — not after. Full procedures remain in the remediate mode references (admin-remediate.md, dataowner-remediate.md); this is the checklist, not a substitute.

Before executing any of these in either remediate mode, the gate MUST pass. The Mode column shows which cell owns the operation:

| Irreversible / terminal act | Mode | Gate that MUST fire first | |---|---|---| | Delete a domain (DELETE /v1/admin/domains/{id}) | admin | Check for subdomains (parentDomainId) and assigned-workspace counts for the domain and every subdomain. If any workspaces would be orphaned, STOP and get explicit user confirmation naming the affected domains/workspaces. The REST API has no cascade-block — the check is yours. See domain-crud.md § Deleting a Domain. | | Delete a tag definition | admin | Report how many items carry it first — deletion detaches it everywhere with no undo. | | Bulk-assign workspaces to a domain | admin | Check each target's current domainId and warn before silently overriding an existing assignment. Dry-run the target list first. | | Remove a principal from a domain role | admin | Confirm it will not leave the domain ownerless; name the principal being removed. | | Bulk sensitivity-label change | admin | Dry-run: show the exact affected item list and before/after label, get confirmation. No service principal / managed identity — the call will fail. | | Write a tenant setting (e.g. enable certification) | admin | Read the current value and show it, then the proposed value — tenant-wide blast radius. | | Assign / unassign one workspace to a domain | dataowner | A move is a reassignment — confirm the current domainId and name the domain it is leaving. Needs domain-contributor and workspace-Admin; say which is missing on failure. | | Reassign item ownership (item identity, preview) | dataowner | Assigns to the caller only; needs Write on the item and its children. Confirm the intended identity. | | Assign a workspace to a capacity | dataowner | Needs workspace Admin plus capacity Contributor/Admin. Async 202 — do not report success from the 202 alone; poll to a terminal state. |

Do not promise a remediation that has no write API. Endorsement, DLP policies, and item deletion by a tenant admin have no write route. For those, produce a contact list of who can act — see references/admin-remediate/no-write-api-escalation.md § Route a Finding to Someone Who Can Fix It.

Step 3 — Load the reference and proceed

Load only the one mode reference matching Step 1 and follow it end to end. Shared background and every leaf procedure are indexed here so each file is one hop from this dispatcher. References are leaves: after loading one, return to this index when another procedure is needed.

Shared governance references

• Govern pillars — the three pillars, what "good" looks like, and reporting conventions
• Governance data sources — verified API field coverage, product blind spots, and reporting conventions
• Governance roles — permission tiers, domain/workspace roles, and insight refresh lag
• Catalog concepts — the entity model and API-backed versus conceptual terms
• ../../common/COMMON-CORE.md — repository-level Fabric REST patterns, auth, and pagination
• ../../common/COMMON-CLI.md — repository-level CLI implementation (az rest, pagination, auth recipes)

Mode dispatchers

• Admin audit — tenant-wide read-only governance assessment
• Admin audit scope — governable denominator, exclusions, and known blind spots
• Admin audit assessment — end-to-end evaluative workflow, prioritization, and deliverable contract
• Admin remediate — tenant-wide guarded writes through Admin APIs
• Data-owner audit — caller-scoped read-only checks through Core APIs
• Data-owner remediate — least-privileged writes through Core and Power BI APIs

Admin audit procedures

• Domain health — assignment, ownership, contributor scope, and metadata
• Workspace health — empty/inactive workspaces and admin bus factor
• Capacity health — capacity state, ownership, and domain alignment
• Item inventory — Admin versus scanner inventory and field coverage
• Item health — ownership, staleness, and refresh state
• Protect coverage — sensitivity labels and DLP visibility
• Trust curation — descriptions, endorsement, and tag coverage

Admin remediation procedures

• Domain lifecycle — create, update, and safely delete domains
• Workspace assignment — choose and dry-run bulk assignment methods
• Domain roles — assign admins and contributors
• Tags — manage tenant tag definitions
• Item sensitivity labels — guarded bulk label changes
• Domain default labels — prevent new unlabeled backlog
• Trust remediation — certification enablement and delegated actions
• No-write escalation — identify missing APIs and named owners who can act

Data-owner procedures

• Data-owner workspace health — empty and inactive workspace checks within caller scope

Examples

Audit our tenant's OneLake catalog governance posture and prioritize the findings.

Which workspaces I administer are not assigned to a domain?

Show a dry run for assigning these workspaces to the Finance domain, including current assignments.

Find unlabeled items tenant-wide and explain which remediations require a tenant admin versus a data owner.