orbital migrate plan

orbital migrate plan is the first step in any migration. It logs into your existing registry, enumerates every repository, samples the size, and emits a JSON envelope you feed to orbital migrate apply later.

The CLI is a thin layer over POST /api/admin/migrate/plan — every backend the bulk-import surface already supports flows through unchanged. The plan call never persists the source credential on the server side; it lives in the request body, is used to build a single in-memory client, and is dropped at the end of the request.

Supported sources

Source	--source value	Auth shape
JFrog Artifactory	jfrog	bearer / API token
Sonatype Nexus 3	nexus	password or user:password
GitHub Packages	github	PAT with read:packages (--github-org)
GitLab Package Registry	gitlab	PAT (--gitlab-project-id xor --gitlab-group-id)
Azure Artifacts	azure	PAT (--azure-organization)
AWS CodeArtifact	awscodeartifact	keys:AKIA…:secret[:session] or bearer:<token>
Google Artifact Registry	gcparhybrid	sa:<service-account JSON> or bearer:<oauth>

The full set lives in api/internal/migrate.SupportedSources; new adapters are wired in lock-step with the bulk-import handler.

Quick start

# Persist OrbitalReg credentials once
orbital auth login --endpoint https://registry.example.com --token "$ORBITAL_TOKEN"

# JFrog Artifactory inventory
orbital migrate plan \
  --source jfrog \
  --endpoint https://jfrog.example.com \
  --token "$JFROG_TOKEN" \
  --output-file migration-plan.json

Sample output (pretty-printed):

Migration plan — source=jfrog endpoint=https://jfrog.example.com
  Generated:    2026-05-06T12:00:00Z
  Repositories: 47
  Formats:      docker, helm, maven, npm, pypi
  Artifacts:    ~12000 (sampled)
  Total size:   ~85.20 GB (sampled)
  Strategy:     big-bang
  Window:       2 – 4 h downtime
  Notes:
    - artifact_count + total_size_gb are sampled estimates — apply phase walks the full tree.

The same envelope is also written to migration-plan.json for the later orbital migrate apply step (Phase B).

Strategy recommendation

The planner picks one of the three strategies in the migration overview based on the sampled total-size estimate:

Total size	Strategy	Estimated window
< 100 GB	big-bang	30 min – 4 h downtime depending on size
100 GB – 10 TB	blue-green	single-change cutover, double-write warm-up
> 10 TB	lazy-proxy	remote-mode for 7 – 30 days, then finalize

Override the heuristic with --strategy big-bang|blue-green|lazy-proxy when you already know the answer (e.g. compliance disallows blue-green because it requires writes to flow through both registries).

Source-specific flags

GitHub Packages

orbital migrate plan --source github \
  --github-org acme-corp \
  --github-package-type container \
  --token "$GITHUB_PAT"

GitLab Package Registry

# Project-scoped
orbital migrate plan --source gitlab \
  --gitlab-project-id 12345 \
  --token "$GITLAB_PAT"

# Group-scoped (mutually exclusive with --gitlab-project-id)
orbital migrate plan --source gitlab \
  --gitlab-group-id 678 \
  --gitlab-include-container \
  --token "$GITLAB_PAT"

Azure Artifacts

orbital migrate plan --source azure \
  --azure-organization acme-org \
  --azure-project Platform \
  --azure-feed prod-feed \
  --token "$AZURE_PAT"

AWS CodeArtifact

# Static keys (token contains the credentials, not just a bearer)
orbital migrate plan --source awscodeartifact \
  --aws-region eu-west-1 \
  --aws-domain acme \
  --aws-domain-owner 123456789012 \
  --token 'keys:AKIA…:wJal…'

# Or a pre-fetched session token
orbital migrate plan --source awscodeartifact \
  --aws-region eu-west-1 \
  --aws-domain acme \
  --token "bearer:$CODEARTIFACT_AUTH_TOKEN"

Google Artifact Registry

orbital migrate plan --source gcparhybrid \
  --gcp-project-id acme-platform \
  --gcp-location europe-west1 \
  --token "sa:$(cat sa-key.json)"

Output formats

Mode	Flag	Use case
Pretty	(default)	Operator review in a terminal
JSON	--json	Machine-readable for CI scripting
Persisted file	--output-file	Saved input for orbital migrate apply

Exit codes

Code	Meaning
0	Plan generated successfully
1	User error (bad flag, conflicting source extras, OrbitalReg returned 400)
2	Auth error (no OrbitalReg token, OrbitalReg returned 401 / 403)
3	Server / source error (OrbitalReg returned 5xx, source registry unreachable)

OrbitalReg surfaces source-side discovery failures as 502 Bad Gateway so a "wrong source token" maps to exit code 3 (server error) rather than 1 (user error). That keeps the exit-code grammar predictable: 1 means "fix your flags", 3 means "the source is misbehaving — check the URL or the credential the source-side admin issued you".

Phase B + onwards

orbital migrate apply (Phase B) consumes the JSON envelope this command writes; orbital migrate verify (Phase C) sha256-compares migrated artifacts against the source; and finalize ships in a follow-up phase. The plan JSON is forward- compatible — saving a plan today and applying it tomorrow is supported.

For step-by-step strategy guidance and verification recipes see the migration overview and the per-source playbooks (JFrog, Nexus, GitLab, GitHub Packages, cloud).