Recipes

Recipes are task walkthroughs for readers who already know the Shipper job they want to complete and need the shortest safe path through it. For CI or container token authentication, use the Containers reference. For failed runs and common recovery paths, start with failed issues and rollback loops.

Adopt an existing repo

Goal

Initialize Shipper in an existing GitHub-backed repository and bring open GitHub issues into the Shipper workflow without recreating them.

Preconditions

You are in the root of a Git checkout with a GitHub remote.
git, gh, and shipper are installed.
GitHub authentication works through gh auth login, or the environment exports GH_TOKEN or GITHUB_TOKEN.
At least one open GitHub issue does not already have a shipper: label.

Steps

Verify GitHub auth before you initialize Shipper:
Terminal window
```
gh auth status
```
In token-based environments, confirm one of the supported token variables is present instead:
Terminal window
```
test -n "${GH_TOKEN:-${GITHUB_TOKEN:-}}"
```
Initialize Shipper from the repository root:
Terminal window
```
shipper init
```
Let shipper init create or update .shipper/, write .shipper/settings.json, and sync the Shipper workflow labels in GitHub. This step must run before adoption so shipper adopt can move issues into an initialized workflow.

If the repo team shares Shipper configuration, commit the generated setup:

git status --short .shipper/
git add .shipper/
git commit -m "chore: initialize shipper"

Adopt one existing issue by number:
Terminal window
```
shipper adopt <issue>
```
Or adopt every open issue that does not already have a shipper: label:
Terminal window
```
shipper adopt --all
```

Verification

Confirm Shipper was initialized locally:

test -f .shipper/settings.json

Confirm the targeted GitHub issue now carries shipper:new:

gh issue view <issue> --json labels -q '.labels[].name' | grep '^shipper:new$'

You can also view adopted issues through Shipper:

shipper issue list --status new