Release-Please Setup

Scaffold or migrate a repository onto release-please. The skill generates release-please-config.json and .release-please-manifest.json from a monorepo package scan, then guides you through wiring the release-please.yml workflow and optionally an opt-in deploy/publish template from the six provided in templates/.

Two modes

Mode	When to use
Greenfield (default)	New repo with no prior tags. All packages start at 0.0.0 (or --initial <ver>).
--migrate	Existing repo with hand-maintained <component>-v* tags. Manifest is seeded from detected file versions; existing deploy workflows keep working unchanged.

Quick start

# SCRIPTS = absolute path to this skill's scripts/ directory
# Always dry-run first — no files are written
python3 SCRIPTS/release_please_setup.py --root . --dry-run            # greenfield
python3 SCRIPTS/release_please_setup.py --root . --migrate --dry-run  # migrate
python3 SCRIPTS/release_please_setup.py --root . --migrate            # write files

CLI flags: --root (repo root), --globs (comma-separated package globs; default packages/*,backend/*,frontend/*), --migrate (migration mode), --single (force single-package config), --initial (starting version; default 0.0.0), --dry-run (print output, no writes), --out-dir (write location; default --root).

Then:

1. Copy templates/release-please.yml into .github/workflows/.
2. Set the REPO_TOKEN secret — see CONTRACT.md. ⚠️ GITHUB_TOKEN-created tags do not trigger other workflows; a PAT is required for deploy templates to fire.
3. Pick a deploy template (optional).

Deploy template menu

Template	Use for
deploy-fly.yml	Fly.io app deploy
publish-npm-oidc.yml	npm Trusted Publishing (OIDC, no token)
release-asset.yml	Build artifact → GitHub Release (e.g. .vsix, .zip)
deploy-docker-matrix.yml	Docker image → Amazon ECR / any registry
deploy-frontend-host.yml	Gated frontend deploy (Amplify, Vercel, Netlify)
deploy-generic.yml	Any build + deploy command
None	Release-please only — add deploy later

Fill all __TOKEN__ placeholders before committing; see WORKFLOW.md for the complete placeholder reference table.

Output structure

<repo-root>/
├── release-please-config.json       ← written by the script
├── .release-please-manifest.json    ← written by the script
└── .github/workflows/
    ├── release-please.yml            ← copy from templates/
    └── deploy-<component>.yml        ← copy from templates/ (optional)

Monorepo: each package gets include-component-in-tag: true, tag-separator: "-", and a mutual exclude-paths matrix (tags like user-service-v1.2.0). Single-package: minimal config, tags are v<semver>.

Common issues

• Release PR not created — check commits follow Conventional Commits, you are on the default branch, and the workflow has contents: write + pull-requests: write permissions.
• Deploy didn't fire — the REPO_TOKEN gotcha; see CONTRACT.md and TROUBLESHOOTING.md.
• Wrong version after migration — discovery missed the version; edit .release-please-manifest.json manually.

References

• WORKFLOW.md — Greenfield and migration runbooks + placeholder reference table
• EXAMPLES.md — Three worked examples (acme monorepo, papia-studio migration, single-package)
• CONTRACT.md — Tag format, REPO_TOKEN gotcha, job outputs, trigger variants
• TROUBLESHOOTING.md — Error reference