| name | release-please-setup |
| description | Scaffold or migrate a repository onto release-please. Generates release-please-config.json, .release-please-manifest.json, and a release-please.yml workflow, plus an opt-in menu of tag-keyed deploy/publish templates (Docker/ECR matrix, frontend host deploy, npm OIDC publish, GitHub Release asset, Fly.io deploy, generic). Supports monorepo (mutual exclude-paths matrix), single-package, and mixed-language (node/simple/python) repos. Use when user runs /release-please-setup, mentions "release please", "set up release please", "automate releases", "conventional-commit releases", "monorepo release automation", or "migrate to release-please". |
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
python3 SCRIPTS/release_please_setup.py --root . --dry-run
python3 SCRIPTS/release_please_setup.py --root . --migrate --dry-run
python3 SCRIPTS/release_please_setup.py --root . --migrate
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:
- Copy
templates/release-please.yml into .github/workflows/.
- 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.
- 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
