shipper_relocate_repository

shipper_relocate_repository

Replace exactly one missing local registration with an existing checkout of the same repository. Use an exact retained key or local source path, never bare owner/name. Preserves content, history, Auto-ship and Auto-merge without enabling automation, switching active repository, moving files or starting a host. Refresh membership after a stale-source refusal.

When to use

Reconnect exactly one missing local alias using an exact retained key or local source path and an existing destination. Bare owner/name selects managed membership and is refused as a relocation source. No file moves, fetches, clones, active-repository switches, host startup or Auto-ship enablement. Accepts dirty primary working trees and subdirectory selections, rejects bare repositories and linked worktrees, and verifies named or lineage identity. A different repository is refused. Preserves issue content, run history, Auto-ship and Auto-merge choices, generations, safety stops and retry state. Success commits one guarded alias replacement; post-commit refresh warnings remain successful. Explicit relocation advances predecessor membership losslessly to existing registry version 4: protected df2234313 readers refuse before decoding payloads or mutating. Passive reporting changes no saved formats. No protection is promised for pre-S#645 builds.

Behavior hints

• readOnlyHint: false — The tool may intentionally modify repository or workflow state.
• destructiveHint: false — The tool is not expected to remove or rewrite workflow artifacts.
• idempotentHint: false — False: retrying a successfully replaced source refuses; refresh shipper_list_repositories before another action.
• openWorldHint: false — The tool does not reach GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
repository	string	yes	-	Exact retained registration key or missing local source path; bare owner/name is refused.
path	string	yes	-	Existing same-repository primary checkout or subdirectory. Dirty trees are allowed; bare/linked worktrees are refused.

Output schema

Name	Type	Required	Default	Description
status	string	yes	-	-
previousAddress	object	yes	-	-
registration	object	yes	-	-
warnings	array	yes	-	-

Example call

{
  "repository": "retained-key-from-list",
  "path": "/existing/primary-checkout"
}

Example result

{
  "status": "relocated",
  "previousAddress": {
    "kind": "local",
    "path": "/missing/old-checkout"
  },
  "registration": {
    "key": "destination-key",
    "address": {
      "kind": "local",
      "path": "/existing/primary-checkout"
    },
    "repository": {
      "kind": "named",
      "repo": "owner/repo",
      "storageKey": "owner-repo"
    },
    "lifecycle": {
      "status": "active"
    },
    "autoMerge": true,
    "intent": "off",
    "availability": "available",
    "missingCheckout": false,
    "recoveryActions": [],
    "limitations": []
  },
  "warnings": []
}

Error modes

• Stale source: The exact source changed, was restored, is unresolved or is deleting. Refresh membership; do not choose another alias implicitly.
• Destination refused: Identity mismatch, unavailable identity, invalid primary checkout or conflicting retained binding leaves membership unchanged.
• Write failure: Atomic registry replacement failed; the original registration remains. No successful result is returned.

Related tools

• shipper_list_repositories
• shipper_delete_repository
• shipper_register_repository