Skip to content

Enterprise Version Management

As a team_admin or enterprise_admin, you control how artifact versions flow across scopes in your organization. This guide covers the admin version management dashboard, how to interpret divergence, how to approve or reject promotion requests, and how to use force-sync and bulk operations safely.

Enterprise Edition only. The features described here require SKILLMEAT_EDITION=enterprise and a user account with the team_admin or enterprise_admin role. See the Edition Feature Matrix for more.

Dashboard Overview

Navigate to Admin → Version Management to open the version management dashboard. The dashboard provides a centralized view of every artifact scope in your organization, so you can track version health and act on issues without jumping between individual projects.

Version management admin dashboard

The Scope Table

The main panel is a sortable, filterable table where each row represents one artifact scope — the combination of an artifact and the organizational scope (user, team, or organization) it belongs to.

Column What it shows
Artifact Artifact name and type badge
Scope Level user, team, or org — the tier at which this version lives
Owner Username, team name, or org slug
Version Currently active version hash (short SHA)
Diverged Whether the scope's version differs from the baseline for that tier
Pending Promotion Badge count of promotion requests waiting for review
Last Synced Timestamp of the most recent successful sync to this scope
Actions Promote, Force Sync, View History

Sorting and Filtering

Click any column header to sort. Use the filter bar above the table to narrow rows:

  • Scope level — show only user, team, or org scopes
  • Diverged only — show scopes where the version hash does not match the scope baseline
  • Pending promotions — show scopes with at least one open promotion request
  • Artifact name — free-text search across artifact names
  • Owner — filter by a specific user, team, or org

The active filter set is preserved in the URL, so you can bookmark views such as "all diverged org-level scopes" and share them with other admins.

Version management filter bar showing diverged scopes filtered

Understanding Divergence

What "Diverged" Means

Every artifact scope has a baseline — the canonical version for that tier. For org-level scopes, the baseline is the version pinned by the organization. For team-level scopes, the baseline is typically the version promoted from the org tier. For user-level scopes, the baseline is the version promoted from the team tier.

A scope is diverged when its current version hash does not match its tier's baseline. This can happen because:

  • A user or team admin made a local change and did not promote it upward
  • A promotion was approved at a higher tier but has not yet propagated down
  • A force-sync was applied at one tier and the adjacent tier has not been updated
  • An artifact was updated from an upstream source and the change has not been reviewed or accepted at this scope

Divergence is not inherently a problem — it is expected when teams are actively customizing artifacts. It becomes a concern when it is unintentional, persists for a long time, or causes inconsistency that affects users.

Why Divergence Matters

Scenario Risk if ignored
User scope diverged from team baseline User is running an untested version; issues may not surface until promotion
Team scope diverged from org baseline Inconsistency across teams; policy or security changes at org level are not in effect for this team
Org scope diverged from upstream Upstream security fixes or critical updates have not been adopted

Filtering for Diverged Scopes

Use the Diverged only filter to surface all scopes requiring attention. Combine with the Scope level filter to prioritize by tier:

  1. Start with org-level diverged scopes — these affect the entire organization
  2. Then review team-level diverged scopes to identify teams running non-standard versions
  3. Finally, review user-level diverged scopes, which are often expected but worth monitoring

Promotion Workflow

Promotions allow changes at a lower scope to be reviewed and accepted at a higher scope. A user can request that their local version be promoted to the team baseline; a team admin can request that a team version be promoted to the org baseline.

How a Promotion Request Is Submitted

Users and team admins initiate promotion from the artifact's detail view or from the version timeline. They select the target scope, provide an optional description of what changed and why, then submit the request. The request enters a queue visible to admins for the target scope.

Promotion request review panel showing diff between user and team versions

Reviewing a Promotion Request

  1. Open Admin → Version Management and filter for Pending Promotions.
  2. Click the artifact row, then select the promotion request from the panel on the right.
  3. The review panel shows:
  4. The submitter's identity and the timestamp of the request
  5. A diff comparing the proposed version against the current baseline for the target scope
  6. The change attribution — which lines come from upstream, local modification, or conflict
  7. Any description the submitter provided
  8. Review the diff carefully. If the scope has multiple open requests for the same artifact, they are listed in chronological order; you can review and act on each independently.

Approving a Promotion

Click Approve to accept the proposed version as the new baseline for the target scope.

On approval:

  • The target scope's baseline is updated to the promoted version hash
  • All directly downstream scopes (scopes that inherit from this scope) are flagged as diverged, since their current version no longer matches the updated baseline
  • A promotion event is recorded in the audit log, including the reviewer identity, timestamp, and the before/after version hashes
  • The submitter receives a notification that their request was approved

Downstream effect: Approving a promotion does not automatically update downstream scopes. Each downstream scope continues running its current version until an admin applies a force-sync or a new promotion request is reviewed. This is by design — downstream updates require a deliberate action.

Rejecting a Promotion

Click Reject and provide a reason in the dialog. The reason is required and will be visible to the submitter.

On rejection:

  • The target scope's baseline is unchanged
  • The submitter receives a notification with your rejection reason
  • The promotion request is closed and archived; it remains visible in the request history for the artifact

Promotion Request History

All promotion requests — open, approved, and rejected — are accessible from the artifact's Version History panel under the Promotions tab. This gives you a full audit trail of who requested what, when, and what decision was made.

Force Sync

Force sync pushes the baseline version for a scope onto that scope, overwriting whatever version is currently active there. Use it when you need to ensure a scope is running a specific version regardless of local modifications.

When to Use Force Sync

