@serve.zone/gitops 2.13.1 → 3.1.0

package/ts/classes/syncmanager.ts

@@ -1,15 +1,32 @@
 import * as plugins from '../plugins.js';
 import { logger } from '../logging.js';
 import { intervalMinutesToMs, unrefTimer, validateIntervalMinutes } from '../timers.js';
-import type { ChildProcess } from 'node:child_process';
 import type * as interfaces from '../../ts_interfaces/index.js';
 import type { ConnectionManager } from './connectionmanager.js';
 import type { ActionLog } from './actionlog.js';
 import type { StorageManager } from '../storage/index.js';
 import type { BaseProvider } from '../providers/classes.baseprovider.js';
+import * as syncpath from './syncpath.js';
 
 const SYNC_PREFIX = '/sync/';
 const SYNC_STATUS_PREFIX = '/sync-status/';
+const SYNC_MAPPING_PREFIX = '/sync-mappings/';
+const REPO_SYNC_CONCURRENCY = 10;
+const ARTIFACT_REPO_SYNC_CONCURRENCY = 2;
+const IMAGE_COPY_CONCURRENCY = 2;
+const SKOPEO_VERSION_TIMEOUT_MS = 10_000;
+const SKOPEO_COPY_TIMEOUT_MS = 30 * 60 * 1000;
+const RELEASE_ASSET_TRANSFER_TIMEOUT_MS = 10 * 60 * 1000;
+const RELEASE_ASSET_MAX_BYTES = 250 * 1024 * 1024;
+const RAW_API_TIMEOUT_MS = 2 * 60 * 1000;
+const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
+
+type TSpawnedChild = ReturnType<typeof plugins.childProcess.spawn>;
+
+interface IRunCommandOptions {
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+}
 
 /**
  * Manages sync configurations and executes periodic git mirror operations.
@@ -23,8 +40,12 @@ export class SyncManager {
   private syncedGroupMeta: Set<string> = new Set();
   private currentSyncConfig: interfaces.data.ISyncConfig | null = null;
   private avatarUploadCache: Map<string, string> = new Map();
-  private activeGitChildren = new Set<ChildProcess>();
+  private activeGitChildren = new Set<TSpawnedChild>();
   private stopping = false;
+  private skopeoAvailable: boolean | null = null;
+  private abortController = new AbortController();
+  private activeImageCopies = 0;
+  private imageCopyWaiters: Array<() => void> = [];
 
   private mirrorsPath = '';
 
@@ -36,6 +57,7 @@ export class SyncManager {
 
   async init(): Promise<void> {
     this.stopping = false;
+    this.abortController = new AbortController();
     // Create temp directory for mirrors (RAM-backed on most Linux systems via tmpfs)
     this.mirrorsPath = await plugins.fs.mkdtemp(plugins.path.join(plugins.os.tmpdir(), 'gitops-mirrors-'));
     await this.loadConfigs();
@@ -51,6 +73,12 @@ export class SyncManager {
 
   async stop(): Promise<void> {
     this.stopping = true;
+    if (!this.abortController.signal.aborted) {
+      this.abortController.abort(new Error('SyncManager is stopping'));
+    }
+    for (const wake of this.imageCopyWaiters.splice(0)) {
+      wake();
+    }
     for (const [_id, timer] of this.timers) {
       clearInterval(timer);
     }
@@ -105,6 +133,8 @@ export class SyncManager {
     intervalMinutes?: number;
     enforceDelete?: boolean;
     enforceGroupDelete?: boolean;
+    syncReleases?: boolean;
+    syncContainerImages?: boolean;
     addMirrorHint?: boolean;
     useGroupAvatarsForProjects?: boolean;
   }): Promise<interfaces.data.ISyncConfig> {
@@ -118,8 +148,12 @@ export class SyncManager {
       status: 'paused',
       lastSyncAt: 0,
       reposSynced: 0,
+      releasesSynced: 0,
+      imagesSynced: 0,
       enforceDelete: data.enforceDelete ?? false,
       enforceGroupDelete: data.enforceGroupDelete ?? false,
+      syncReleases: data.syncReleases ?? false,
+      syncContainerImages: data.syncContainerImages ?? false,
       addMirrorHint: data.addMirrorHint ?? false,
       useGroupAvatarsForProjects: data.useGroupAvatarsForProjects ?? false,
       createdAt: Date.now(),
@@ -133,7 +167,7 @@ export class SyncManager {
 
   async updateConfig(
     id: string,
-    updates: { name?: string; targetGroupOffset?: string; intervalMinutes?: number; enforceDelete?: boolean; enforceGroupDelete?: boolean; addMirrorHint?: boolean; useGroupAvatarsForProjects?: boolean },
+    updates: { name?: string; targetGroupOffset?: string; intervalMinutes?: number; enforceDelete?: boolean; enforceGroupDelete?: boolean; syncReleases?: boolean; syncContainerImages?: boolean; addMirrorHint?: boolean; useGroupAvatarsForProjects?: boolean },
   ): Promise<interfaces.data.ISyncConfig> {
     const config = this.configs.find((c) => c.id === id);
     if (!config) throw new Error(`Sync config not found: ${id}`);
@@ -143,9 +177,11 @@ export class SyncManager {
     }
     if (updates.enforceDelete !== undefined) config.enforceDelete = updates.enforceDelete;
     if (updates.enforceGroupDelete !== undefined) config.enforceGroupDelete = updates.enforceGroupDelete;
+    if (updates.syncReleases !== undefined) config.syncReleases = updates.syncReleases;
+    if (updates.syncContainerImages !== undefined) config.syncContainerImages = updates.syncContainerImages;
     if (updates.addMirrorHint !== undefined) config.addMirrorHint = updates.addMirrorHint;
     if (updates.useGroupAvatarsForProjects !== undefined) config.useGroupAvatarsForProjects = updates.useGroupAvatarsForProjects;
-    if (updates.targetGroupOffset !== undefined) config.targetGroupOffset = updates.targetGroupOffset;
+    if (updates.targetGroupOffset !== undefined) config.targetGroupOffset = updates.targetGroupOffset || undefined;
     this.validateSyncConfig(config);
     await this.persistConfig(config);
     // Restart timer with new interval
@@ -166,6 +202,10 @@ export class SyncManager {
     for (const key of statusKeys) {
       await this.storageManager.delete(key);
     }
+    const mappingKeys = await this.storageManager.list(`${SYNC_MAPPING_PREFIX}${id}/`);
+    for (const key of mappingKeys) {
+      await this.storageManager.delete(key);
+    }
     // Clean up mirror directory
     const mirrorDir = plugins.path.join(this.mirrorsPath, id);
     try {
@@ -222,11 +262,11 @@ export class SyncManager {
     const sourceProvider = this.connectionManager.getProvider(config.sourceConnectionId);
     const targetProvider = this.connectionManager.getProvider(config.targetConnectionId);
     logger.syncLog('info', `Fetching source projects from "${sourceConn.name}"...`, 'preview');
-    const allProjects = await sourceProvider.getProjects();
-    const projects = allProjects.filter(p => !this.isObsoletePath(p.fullPath));
+    const allProjects: interfaces.data.IProject[] = await sourceProvider.getProjects();
+    const projects = allProjects.filter((p: interfaces.data.IProject) => !this.isObsoletePath(p.fullPath));
     logger.syncLog('info', `Found ${projects.length} source projects (${allProjects.length - projects.length} obsolete excluded)`, 'preview');
 
-    const mappings = projects.map((project) => {
+    const mappings = projects.map((project: interfaces.data.IProject) => {
       const targetFullPath = this.computeTargetFullPath(
         project.fullPath, sourceConn.groupFilter, config.targetGroupOffset,
       );
@@ -238,14 +278,14 @@ export class SyncManager {
     if (config.enforceDelete) {
       logger.syncLog('info', 'Computing repo deletions (enforce-delete enabled)...', 'preview');
       const expectedTargetPaths = new Set(
-        mappings.map((m) => m.targetFullPath.toLowerCase()),
+        mappings.map((m: { sourceFullPath: string; targetFullPath: string }) => this.computeProviderProjectFullPath(targetConn, m.targetFullPath).toLowerCase()),
       );
       const scopePrefix = config.targetGroupOffset;
       const targetProjects = await targetProvider.getProjects();
 
       for (const tp of targetProjects) {
         if (this.isObsoletePath(tp.fullPath)) continue;
-        if (scopePrefix && !tp.fullPath.toLowerCase().startsWith(scopePrefix.toLowerCase() + '/')) {
+        if (!this.isTargetProjectInScope(targetConn, tp.fullPath, scopePrefix)) {
           continue;
         }
         if (!expectedTargetPaths.has(tp.fullPath.toLowerCase())) {
@@ -326,29 +366,68 @@ export class SyncManager {
       // Get all projects from source
       const sourceProvider = this.connectionManager.getProvider(config.sourceConnectionId);
       logger.syncLog('info', `Fetching source projects from "${sourceConn.name}"...`, 'api');
-      const allProjects = await sourceProvider.getProjects();
-      const projects = allProjects.filter(p => !this.isObsoletePath(p.fullPath));
+      const allProjects: interfaces.data.IProject[] = await sourceProvider.getProjects();
+      const projects = allProjects.filter((p: interfaces.data.IProject) => !this.isObsoletePath(p.fullPath));
       logger.syncLog('info', `Found ${projects.length} source projects (${allProjects.length - projects.length} obsolete excluded)`, 'api');
 
       let synced = 0;
-      const CONCURRENCY = 10;
-      for (let i = 0; i < projects.length; i += CONCURRENCY) {
-        const batch = projects.slice(i, i + CONCURRENCY);
-        await Promise.all(batch.map(async (project) => {
+      let failed = 0;
+      let releasesSynced = 0;
+      let imagesSynced = 0;
+      const concurrency = config.syncReleases || config.syncContainerImages
+        ? ARTIFACT_REPO_SYNC_CONCURRENCY
+        : REPO_SYNC_CONCURRENCY;
+      for (let i = 0; i < projects.length; i += concurrency) {
+        const batch = projects.slice(i, i + concurrency);
+        await Promise.all(batch.map(async (project: interfaces.data.IProject) => {
+          const targetFullPath = this.computeTargetFullPath(
+            project.fullPath, sourceConn.groupFilter, config.targetGroupOffset,
+          );
           try {
             logger.syncLog('info', `Syncing ${project.fullPath}...`, 'sync');
-            await this.syncRepo(config, project, sourceConn, targetConn);
+            const syncResult = await this.syncRepo(config, project, sourceConn, targetConn);
+            releasesSynced += syncResult.releasesSynced || 0;
+            imagesSynced += syncResult.imagesSynced || 0;
+            const artifactErrors = [syncResult.releaseSyncError, syncResult.imageSyncError].filter(Boolean);
+            if (artifactErrors.length > 0) {
+              failed++;
+              const errMsg = artifactErrors.join('; ');
+              await this.updateRepoStatus(config.id, project.fullPath, {
+                status: 'error',
+                targetFullPath: syncResult.targetFullPath,
+                sourceProjectId: project.id,
+                targetProjectId: syncResult.targetProjectId,
+                releasesSynced: syncResult.releasesSynced,
+                imagesSynced: syncResult.imagesSynced,
+                releaseSyncError: syncResult.releaseSyncError,
+                imageSyncError: syncResult.imageSyncError,
+                lastSyncAt: Date.now(),
+                lastSyncError: errMsg,
+              });
+              logger.syncLog('error', `Artifact sync failed for ${project.fullPath}: ${errMsg}`, 'sync');
+              return;
+            }
             synced++;
             await this.updateRepoStatus(config.id, project.fullPath, {
               status: 'synced',
+              targetFullPath: syncResult.targetFullPath,
+              sourceProjectId: project.id,
+              targetProjectId: syncResult.targetProjectId,
+              releasesSynced: syncResult.releasesSynced,
+              imagesSynced: syncResult.imagesSynced,
+              releaseSyncError: syncResult.releaseSyncError,
+              imageSyncError: syncResult.imageSyncError,
               lastSyncAt: Date.now(),
               lastSyncError: undefined,
             });
             logger.syncLog('success', `Synced ${project.fullPath}`, 'sync');
           } catch (err) {
+            failed++;
             const errMsg = err instanceof Error ? err.message : String(err);
             await this.updateRepoStatus(config.id, project.fullPath, {
               status: 'error',
+              targetFullPath,
+              sourceProjectId: project.id,
               lastSyncError: errMsg,
               lastSyncAt: Date.now(),
             });
@@ -371,12 +450,20 @@ export class SyncManager {
 
       config.lastSyncAt = Date.now();
       config.reposSynced = synced;
+      config.releasesSynced = releasesSynced;
+      config.imagesSynced = imagesSynced;
       config.lastSyncDurationMs = Date.now() - startTime;
-      config.lastSyncError = undefined;
-      if (config.status === 'error') config.status = 'active';
+      if (failed > 0) {
+        config.lastSyncError = `Sync completed with ${failed}/${projects.length} repo error(s)`;
+        config.status = 'error';
+      } else {
+        config.lastSyncError = undefined;
+        if (config.status === 'error') config.status = 'active';
+      }
       await this.persistConfig(config);
 
-      logger.syncLog('success', `Sync complete for "${config.name}": ${synced}/${projects.length} repos in ${config.lastSyncDurationMs}ms`, 'sync');
+      const completionLevel = failed > 0 ? 'error' : 'success';
+      logger.syncLog(completionLevel, `Sync complete for "${config.name}": ${synced}/${projects.length} repos synced, ${failed} failed in ${config.lastSyncDurationMs}ms`, 'sync');
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
       config.lastSyncError = errMsg;
@@ -399,14 +486,22 @@ export class SyncManager {
     project: interfaces.data.IProject,
     sourceConn: interfaces.data.IProviderConnection,
     targetConn: interfaces.data.IProviderConnection,
-  ): Promise<void> {
+  ): Promise<{
+    targetFullPath: string;
+    targetProjectId?: string;
+    releasesSynced?: number;
+    imagesSynced?: number;
+    releaseSyncError?: string;
+    imageSyncError?: string;
+  }> {
     const targetFullPath = this.computeTargetFullPath(
       project.fullPath, sourceConn.groupFilter, config.targetGroupOffset,
     );
+    const targetProviderFullPath = this.computeProviderProjectFullPath(targetConn, targetFullPath);
 
     // Build authenticated git URLs
     const sourceUrl = this.buildAuthUrl(sourceConn, project.fullPath);
-    const targetUrl = this.buildAuthUrl(targetConn, targetFullPath);
+    const targetUrl = this.buildAuthUrl(targetConn, targetProviderFullPath);
 
     // Mirror directory for this repo
     const mirrorDir = plugins.path.join(
@@ -415,6 +510,8 @@ export class SyncManager {
       this.sanitizePath(project.fullPath),
     );
 
+    await this.reconcileProjectMapping(config, project, sourceConn, targetConn, targetFullPath);
+
     // Ensure target group/project hierarchy exists
     await this.ensureTargetExists(targetConn, targetFullPath, project, sourceConn, sourceConn.groupFilter, config.targetGroupOffset);
 
@@ -422,12 +519,27 @@ export class SyncManager {
     const sourceProvider = this.connectionManager.getProvider(sourceConn.id);
     const targetProvider = this.connectionManager.getProvider(targetConn.id);
     const apiRefsMatch = await this.refsMatchViaApi(
-      sourceProvider, targetProvider, project.fullPath, targetFullPath,
+      sourceProvider, targetProvider, project.fullPath, targetProviderFullPath,
     );
     if (apiRefsMatch === true) {
       logger.syncLog('info', `Refs match via API for ${project.fullPath}, skipping git`, 'api');
-      await this.syncProjectMetadata(config, sourceConn, targetConn, project.fullPath, targetFullPath);
-      return;
+      await this.syncProjectMetadata(config, sourceConn, targetConn, project.fullPath, targetProviderFullPath);
+      const targetProject = await this.fetchProjectRaw(targetConn, targetProviderFullPath);
+      await this.persistProjectMapping(config, project, sourceConn, targetConn, targetFullPath, targetProject);
+      const artifactResult = await this.syncProjectArtifacts(
+        config,
+        sourceConn,
+        targetConn,
+        sourceProvider,
+        targetProvider,
+        project.fullPath,
+        targetFullPath,
+      );
+      return {
+        targetFullPath,
+        targetProjectId: targetProject?.id ? String(targetProject.id) : undefined,
+        ...artifactResult,
+      };
     }
 
     // Clone or fetch from source
@@ -454,7 +566,22 @@ export class SyncManager {
       const msg = err instanceof Error ? err.message : String(err);
       if (msg.includes("couldn't find remote ref HEAD")) {
         logger.syncLog('warn', `Skipping empty repo ${project.fullPath} (no HEAD ref)`, 'git');
-        return;
+        const targetProject = await this.fetchProjectRaw(targetConn, targetProviderFullPath);
+        await this.persistProjectMapping(config, project, sourceConn, targetConn, targetFullPath, targetProject);
+        const artifactResult = await this.syncProjectArtifacts(
+          config,
+          sourceConn,
+          targetConn,
+          sourceProvider,
+          targetProvider,
+          project.fullPath,
+          targetFullPath,
+        );
+        return {
+          targetFullPath,
+          targetProjectId: targetProject?.id ? String(targetProject.id) : undefined,
+          ...artifactResult,
+        };
       }
       throw err;
     }
@@ -471,7 +598,7 @@ export class SyncManager {
     const isUnrelated = await this.checkUnrelatedHistory(mirrorDir);
     if (isUnrelated) {
       logger.syncLog('warn', `Target "${targetFullPath}" has unrelated history — moving to obsolete`, 'git');
-      await this.moveToObsolete(targetConn, targetFullPath, config.targetGroupOffset);
+      await this.moveToObsolete(targetConn, targetProviderFullPath, config.targetGroupOffset);
       // Re-create fresh target
       await this.ensureTargetExists(targetConn, targetFullPath, project, sourceConn, sourceConn.groupFilter, config.targetGroupOffset);
       this.actionLog.append({
@@ -498,10 +625,10 @@ export class SyncManager {
       ], mirrorDir);
 
       // Phase 2: sync default_branch now that all branches exist on target
-      await this.syncDefaultBranchBeforePush(sourceConn, targetConn, project.fullPath, targetFullPath);
+      await this.syncDefaultBranchBeforePush(sourceConn, targetConn, project.fullPath, targetProviderFullPath);
 
       // Phase 2b: unprotect stale branches on target so --prune can delete them
-      await this.unprotectStaleBranches(targetConn, targetFullPath, mirrorDir);
+      await this.unprotectStaleBranches(targetConn, targetProviderFullPath, mirrorDir);
 
       // Phase 3: push with --prune to remove stale branches (safe now that default_branch is correct)
       await this.runGit([
@@ -513,7 +640,754 @@ export class SyncManager {
     }
 
     // Sync project metadata (description, visibility, topics, default_branch, avatar)
-    await this.syncProjectMetadata(config, sourceConn, targetConn, project.fullPath, targetFullPath);
+    await this.syncProjectMetadata(config, sourceConn, targetConn, project.fullPath, targetProviderFullPath);
+    const targetProject = await this.fetchProjectRaw(targetConn, targetProviderFullPath);
+    await this.persistProjectMapping(config, project, sourceConn, targetConn, targetFullPath, targetProject);
+    const artifactResult = await this.syncProjectArtifacts(
+      config,
+      sourceConn,
+      targetConn,
+      sourceProvider,
+      targetProvider,
+      project.fullPath,
+      targetFullPath,
+    );
+    return {
+      targetFullPath,
+      targetProjectId: targetProject?.id ? String(targetProject.id) : undefined,
+      ...artifactResult,
+    };
+  }
+
+  private async syncProjectArtifacts(
+    config: interfaces.data.ISyncConfig,
+    sourceConn: interfaces.data.IProviderConnection,
+    targetConn: interfaces.data.IProviderConnection,
+    sourceProvider: BaseProvider,
+    targetProvider: BaseProvider,
+    sourceFullPath: string,
+    targetFullPath: string,
+  ): Promise<{
+    releasesSynced?: number;
+    imagesSynced?: number;
+    releaseSyncError?: string;
+    imageSyncError?: string;
+  }> {
+    const result: {
+      releasesSynced?: number;
+      imagesSynced?: number;
+      releaseSyncError?: string;
+      imageSyncError?: string;
+    } = {};
+
+    if (config.syncReleases) {
+      try {
+        result.releasesSynced = await this.syncReleasesForProject(
+          sourceProvider,
+          targetProvider,
+          sourceFullPath,
+          this.computeProviderProjectFullPath(targetConn, targetFullPath),
+        );
+      } catch (err) {
+        result.releasesSynced = 0;
+        result.releaseSyncError = err instanceof Error ? err.message : String(err);
+        logger.syncLog('error', `Release sync failed for ${sourceFullPath}: ${result.releaseSyncError}`, 'api');
+      }
+    }
+
+    if (config.syncContainerImages) {
+      try {
+        result.imagesSynced = await this.syncContainerImagesForProject(
+          config,
+          sourceConn,
+          targetConn,
+          sourceProvider,
+          targetProvider,
+          sourceFullPath,
+          targetFullPath,
+        );
+      } catch (err) {
+        result.imagesSynced = 0;
+        result.imageSyncError = err instanceof Error ? err.message : String(err);
+        logger.syncLog('error', `Container image sync failed for ${sourceFullPath}: ${result.imageSyncError}`, 'api');
+      }
+    }
+
+    return result;
+  }
+
+  private async syncReleasesForProject(
+    sourceProvider: BaseProvider,
+    targetProvider: BaseProvider,
+    sourceFullPath: string,
+    targetFullPath: string,
+  ): Promise<number> {
+    const [sourceReleases, targetReleases] = await Promise.all([
+      sourceProvider.getReleases(sourceFullPath),
+      targetProvider.getReleases(targetFullPath),
+    ]);
+    const targetByTag = new Map<string, interfaces.data.IRelease>(
+      targetReleases.map((release: interfaces.data.IRelease) => [release.tagName, release]),
+    );
+    const sourceTags = new Set<string>(
+      sourceReleases.map((release: interfaces.data.IRelease) => release.tagName),
+    );
+
+    let synced = 0;
+    for (const sourceRelease of sourceReleases) {
+      logger.syncLog('info', `Syncing release ${sourceRelease.tagName} for ${targetFullPath}`, 'api');
+      const previousTargetRelease = targetByTag.get(sourceRelease.tagName);
+      const targetRelease = await targetProvider.upsertRelease(targetFullPath, sourceRelease);
+      const previousTargetAssets = previousTargetRelease?.assets || targetRelease.assets || [];
+      const previousAssetsByName = new Map<string, interfaces.data.IReleaseAsset>();
+      for (const targetAsset of previousTargetAssets) {
+        if (!previousAssetsByName.has(targetAsset.name)) {
+          previousAssetsByName.set(targetAsset.name, targetAsset);
+        }
+      }
+      const retainedAssetIds = new Set<string>();
+      const syncedAssetIds = new Set<string>();
+      const deletedAssetIds = new Set<string>();
+
+      for (const sourceAsset of sourceRelease.assets) {
+        if (sourceAsset.kind === 'source') continue;
+        const previousAsset = previousAssetsByName.get(sourceAsset.name);
+        if (previousAsset && this.canReuseTargetReleaseAsset(sourceRelease, sourceAsset, previousAsset)) {
+          if (previousAsset.id) retainedAssetIds.add(previousAsset.id);
+          continue;
+        }
+        if (sourceAsset.size && sourceAsset.size > RELEASE_ASSET_MAX_BYTES) {
+          throw new Error(`Release asset ${sourceAsset.name} is ${sourceAsset.size} bytes, exceeding the ${RELEASE_ASSET_MAX_BYTES} byte limit`);
+        }
+
+        const syncAsset = async (): Promise<interfaces.data.IReleaseAsset> => {
+          const transfer = this.createTransferAbortSignal(
+            RELEASE_ASSET_TRANSFER_TIMEOUT_MS,
+            `Release asset transfer ${sourceFullPath}@${sourceRelease.tagName}/${sourceAsset.name}`,
+          );
+          try {
+            const transferOptions = {
+              signal: transfer.signal,
+              maxBytes: RELEASE_ASSET_MAX_BYTES,
+            };
+            const payload = await sourceProvider.downloadReleaseAsset(
+              sourceFullPath,
+              sourceRelease,
+              sourceAsset,
+              transferOptions,
+            );
+            if (payload) {
+              return await targetProvider.uploadReleaseAsset(
+                targetFullPath,
+                targetRelease,
+                sourceAsset,
+                payload,
+                transferOptions,
+              );
+            }
+            return await targetProvider.createReleaseAssetLink(targetFullPath, targetRelease, sourceAsset);
+          } finally {
+            transfer.cleanup();
+          }
+        };
+
+        let syncedAsset: interfaces.data.IReleaseAsset;
+        try {
+          syncedAsset = await syncAsset();
+        } catch (err) {
+          if (!previousAsset || !this.isReleaseAssetDuplicateError(err)) throw err;
+          await targetProvider.deleteReleaseAsset(targetFullPath, previousTargetRelease || targetRelease, previousAsset);
+          if (previousAsset.id) deletedAssetIds.add(previousAsset.id);
+          syncedAsset = await syncAsset();
+        }
+        if (syncedAsset.id) syncedAssetIds.add(syncedAsset.id);
+      }
+
+      for (const targetAsset of previousTargetAssets) {
+        if (targetAsset.id && deletedAssetIds.has(targetAsset.id)) {
+          continue;
+        }
+        if (targetAsset.id && (retainedAssetIds.has(targetAsset.id) || syncedAssetIds.has(targetAsset.id))) {
+          continue;
+        }
+        await targetProvider.deleteReleaseAsset(targetFullPath, previousTargetRelease || targetRelease, targetAsset);
+      }
+      synced++;
+    }
+
+    for (const targetRelease of targetReleases) {
+      if (!sourceTags.has(targetRelease.tagName)) {
+        logger.syncLog('warn', `Deleting stale release ${targetRelease.tagName} from ${targetFullPath}`, 'api');
+        await targetProvider.deleteRelease(targetFullPath, targetRelease.tagName);
+      }
+    }
+
+    return synced;
+  }
+
+  private canReuseTargetReleaseAsset(
+    _release: interfaces.data.IRelease,
+    sourceAsset: interfaces.data.IReleaseAsset,
+    targetAsset: interfaces.data.IReleaseAsset,
+  ): boolean {
+    if (sourceAsset.name !== targetAsset.name) return false;
+    if (sourceAsset.url && targetAsset.url && sourceAsset.url === targetAsset.url) return true;
+    if (sourceAsset.size !== undefined && targetAsset.size !== undefined) {
+      return sourceAsset.size === targetAsset.size;
+    }
+    return false;
+  }
+
+  private isReleaseAssetDuplicateError(err: unknown): boolean {
+    const errMsg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return errMsg.includes('already')
+      || errMsg.includes('exists')
+      || errMsg.includes('duplicate')
+      || errMsg.includes('409');
+  }
+
+  private async syncContainerImagesForProject(
+    config: interfaces.data.ISyncConfig,
+    sourceConn: interfaces.data.IProviderConnection,
+    targetConn: interfaces.data.IProviderConnection,
+    sourceProvider: BaseProvider,
+    targetProvider: BaseProvider,
+    sourceFullPath: string,
+    targetFullPath: string,
+  ): Promise<number> {
+    await this.assertSkopeoAvailable();
+
+    const sourceRepositories = await sourceProvider.getContainerImageRepositories(sourceFullPath);
+    const targetProviderFullPath = this.computeProviderProjectFullPath(targetConn, targetFullPath);
+    const expectedTargetTags = new Set<string>();
+    let copiedTags = 0;
+
+    for (const sourceRepository of sourceRepositories) {
+      const targetImagePath = this.computeProviderContainerImagePath(
+        targetConn,
+        targetFullPath,
+        syncpath.computeTargetContainerImagePath({
+          sourceFullPath,
+          sourceGroupFilter: sourceConn.groupFilter,
+          targetGroupOffset: config.targetGroupOffset,
+          sourceImagePath: sourceRepository.path,
+        }),
+      );
+      const targetLocation = this.buildRegistryImageLocation(targetConn, targetImagePath);
+
+      for (const tag of sourceRepository.tags) {
+        expectedTargetTags.add(this.getContainerTagKey(targetImagePath, tag.name));
+        await this.copyContainerImageTag(
+          sourceConn,
+          targetConn,
+          `${sourceRepository.location}:${tag.name}`,
+          `${targetLocation}:${tag.name}`,
+        );
+        copiedTags++;
+      }
+    }
+
+    const targetRepositories = await targetProvider.getContainerImageRepositories(targetProviderFullPath);
+    for (const targetRepository of targetRepositories) {
+      for (const tag of targetRepository.tags) {
+        const tagKey = this.getContainerTagKey(targetRepository.path, tag.name);
+        if (!expectedTargetTags.has(tagKey)) {
+          logger.syncLog('warn', `Deleting stale image tag ${targetRepository.path}:${tag.name}`, 'api');
+          await targetProvider.deleteContainerImageTag(targetProviderFullPath, targetRepository.id, tag.name);
+        }
+      }
+    }
+
+    return copiedTags;
+  }
+
+  private computeProviderProjectFullPath(
+    conn: interfaces.data.IProviderConnection,
+    fullPath: string,
+  ): string {
+    const normalizedPath = syncpath.normalizeSyncPath(fullPath);
+    if (conn.providerType !== 'gitea') return normalizedPath;
+    const [orgName, ...repoSegments] = normalizedPath.split('/');
+    if (!orgName) return normalizedPath;
+    if (repoSegments.length === 0) return `${conn.groupFilter || 'default'}/${orgName}`;
+    return `${orgName}/${repoSegments.join('-')}`;
+  }
+
+  private isTargetProjectInScope(
+    conn: interfaces.data.IProviderConnection,
+    providerFullPath: string,
+    logicalScopePrefix?: string,
+  ): boolean {
+    if (!logicalScopePrefix) return true;
+    const normalizedProviderPath = syncpath.normalizeSyncPath(providerFullPath).toLowerCase();
+    const normalizedScope = syncpath.normalizeSyncPath(logicalScopePrefix).toLowerCase();
+    if (conn.providerType !== 'gitea') {
+      return normalizedProviderPath === normalizedScope
+        || normalizedProviderPath.startsWith(`${normalizedScope}/`);
+    }
+
+    const [scopeOwner, ...scopeRepoSegments] = normalizedScope.split('/');
+    if (!scopeOwner) return true;
+    if (scopeRepoSegments.length === 0) {
+      return normalizedProviderPath === scopeOwner
+        || normalizedProviderPath.startsWith(`${scopeOwner}/`);
+    }
+    const repoPrefix = scopeRepoSegments.join('-');
+    return normalizedProviderPath === `${scopeOwner}/${repoPrefix}`
+      || normalizedProviderPath.startsWith(`${scopeOwner}/${repoPrefix}-`)
+      || normalizedProviderPath.startsWith(`${scopeOwner}/${repoPrefix}/`);
+  }
+
+  private computeProviderContainerImagePath(
+    conn: interfaces.data.IProviderConnection,
+    targetFullPath: string,
+    targetImagePath: string,
+  ): string {
+    if (conn.providerType !== 'gitea') return syncpath.normalizeSyncPath(targetImagePath);
+    const normalizedTargetFullPath = syncpath.normalizeSyncPath(targetFullPath);
+    const normalizedImagePath = syncpath.normalizeSyncPath(targetImagePath);
+    const providerProjectPath = this.computeProviderProjectFullPath(conn, normalizedTargetFullPath);
+    if (normalizedImagePath === normalizedTargetFullPath) return providerProjectPath;
+    if (normalizedImagePath.startsWith(`${normalizedTargetFullPath}/`)) {
+      return `${providerProjectPath}/${normalizedImagePath.substring(normalizedTargetFullPath.length + 1)}`;
+    }
+    return this.computeProviderProjectFullPath(conn, normalizedImagePath);
+  }
+
+  private getContainerTagKey(imagePath: string, tagName: string): string {
+    return `${syncpath.normalizeSyncPath(imagePath).toLowerCase()}:${tagName}`;
+  }
+
+  private buildRegistryImageLocation(
+    conn: interfaces.data.IProviderConnection,
+    imagePath: string,
+  ): string {
+    return `${this.getRegistryHost(conn)}/${syncpath.normalizeSyncPath(imagePath)}`;
+  }
+
+  private getRegistryHost(conn: interfaces.data.IProviderConnection): string {
+    return (conn.registryUrl || new URL(conn.baseUrl).host)
+      .replace(/^https?:\/\//, '')
+      .replace(/\/+$/, '');
+  }
+
+  private getRegistryAuth(conn: interfaces.data.IProviderConnection): { registry: string; username: string; password: string } | undefined {
+    const token = conn.registryToken || conn.token;
+    const username = conn.registryUsername || (conn.providerType === 'gitlab' ? 'oauth2' : undefined);
+    if (!username || !token || token === '***') return undefined;
+    return {
+      registry: this.getRegistryHost(conn),
+      username,
+      password: token,
+    };
+  }
+
+  private async createRegistryAuthFile(conn: interfaces.data.IProviderConnection): Promise<string | undefined> {
+    const auth = this.getRegistryAuth(conn);
+    if (!auth) return undefined;
+    const authDir = await plugins.fs.mkdtemp(plugins.path.join(plugins.os.tmpdir(), 'gitops-skopeo-auth-'));
+    const authFile = plugins.path.join(authDir, 'auth.json');
+    const authString = plugins.Buffer.from(`${auth.username}:${auth.password}`, 'utf8').toString('base64');
+    try {
+      await plugins.fs.writeFile(
+        authFile,
+        JSON.stringify({ auths: { [auth.registry]: { auth: authString } } }),
+        { mode: 0o600 },
+      );
+      return authFile;
+    } catch (err) {
+      await plugins.fs.rm(authDir, { recursive: true, force: true });
+      throw err;
+    }
+  }
+
+  private async removeRegistryAuthFile(authFile: string | undefined): Promise<void> {
+    if (!authFile) return;
+    await plugins.fs.rm(plugins.path.dirname(authFile), { recursive: true, force: true });
+  }
+
+  private async assertSkopeoAvailable(): Promise<void> {
+    if (this.skopeoAvailable === true) return;
+    if (this.skopeoAvailable === false) {
+      throw new Error('Container image sync requires skopeo, but the skopeo command is not available');
+    }
+    try {
+      await this.runCommand('skopeo', ['--version'], undefined, { timeoutMs: SKOPEO_VERSION_TIMEOUT_MS });
+      this.skopeoAvailable = true;
+    } catch {
+      this.skopeoAvailable = false;
+      throw new Error('Container image sync requires skopeo, but the skopeo command is not available');
+    }
+  }
+
+  private async copyContainerImageTag(
+    sourceConn: interfaces.data.IProviderConnection,
+    targetConn: interfaces.data.IProviderConnection,
+    sourceReference: string,
+    targetReference: string,
+  ): Promise<void> {
+    logger.syncLog('info', `Copying image ${sourceReference} -> ${targetReference}`, 'api');
+    let sourceAuthFile: string | undefined;
+    let targetAuthFile: string | undefined;
+    try {
+      sourceAuthFile = await this.createRegistryAuthFile(sourceConn);
+      targetAuthFile = await this.createRegistryAuthFile(targetConn);
+      const args = ['copy', '--all', '--image-parallel-copies', '3'];
+      if (sourceAuthFile) args.push('--src-authfile', sourceAuthFile);
+      if (targetAuthFile) args.push('--dest-authfile', targetAuthFile);
+      args.push(`docker://${sourceReference}`, `docker://${targetReference}`);
+      await this.withImageCopySlot(() => this.runCommand('skopeo', args, undefined, {
+        timeoutMs: SKOPEO_COPY_TIMEOUT_MS,
+      }));
+    } finally {
+      await Promise.all([
+        this.removeRegistryAuthFile(sourceAuthFile),
+        this.removeRegistryAuthFile(targetAuthFile),
+      ]);
+    }
+  }
+
+  private async withImageCopySlot<T>(fn: () => Promise<T>): Promise<T> {
+    while (this.activeImageCopies >= IMAGE_COPY_CONCURRENCY) {
+      if (this.stopping) {
+        throw new Error('SyncManager is stopping');
+      }
+      await new Promise<void>((resolve) => this.imageCopyWaiters.push(resolve));
+    }
+    if (this.stopping) {
+      throw new Error('SyncManager is stopping');
+    }
+
+    this.activeImageCopies++;
+    try {
+      return await fn();
+    } finally {
+      this.activeImageCopies--;
+      const wake = this.imageCopyWaiters.shift();
+      if (wake) wake();
+    }
+  }
+
+  private createTransferAbortSignal(
+    timeoutMs: number,
+    label: string,
+  ): { signal: AbortSignal; cleanup: () => void } {
+    const controller = new AbortController();
+    const abortFromStop = (): void => {
+      if (!controller.signal.aborted) {
+        controller.abort(new Error('SyncManager is stopping'));
+      }
+    };
+    if (this.abortController.signal.aborted) {
+      abortFromStop();
+    } else {
+      this.abortController.signal.addEventListener('abort', abortFromStop, { once: true });
+    }
+
+    const timeout = setTimeout(() => {
+      if (!controller.signal.aborted) {
+        controller.abort(new Error(`${label} timed out after ${timeoutMs}ms`));
+      }
+    }, timeoutMs);
+    unrefTimer(timeout);
+
+    return {
+      signal: controller.signal,
+      cleanup: () => {
+        clearTimeout(timeout);
+        this.abortController.signal.removeEventListener('abort', abortFromStop);
+      },
+    };
+  }
+
+  // ============================================================================
+  // Stable Project Mapping
+  // ============================================================================
+
+  private getProjectMappingId(
+    sourceConn: interfaces.data.IProviderConnection,
+    sourceProjectId: string,
+  ): string {
+    return encodeURIComponent(`${sourceConn.id}:${sourceProjectId}`);
+  }
+
+  private getProjectMappingKey(
+    configId: string,
+    sourceConn: interfaces.data.IProviderConnection,
+    sourceProjectId: string,
+  ): string {
+    return `${SYNC_MAPPING_PREFIX}${configId}/${this.getProjectMappingId(sourceConn, sourceProjectId)}.json`;
+  }
+
+  private getRepoStatusKey(syncConfigId: string, sourceFullPath: string): string {
+    const hash = this.sanitizePath(sourceFullPath).replace(/\//g, '__');
+    return `${SYNC_STATUS_PREFIX}${syncConfigId}/${hash}.json`;
+  }
+
+  private isApiNotFoundError(err: unknown): boolean {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    return errMsg.includes(': 404 -') || errMsg.includes(': 404 ');
+  }
+
+  private async fetchProjectRawOptional(
+    conn: interfaces.data.IProviderConnection,
+    fullPath: string,
+  ): Promise<any | null> {
+    try {
+      return await this.fetchProjectRaw(conn, fullPath);
+    } catch (err) {
+      if (this.isApiNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+
+  private getRawProjectId(rawProject: any): string | undefined {
+    return rawProject?.id ? String(rawProject.id) : undefined;
+  }
+
+  private async getProjectMapping(
+    config: interfaces.data.ISyncConfig,
+    sourceConn: interfaces.data.IProviderConnection,
+    project: interfaces.data.IProject,
+  ): Promise<interfaces.data.ISyncProjectMapping | null> {
+    const key = this.getProjectMappingKey(config.id, sourceConn, project.id);
+    const direct = await this.storageManager.getJSON<interfaces.data.ISyncProjectMapping>(key);
+    if (direct) return direct;
+
+    const statusFromCurrentPath = await this.storageManager.getJSON<interfaces.data.ISyncRepoStatus>(
+      this.getRepoStatusKey(config.id, project.fullPath),
+    );
+    if (statusFromCurrentPath?.targetFullPath) {
+      return {
+        id: this.getProjectMappingId(sourceConn, project.id),
+        syncConfigId: config.id,
+        sourceConnectionId: sourceConn.id,
+        sourceProjectId: project.id,
+        sourceFullPath: project.fullPath,
+        targetConnectionId: config.targetConnectionId,
+        targetFullPath: statusFromCurrentPath.targetFullPath,
+        targetProjectId: statusFromCurrentPath.targetProjectId,
+        updatedAt: Date.now(),
+      };
+    }
+
+    const statusKeys = await this.storageManager.list(`${SYNC_STATUS_PREFIX}${config.id}/`);
+    for (const statusKey of statusKeys) {
+      const status = await this.storageManager.getJSON<interfaces.data.ISyncRepoStatus>(statusKey);
+      if (status?.sourceProjectId === project.id && status.targetFullPath) {
+        return {
+          id: this.getProjectMappingId(sourceConn, project.id),
+          syncConfigId: config.id,
+          sourceConnectionId: sourceConn.id,
+          sourceProjectId: project.id,
+          sourceFullPath: status.sourceFullPath,
+          targetConnectionId: config.targetConnectionId,
+          targetFullPath: status.targetFullPath,
+          targetProjectId: status.targetProjectId,
+          updatedAt: Date.now(),
+        };
+      }
+    }
+
+    return null;
+  }
+
+  private async reconcileProjectMapping(
+    config: interfaces.data.ISyncConfig,
+    project: interfaces.data.IProject,
+    sourceConn: interfaces.data.IProviderConnection,
+    targetConn: interfaces.data.IProviderConnection,
+    targetFullPath: string,
+  ): Promise<void> {
+    const mapping = await this.getProjectMapping(config, sourceConn, project);
+    if (!mapping) return;
+
+    const previousTargetPath = syncpath.normalizeSyncPath(mapping.targetFullPath);
+    const nextTargetPath = syncpath.normalizeSyncPath(targetFullPath);
+    if (previousTargetPath === nextTargetPath) return;
+
+    logger.syncLog(
+      'info',
+      `Project mapping moved for source ID ${project.id}: ${mapping.targetFullPath} -> ${targetFullPath}`,
+      'sync',
+    );
+
+    const targetProjectId = await this.moveMappedProjectTarget(
+      config,
+      project,
+      sourceConn,
+      targetConn,
+      mapping,
+      targetFullPath,
+    );
+
+    await this.persistProjectMapping(config, project, sourceConn, targetConn, targetFullPath, {
+      id: targetProjectId,
+    });
+  }
+
+  private async moveMappedProjectTarget(
+    config: interfaces.data.ISyncConfig,
+    project: interfaces.data.IProject,
+    sourceConn: interfaces.data.IProviderConnection,
+    targetConn: interfaces.data.IProviderConnection,
+    mapping: interfaces.data.ISyncProjectMapping,
+    targetFullPath: string,
+  ): Promise<string | undefined> {
+    const nextProviderFullPath = this.computeProviderProjectFullPath(targetConn, targetFullPath);
+    const previousProviderFullPath = this.computeProviderProjectFullPath(targetConn, mapping.targetFullPath);
+    const existingTarget = await this.fetchProjectRawOptional(targetConn, nextProviderFullPath);
+    const existingTargetId = this.getRawProjectId(existingTarget);
+    if (existingTarget) {
+      if (mapping.targetProjectId && existingTargetId === mapping.targetProjectId) {
+        return existingTargetId;
+      }
+      throw new Error(
+        `Cannot move mapped project ${project.fullPath}: target path "${targetFullPath}" already exists`,
+      );
+    }
+
+    const previousTarget = await this.fetchProjectRawOptional(targetConn, previousProviderFullPath);
+    const previousTargetId = this.getRawProjectId(previousTarget);
+    if (!previousTarget) {
+      logger.syncLog(
+        'warn',
+        `Stored target path "${mapping.targetFullPath}" no longer exists for source ID ${project.id}; creating fresh target`,
+        'sync',
+      );
+      return undefined;
+    }
+
+    if (mapping.targetProjectId && previousTargetId && previousTargetId !== mapping.targetProjectId) {
+      throw new Error(
+        `Cannot move mapped project ${project.fullPath}: stored target path "${mapping.targetFullPath}" belongs to a different project`,
+      );
+    }
+
+    await this.moveProjectPath(
+      config,
+      project,
+      sourceConn,
+      targetConn,
+      previousTarget,
+      mapping.targetFullPath,
+      targetFullPath,
+    );
+    return previousTargetId;
+  }
+
+  private async moveProjectPath(
+    config: interfaces.data.ISyncConfig,
+    project: interfaces.data.IProject,
+    sourceConn: interfaces.data.IProviderConnection,
+    targetConn: interfaces.data.IProviderConnection,
+    rawProject: any,
+    previousTargetFullPath: string,
+    nextTargetFullPath: string,
+  ): Promise<void> {
+    const segments = nextTargetFullPath.split('/');
+    const projectPath = segments.pop()!;
+    const groupSegments = segments;
+
+    if (targetConn.providerType === 'gitlab') {
+      const namespaceId = await this.ensureGitLabGroupPath(
+        targetConn,
+        groupSegments,
+        sourceConn,
+        sourceConn.groupFilter,
+        config.targetGroupOffset,
+      );
+      const rawProjectId = this.getRawProjectId(rawProject);
+      if (!rawProjectId) {
+        throw new Error(`Cannot move ${previousTargetFullPath}: missing target project ID`);
+      }
+
+      if (namespaceId && String(rawProject.namespace?.id) !== String(namespaceId)) {
+        await this.rawApiCall(targetConn, 'PUT', `/api/v4/projects/${rawProjectId}/transfer`, {
+          namespace: namespaceId,
+        });
+      }
+      await this.rawApiCall(targetConn, 'PUT', `/api/v4/projects/${rawProjectId}`, {
+        name: project.name,
+        path: projectPath,
+      });
+      logger.syncLog('success', `Moved GitLab project ${previousTargetFullPath} to ${nextTargetFullPath}`, 'api');
+      return;
+    }
+
+    const previousRepo = this.getGiteaRepoCoordinates(previousTargetFullPath, targetConn);
+    const nextRepo = this.getGiteaRepoCoordinates(nextTargetFullPath, targetConn);
+    const client = new plugins.giteaClient.GiteaClient(targetConn.baseUrl, targetConn.token);
+
+    try {
+      await client.getOrg(nextRepo.owner);
+    } catch {
+      await client.createOrg(nextRepo.owner, { visibility: 'private' });
+    }
+
+    if (previousRepo.owner !== nextRepo.owner) {
+      await this.rawApiCall(
+        targetConn,
+        'POST',
+        `/api/v1/repos/${encodeURIComponent(previousRepo.owner)}/${encodeURIComponent(previousRepo.repo)}/transfer`,
+        { new_owner: nextRepo.owner },
+      );
+    }
+
+    if (previousRepo.repo !== nextRepo.repo) {
+      await this.rawApiCall(
+        targetConn,
+        'PATCH',
+        `/api/v1/repos/${encodeURIComponent(nextRepo.owner)}/${encodeURIComponent(previousRepo.repo)}`,
+        { name: nextRepo.repo },
+      );
+    }
+    logger.syncLog('success', `Moved Gitea repo ${previousTargetFullPath} to ${nextTargetFullPath}`, 'api');
+  }
+
+  private getGiteaRepoCoordinates(
+    fullPath: string,
+    conn: interfaces.data.IProviderConnection,
+  ): { owner: string; repo: string } {
+    const segments = fullPath.split('/');
+    const projectName = segments.pop()!;
+    const groupSegments = segments;
+    return {
+      owner: groupSegments[0] || conn.groupFilter || 'default',
+      repo: groupSegments.length > 1
+        ? [...groupSegments.slice(1), projectName].join('-')
+        : projectName,
+    };
+  }
+
+  private async persistProjectMapping(
+    config: interfaces.data.ISyncConfig,
+    project: interfaces.data.IProject,
+    sourceConn: interfaces.data.IProviderConnection,
+    targetConn: interfaces.data.IProviderConnection,
+    targetFullPath: string,
+    targetRawProject?: any,
+  ): Promise<void> {
+    const previousMapping = await this.getProjectMapping(config, sourceConn, project);
+    if (previousMapping && previousMapping.sourceFullPath !== project.fullPath) {
+      await this.storageManager.delete(this.getRepoStatusKey(config.id, previousMapping.sourceFullPath));
+    }
+
+    const mapping: interfaces.data.ISyncProjectMapping = {
+      id: this.getProjectMappingId(sourceConn, project.id),
+      syncConfigId: config.id,
+      sourceConnectionId: sourceConn.id,
+      sourceProjectId: project.id,
+      sourceFullPath: project.fullPath,
+      targetConnectionId: targetConn.id,
+      targetFullPath,
+      targetProjectId: this.getRawProjectId(targetRawProject),
+      updatedAt: Date.now(),
+    };
+    await this.storageManager.setJSON(
+      this.getProjectMappingKey(config.id, sourceConn, project.id),
+      mapping,
+    );
   }
 
   // ============================================================================
@@ -549,8 +1423,51 @@ export class SyncManager {
     targetGroupOffset?: string,
   ): Promise<void> {
     const client = new plugins.gitlabClient.GitLabClient(conn.baseUrl, conn.token);
+    const parentId = await this.ensureGitLabGroupPath(
+      conn,
+      groupSegments,
+      sourceConn,
+      sourceGroupFilter,
+      targetGroupOffset,
+    );
+
+    // Create the project if it doesn't exist
+    const projectPath = groupSegments.length > 0
+      ? `${groupSegments.join('/')}/${projectName}`
+      : projectName;
+
+    try {
+      // Check if project exists by path
+      await client.getGroup(projectPath);
+      // If this succeeds, it's actually a group, not a project... unlikely but handle
+    } catch {
+      // Project doesn't exist as a group path; try creating it
+      try {
+        await client.createProject(projectName, {
+          path: projectName,
+          namespaceId: parentId,
+          description: sourceProject.description,
+          visibility: sourceProject.visibility || 'private',
+        });
+        logger.info(`Created GitLab project: ${projectPath}`);
+      } catch (createErr: any) {
+        // Already exists is fine
+        if (!String(createErr).includes('409') && !String(createErr).includes('already been taken')) {
+          throw createErr;
+        }
+      }
+    }
+  }
+
+  private async ensureGitLabGroupPath(
+    conn: interfaces.data.IProviderConnection,
+    groupSegments: string[],
+    sourceConn?: interfaces.data.IProviderConnection,
+    sourceGroupFilter?: string,
+    targetGroupOffset?: string,
+  ): Promise<number | undefined> {
+    const client = new plugins.gitlabClient.GitLabClient(conn.baseUrl, conn.token);
 
-    // Walk group hierarchy top-down, creating each if needed
     let parentId: number | undefined = undefined;
     let currentPath = '';
 
@@ -560,13 +1477,11 @@ export class SyncManager {
         const group = await client.getGroup(currentPath);
         parentId = group.id;
       } catch {
-        // Group doesn't exist — create it
         try {
           const newGroup = await client.createGroup(segment, segment, parentId);
           parentId = newGroup.id;
           logger.info(`Created GitLab group: ${currentPath}`);
         } catch (createErr: any) {
-          // 409 = already exists (race condition), try fetching again
           if (String(createErr).includes('409') || String(createErr).includes('already')) {
             const group = await client.getGroup(currentPath);
             parentId = group.id;
@@ -576,7 +1491,6 @@ export class SyncManager {
         }
       }
 
-      // Sync group metadata from source (once per group per sync cycle)
       if (sourceConn && !this.syncedGroupMeta.has(currentPath)) {
         const sourceGroupPath = this.reverseTargetGroupPath(currentPath, sourceGroupFilter, targetGroupOffset);
         if (sourceGroupPath) {
@@ -586,32 +1500,7 @@ export class SyncManager {
       }
     }
 
-    // Create the project if it doesn't exist
-    const projectPath = groupSegments.length > 0
-      ? `${groupSegments.join('/')}/${projectName}`
-      : projectName;
-
-    try {
-      // Check if project exists by path
-      await client.getGroup(projectPath);
-      // If this succeeds, it's actually a group, not a project... unlikely but handle
-    } catch {
-      // Project doesn't exist as a group path; try creating it
-      try {
-        await client.createProject(projectName, {
-          path: projectName,
-          namespaceId: parentId,
-          description: sourceProject.description,
-          visibility: sourceProject.visibility || 'private',
-        });
-        logger.info(`Created GitLab project: ${projectPath}`);
-      } catch (createErr: any) {
-        // Already exists is fine
-        if (!String(createErr).includes('409') && !String(createErr).includes('already been taken')) {
-          throw createErr;
-        }
-      }
-    }
+    return parentId;
   }
 
   private async ensureGiteaTarget(
@@ -686,7 +1575,7 @@ export class SyncManager {
       const targetFullPath = this.computeTargetFullPath(
         project.fullPath, sourceConn.groupFilter, config.targetGroupOffset,
       );
-      expectedTargetPaths.add(targetFullPath.toLowerCase());
+      expectedTargetPaths.add(this.computeProviderProjectFullPath(targetConn, targetFullPath).toLowerCase());
     }
 
     // Scope prefix — only delete repos under this prefix
@@ -700,7 +1589,7 @@ export class SyncManager {
     for (const targetProject of targetProjects) {
       if (this.isObsoletePath(targetProject.fullPath)) continue;
       // Skip repos outside our managed prefix
-      if (scopePrefix && !targetProject.fullPath.toLowerCase().startsWith(scopePrefix.toLowerCase() + '/')) {
+      if (!this.isTargetProjectInScope(targetConn, targetProject.fullPath, scopePrefix)) {
         continue;
       }
       if (!expectedTargetPaths.has(targetProject.fullPath.toLowerCase())) {
@@ -857,7 +1746,8 @@ export class SyncManager {
     const allRepos: any[] = [];
     let page = 1;
     const perPage = 50;
-    while (true) {
+    const maxPages = 1000;
+    while (page <= maxPages) {
       const repos = await this.rawApiCall(
         targetConn, 'GET',
         `/api/v1/orgs/${encodeURIComponent(orgName)}/repos?page=${page}&limit=${perPage}`,
@@ -867,6 +1757,9 @@ export class SyncManager {
       if (repoList.length < perPage) break;
       page++;
     }
+    if (page > maxPages) {
+      throw new Error(`Gitea org repo pagination exceeded ${maxPages} pages for ${orgName}`);
+    }
 
     // Move each repo to obsolete
     for (const repo of allRepos) {
@@ -914,11 +1807,7 @@ export class SyncManager {
   }
 
   private computeRelativePath(fullPath: string, groupFilter?: string): string {
-    if (!groupFilter) return fullPath;
-    if (fullPath.startsWith(groupFilter + '/')) {
-      return fullPath.substring(groupFilter.length + 1);
-    }
-    return fullPath;
+    return syncpath.computeRelativePath(fullPath, groupFilter);
   }
 
   /**
@@ -930,27 +1819,7 @@ export class SyncManager {
     sourceGroupFilter?: string,
     targetGroupOffset?: string,
   ): string | null {
-    let relativePath = targetGroupPath;
-
-    // Strip the target offset prefix
-    if (targetGroupOffset) {
-      if (targetGroupPath === targetGroupOffset) {
-        // This IS the offset group itself, not a source-derived group
-        return null;
-      }
-      if (targetGroupPath.startsWith(targetGroupOffset + '/')) {
-        relativePath = targetGroupPath.substring(targetGroupOffset.length + 1);
-      } else {
-        // Target path is not under the offset — can't reverse-map
-        return null;
-      }
-    }
-
-    // Re-add the source group filter prefix
-    if (sourceGroupFilter) {
-      return `${sourceGroupFilter}/${relativePath}`;
-    }
-    return relativePath;
+    return syncpath.reverseTargetGroupPath(targetGroupPath, sourceGroupFilter, targetGroupOffset);
   }
 
   private computeTargetFullPath(
@@ -958,8 +1827,7 @@ export class SyncManager {
     sourceGroupFilter?: string,
     targetGroupOffset?: string,
   ): string {
-    const relativePath = this.computeRelativePath(sourceFullPath, sourceGroupFilter);
-    return targetGroupOffset ? `${targetGroupOffset}/${relativePath}` : relativePath;
+    return syncpath.computeTargetFullPath({ sourceFullPath, sourceGroupFilter, targetGroupOffset });
   }
 
   /**
@@ -1019,12 +1887,20 @@ export class SyncManager {
       } else {
         headers['Authorization'] = `token ${conn.token}`;
       }
-      const resp = await fetch(url, { headers });
-      if (!resp.ok) {
-        await resp.body?.cancel();
-        return null;
+      const apiSignal = this.createTransferAbortSignal(RAW_API_TIMEOUT_MS, `GET ${url}`);
+      try {
+        const resp = await fetch(url, {
+          headers,
+          signal: apiSignal.signal,
+        });
+        if (!resp.ok) {
+          await resp.body?.cancel();
+          return null;
+        }
+        return new Uint8Array(await resp.arrayBuffer());
+      } finally {
+        apiSignal.cleanup();
       }
-      return new Uint8Array(await resp.arrayBuffer());
     } catch {
       return null;
     }
@@ -1048,15 +1924,25 @@ export class SyncManager {
       headers['Authorization'] = `token ${conn.token}`;
     }
     // Do NOT set Content-Type — let fetch set the multipart boundary
-    const resp = await fetch(url, { method, headers, body: formData });
-    if (!resp.ok) {
-      const text = await resp.text();
-      throw new Error(`${method} ${apiPath}: ${resp.status} - ${text}`);
-    }
+    const apiSignal = this.createTransferAbortSignal(RAW_API_TIMEOUT_MS, `${method} ${apiPath}`);
     try {
-      return await resp.json();
-    } catch {
-      return undefined;
+      const resp = await fetch(url, {
+        method,
+        headers,
+        body: formData,
+        signal: apiSignal.signal,
+      });
+      if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`${method} ${apiPath}: ${resp.status} - ${text}`);
+      }
+      try {
+        return await resp.json();
+      } catch {
+        return undefined;
+      }
+    } finally {
+      apiSignal.cleanup();
     }
   }
 
@@ -1669,19 +2555,26 @@ export class SyncManager {
     } else {
       headers['Authorization'] = `token ${conn.token}`;
     }
-    const resp = await fetch(url, {
-      method,
-      headers,
-      body: body ? JSON.stringify(body) : undefined,
-    });
-    if (!resp.ok) {
-      const text = await resp.text();
-      throw new Error(`${method} ${apiPath}: ${resp.status} - ${text}`);
-    }
+    const apiSignal = this.createTransferAbortSignal(RAW_API_TIMEOUT_MS, `${method} ${apiPath}`);
+    let resp!: Response;
     try {
-      return await resp.json();
-    } catch {
-      return undefined;
+      resp = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: apiSignal.signal,
+      });
+      if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`${method} ${apiPath}: ${resp.status} - ${text}`);
+      }
+      try {
+        return await resp.json();
+      } catch {
+        return undefined;
+      }
+    } finally {
+      apiSignal.cleanup();
     }
   }
 
@@ -1873,8 +2766,8 @@ export class SyncManager {
         provider.getTags(fullPath),
       ]);
       return {
-        branches: new Map(branches.map((b) => [b.name, b.commitSha])),
-        tags: new Map(tags.map((t) => [t.name, t.commitSha])),
+        branches: new Map(branches.map((b: interfaces.data.IBranch) => [b.name, b.commitSha])),
+        tags: new Map(tags.map((t: interfaces.data.ITag) => [t.name, t.commitSha])),
       };
     } catch {
       return null;
@@ -2011,7 +2904,7 @@ export class SyncManager {
 
       child.stdout.on('data', (chunk: Uint8Array) => stdoutChunks.push(chunk));
       child.stderr.on('data', (chunk: Uint8Array) => stderrChunks.push(chunk));
-      child.on('error', (err) => finish(() => reject(err)));
+      child.on('error', (err: Error) => finish(() => reject(err)));
       child.on('close', (code: number | null, signal: NodeJS.Signals | null) => finish(() => {
         const stderr = plugins.Buffer.concat(stderrChunks).toString('utf8');
         if (code !== 0) {
@@ -2024,6 +2917,89 @@ export class SyncManager {
     });
   }
 
+  private async runCommand(
+    command: string,
+    args: string[],
+    cwd?: string,
+    options: IRunCommandOptions = {},
+  ): Promise<string> {
+    if (this.stopping) {
+      throw new Error('SyncManager is stopping');
+    }
+
+    return await new Promise<string>((resolve, reject) => {
+      const child = plugins.childProcess.spawn(command, args, {
+        cwd,
+        env: { ...process.env, ...options.env },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      this.activeGitChildren.add(child);
+      const stdoutChunks: Uint8Array[] = [];
+      const stderrChunks: Uint8Array[] = [];
+      let stdoutBytes = 0;
+      let stderrBytes = 0;
+      let settled = false;
+      let timedOut = false;
+      let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+      let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+
+      const appendChunk = (chunks: Uint8Array[], chunk: Uint8Array, currentBytes: number): number => {
+        const nextBytes = currentBytes + chunk.byteLength;
+        const remainingBytes = MAX_COMMAND_OUTPUT_BYTES - currentBytes;
+        if (remainingBytes > 0) {
+          chunks.push(chunk.byteLength <= remainingBytes ? chunk : chunk.subarray(0, remainingBytes));
+        }
+        return nextBytes;
+      };
+
+      const finish = (callback: () => void): void => {
+        if (settled) return;
+        settled = true;
+        if (timeoutTimer) clearTimeout(timeoutTimer);
+        if (forceKillTimer) clearTimeout(forceKillTimer);
+        this.activeGitChildren.delete(child);
+        callback();
+      };
+
+      if (options.timeoutMs) {
+        timeoutTimer = setTimeout(() => {
+          timedOut = true;
+          if (child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGTERM');
+            forceKillTimer = setTimeout(() => {
+              if (child.exitCode === null && child.signalCode === null) {
+                child.kill('SIGKILL');
+              }
+            }, 5000);
+            unrefTimer(forceKillTimer);
+          }
+        }, options.timeoutMs);
+        unrefTimer(timeoutTimer);
+      }
+
+      child.stdout.on('data', (chunk: Uint8Array) => {
+        stdoutBytes = appendChunk(stdoutChunks, chunk, stdoutBytes);
+      });
+      child.stderr.on('data', (chunk: Uint8Array) => {
+        stderrBytes = appendChunk(stderrChunks, chunk, stderrBytes);
+      });
+      child.on('error', (err: Error) => finish(() => reject(err)));
+      child.on('close', (code: number | null, signal: NodeJS.Signals | null) => finish(() => {
+        const stderr = plugins.Buffer.concat(stderrChunks).toString('utf8');
+        if (timedOut) {
+          reject(new Error(`${command} timed out after ${options.timeoutMs}ms: ${stderr.trim()}`));
+          return;
+        }
+        if (code !== 0) {
+          const exitInfo = signal ? `signal ${signal}` : `code ${code}`;
+          reject(new Error(`${command} failed with ${exitInfo}: ${stderr.trim()}`));
+          return;
+        }
+        resolve(plugins.Buffer.concat(stdoutChunks).toString('utf8'));
+      }));
+    });
+  }
+
   // ============================================================================
   // Persistence
   // ============================================================================
@@ -2060,7 +3036,7 @@ export class SyncManager {
     updates: Partial<interfaces.data.ISyncRepoStatus>,
   ): Promise<void> {
     const hash = this.sanitizePath(sourceFullPath).replace(/\//g, '__');
-    const key = `${SYNC_STATUS_PREFIX}${syncConfigId}/${hash}.json`;
+    const key = this.getRepoStatusKey(syncConfigId, sourceFullPath);
     let status = await this.storageManager.getJSON<interfaces.data.ISyncRepoStatus>(key);
     if (!status) {
       status = {