shipper adopt

shipper adopt

Usage: shipper adopt [options] [ref]

Adopt an existing issue or pull request into the shipper workflow

Arguments

Argument	Required	Description	Choices
[ref]	no	GitHub issue or pull request number or URL	-

Flags

Long	Short	Value	Default	Description	Choices
—all	-	-	false	adopt all open issues without shipper labels	-

Examples

Adopt one existing GitHub issue by URL.

shipper adopt https://github.com/owner/repo/issues/42

Adopt an existing GitHub PR by URL and start its backing work item at PR review.

shipper adopt https://github.com/owner/repo/pull/17

Adopt every open issue not already tracked by the resolved mirror mode.

shipper adopt --all

Exit Codes

Code	When
0	The selected issue or PR is adopted, or selected issues are imported without per-issue failures.
1	Validation, lookup, PR eligibility, backing issue creation, local import, or mirror mutation fails.

Constraints

• —all and an explicit issue or pull request argument are mutually exclusive
• An issue or pull request argument is required unless —all is used
• --all remains issue-only; there is no bulk PR adoption mode.
• Adoption follows the repository mirrorMode; there is no per-command mirror toggle.
• In mirror-on mode, adoption preserves the existing GitHub label, tracking issue, and association-comment behavior for ordinary untracked issues and PRs. A same-repository issue origin already recorded locally is left unchanged; PR adoption reuses that record and writes only to the PR and the record’s active mirror, when present.
• In store-only mode, adoption imports a local Shipper record, records the GitHub origin as read-only provenance, and leaves source GitHub issues and PRs unchanged.
• In both mirror modes, --all skips issues whose same-repository GitHub origin already exists in the local store. Mirror-on also skips issues that already carry Shipper labels.
• assignMirroredIssuesToSelf defaults to false and follows ordinary user-global, repository, and personal precedence. In mirror-on mode it additively assigns the current GitHub account after direct and bulk issue adoption, newly created PR tracking issues, and newly imported one-reference PR backing issues, preserving existing assignees.
• Assignment is best-effort and write-once: an assignment failure is a warning rather than an adoption error, store-only mode performs no assignment, and later adoption or reconcile runs do not maintain or retry assignees. The same preference applies to mirrors first created by reconcile.
• Adoptable PRs must be open, non-draft, and use a same-repository branch.
• Direct PR adoption checks that the pull request head branch is available before creating or changing any tracking item, association, label, or workflow state.
• If the head branch is checked out outside Shipper managed worktrees, adoption refuses, names the checkout, and tells you to switch that checkout to another branch or remove the separate worktree before retrying. No changes are made.
• If Git cannot verify whether the head branch is checked out elsewhere, adoption refuses with an inconclusive diagnostic that includes the underlying Git or worktree reason. Repair that environment and retry; the failure is not a confirmed conflicting checkout, and no changes are made.
• A PR with one open same-repository closing reference uses that issue as its work item; a PR with none creates a mirror-on tracking issue or a store-only local work item; a PR with multiple is rejected as ambiguous.
• Adopted foreign-branch PRs are linked through Shipper-owned issue comments only in mirror-on mode; store-only records the association locally.
• A PR whose backing issue already has a shipper:* label is rejected only when that issue still resolves to a different open PR.
• Adoption imports the current GitHub issue title/body once into the local issue-state store; later GitHub title/body edits are not authoritative.
• A successful shipper issue unadopt removes the prior local origin and history completely. Explicit or bulk adoption can then import that GitHub issue as a fresh candidate with a new Shipper ID.
• If an adopted PR is closed or superseded, run shipper adopt https://github.com/owner/repo/pull/<current-pr-number> to record the replacement.
• Troubleshooting: local issue-state content or mirror drift
• Troubleshooting: adopted PR closed or superseded