Situation Recommended action
Critical security patch adopted at org level; must apply immediately to all teams Bulk force-sync all team-level scopes
A user's scope is diverged in a way that is causing incidents Single-scope force-sync for that user
A team has been customizing an artifact in ways that violate policy Single-scope force-sync for that team
Post-rollback cleanup — scopes need to be realigned to the rolled-back baseline Bulk force-sync affected scopes

Force sync is a destructive operation: the scope's current version is replaced. Any local modifications in that scope that have not been promoted are lost. Always confirm that modifications in the target scope are either captured in a promotion request or intentionally discardable before proceeding.

Single-Scope Force Sync

  1. Find the scope row in the version management table
  2. Click the Force Sync button in the Actions column
  3. A confirmation dialog shows:
  4. The current version hash for the scope
  5. The baseline version hash that will replace it
  6. A summary of what will be overwritten
  7. Type the artifact name to confirm (or check the I understand this will overwrite local changes checkbox for scopes with no pending promotions)
  8. Click Confirm Force Sync

The sync is applied immediately. The scope's version is updated, the event is written to the audit log, and the Diverged indicator for that row clears.

Force sync confirmation dialog showing current version versus baseline

Bulk Force Sync

Select multiple scopes using the checkboxes in the leftmost column, then choose Bulk Actions → Force Sync Selected. The bulk confirmation dialog lists every scope that will be affected. Review the list and confirm.

Bulk force-sync operations are applied atomically per scope — each scope is updated independently, and a failure on one scope does not roll back the others. The operation summary shown after completion lists any scopes that could not be updated, along with the reason.

What Gets Logged

Every force-sync event records:

  • Admin identity and IP address
  • Scope identifier (artifact + scope level + owner)
  • Previous version hash
  • New version hash (the baseline applied)
  • Timestamp
  • Whether the operation was single-scope or part of a bulk batch

Audit logs are accessible under Admin → Audit Log and can be filtered by event type, artifact, scope, or admin.

Bulk Operations

When managing version health across a large organization, bulk operations let you act on many scopes in a single step.

Selecting Scopes

Use the checkboxes in the table to select individual rows. To select all visible rows (after applying your current filters), check the header row checkbox. To select all scopes matching the current filter — including those on other pages — click Select all N results in the selection banner.

Available Bulk Actions

Action What it does
Force Sync Selected Pushes the scope baseline to all selected scopes
Dismiss Divergence Marks the divergence as acknowledged without changing versions; useful when divergence is intentional and you want to clear the indicator
Reject All Pending Promotions Rejects all open promotion requests for selected scopes; requires a shared rejection reason
Export Selection Downloads a CSV of the selected scope rows for offline review or reporting

Atomicity Guarantees

Bulk operations are per-scope atomic: each scope in the selection is processed as an independent unit. If the update for one scope fails (for example, due to a concurrent modification), the remaining scopes are still processed and the failure is reported at the end.

There is no rollback across the entire bulk operation. Before running a large bulk force-sync, consider:

  1. Filtering to a subset of scopes first to confirm the selection is correct
  2. Running the operation on a small test group before applying it broadly
  3. Checking the Pending Promotions filter to identify scopes where users have in-flight work that would be overwritten

Operational Procedures

Feature Flag Toggle

Enterprise version management includes a feature flag (version_management_enabled) that controls whether the promotion workflow and force-sync capabilities are available to users and admins. When the flag is disabled:

  • Users cannot submit promotion requests
  • Admins cannot approve, reject, or force-sync from the UI
  • The version management dashboard remains visible to admins for read-only inspection

To toggle the flag, go to Admin → Feature Flags and find version_management_enabled. Changes take effect immediately without a server restart.

Use the flag to gate rollout in stages — for example, enabling the feature for a single team before rolling out organization-wide.

The Version Health panel (top of the admin version management page) provides aggregate metrics:

  • Total scopes tracked
  • Scopes currently diverged (with percentage)
  • Scopes with pending promotion requests
  • Average time to promotion approval over the past 30 days

Monitor divergence rate over time to detect patterns:

  • A spike in diverged scopes after a baseline update indicates that downstream propagation may be too slow or that downstream teams are not accepting changes
  • A growing queue of pending promotions indicates that the review cadence needs to increase
  • High divergence concentrated in specific teams or artifacts may indicate that the baseline version is not a good fit for those teams

Use the Export Selection bulk action to pull a CSV snapshot for use in periodic reporting or for sharing with team leads.

Rollback Steps if Issues Arise

If a promotion or force-sync causes problems, use the following procedure to restore the previous state.

Step 1: Identify the previous version hash.

Open the artifact's Version History panel. Each entry in the timeline shows the version hash, the event that caused the change (promotion, force-sync, upstream update), the timestamp, and the admin who initiated it. Locate the entry immediately before the problematic change.

Step 2: Force-sync to the previous version.

Currently, the force-sync operation always applies the scope's current baseline. To roll back to a specific version hash that is not the current baseline, you must first update the baseline:

  1. Go to Admin → Version Management → [artifact name] → Baselines
  2. Click Pin to version and enter the previous version hash
  3. Apply the pin — the baseline is updated to the target hash
  4. Use force-sync to propagate the pinned version to affected scopes

Step 3: Notify affected users.

After rolling back, any users whose scope was updated will see a divergence indicator. Send a notification via Admin → Announcements explaining what changed and whether they need to take action.

Step 4: Open a review of the failed promotion.

Use the audit log to reconstruct exactly what changed, when, and who approved it. If the issue was in the promoted content itself, reject any related pending promotions and work with the submitter to address the problem before re-promoting.