chore(release): add release-please automation for versioning

[so0k]

Description

This PR adds release-please automation to manage versioning, CHANGELOG.md generation, and the release PR from Conventional Commits.

The setup is additive: release-please owns versioning and the release PR, while the existing publishing pipeline (release.yml + release-publish.yml, the Sentry release tracking, and the @next prerelease channel) is left untouched and continues to key off package.json as before.

Key design decisions

1. Single root release — this is a locked-version JSII monorepo where all packages ship at the same version. release-please manages only the root "." package; sub-package package.jsons stay at 0.0.0 and are aligned at build time by tools/align-version.sh. Tags are v<version> (include-component-in-tag: false).

2. Pre-1.0 (alpha) bump policy — bump-minor-pre-major + bump-patch-for-minor-pre-major keep breaking changes from prematurely cutting 1.0.0. While the version is 0.x:

   Commit	Bump	Example
   feat! / fix! / BREAKING CHANGE	minor	0.23.3 → 0.24.0
   feat (non-breaking)	patch	0.23.3 → 0.23.4
   fix	patch	0.23.3 → 0.23.4
   chore (dep bumps), docs, …	patch-level	rides along

   Drop these flags to graduate to standard semver / v1 later.

3. GitHub-release ownership stays with release.yml — skip-github-release: true, so release-please only maintains the release PR (version bump + CHANGELOG.md + manifest) and does not create the git tag or GitHub release. release.yml's release_github job (tools/release-github.sh) remains the single, test-gated owner of tag + GitHub release + multi-language publish. No double-create race, and no changes to release.yml.

4. GitHub App token — the workflow mints a short-lived token from the open-constructs-cdktn GitHub App instead of GITHUB_TOKEN, because GITHUB_TOKEN-authored PRs do not trigger downstream workflows (the release PR's own CI would never run).

5. The release PR passes the repo's CI gates:

   • Title — group-pull-request-title-pattern (the pattern that actually applies in manifest mode) yields chore(release): release vX.Y.Z, which passes pr-lint (amannn/action-semantic-pull-request): type chore, scope release.
   • Labels — extra-label attaches the repo's ci/skip-* labels (unit, examples, integration, provider-integration) so the release PR skips the heavy suites it doesn't need, on top of release-please's default autorelease: pending tracking label.

Files added

• release-please-config.json — release-type node, single root package, pre-major bump flags, skip-github-release, conventional title patterns, ci/skip-* labels, and changelog sections mapped to conventional commit types.
• .release-please-manifest.json — source of truth for the last released version, seeded at 0.23.3.
• .github/workflows/release-please.yml — runs on every push to main; mints the App token and maintains the release PR.
• docs/release-please.md — full documentation: versioning model, pre-1.0 policy, release ownership, title/linter interaction, CI-skip labels, App setup, bootstrap, and the future migration path off standard-version.

How it works

1. Conventional commits land on main.
2. release-please.yml keeps one release PR open, rebasing it as more commits land. It bumps the root package.json and prepends a CHANGELOG.md section following the pre-1.0 policy above (breaking → minor; feat/fix → patch).
3. When ready to release, merge the release PR (squash recommended — the conventional title yields a clean chore(release): release vX.Y.Z commit). release-please updates .release-please-manifest.json but does not tag/release (skip-github-release: true).
4. The merge push triggers release.yml, whose stable channel (gated on the release tests) creates the v<version> tag + GitHub release and publishes to npm, PyPI, Maven, NuGet, and Go via release-publish.yml.

Normal (non-release) pushes to main continue publishing the @next prerelease channel as before — release-please only touches the release PR.

bootstrap-sha is pinned to the v0.23.3 release commit so the first release PR collects only the commits after it (no re-scan of history into the changelog).

Checklist

• I have updated the PR title to match CDKTN's style guide
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation if applicable

GitHub App: The open-constructs-cdktn App is installed on this repository with Contents (Read & write) and Pull requests (Read & write) permissions, and its credentials are stored as CDKTN_MAINTAINERS_APP_ID and CDKTN_MAINTAINERS_APP_PRIVATE_KEY repository secrets. ✅

https://claude.ai/code/session_0168ykjbd1W96iSBoQUEkSLE

[sakul-learning]

Ran zizmor v1.25.2 against the new .github/workflows/release-please.yml and, ignoring the other findings, its auto-fix suggests these full SHA pins:

-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2

-        uses: googleapis/release-please-action@v4
+        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4

If Dependabot is configured for GitHub Actions updates, it should be able to maintain these SHA pins while preserving the version comments.

[so0k]

Thanks @sakul-learning — applied both SHA pins in e6a97d8, keeping the # v2/# v4 comments so Dependabot (already configured for github-actions) maintains them:

uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4

Worth noting 5c625bf (release-please-action) is the actual commit the v4 tag resolves to — an earlier API lookup of mine had returned the annotated-tag object SHA instead, so good catch pinning via zizmor.

Also rebased onto main now that v0.23.3 landed (#240): bumped the manifest to 0.23.3 and moved bootstrap-sha to the release commit so release-please takes over from there.

---

Generated by Claude Code

[sakul-learning]

The existing release.yml still has release_github, which runs after release tests and calls yarn release-github. That script also creates a GitHub release for v<version> unless it already exists.

This creates a race / ownership conflict:

• If release-please wins, release_github no-ops.
• If release_github wins, release-please may attempt to create an already-existing release.
• More importantly, release-please creates the GitHub release immediately on the release-PR merge, while release.yml only publishes package artifacts later.

I think this PR should make one workflow the clear owner of GitHub release creation before enabling release-please.

[so0k]

Good catch — fixed in 973b16c by assigning a single owner.

Set skip-github-release: true in release-please-config.json, so release-please now only maintains the release PR (version bump + CHANGELOG.md + manifest) and does not create the tag or GitHub release on merge. release.yml's release_github job (tools/release-github.sh) stays the sole, test-gated owner of tag + GitHub release + artifact publishing — unchanged.

This addresses all three of your points:

• No double-create: only release.yml creates the v<version> release.
• No "already-exists" attempt from release-please — it no longer tries.
• Ordering is preserved: tag + release + artifacts all happen together after the release tests pass, instead of the release appearing immediately on PR merge.

release-please still tracks released versions via .release-please-manifest.json (updated in the merged PR) plus the v<version> tags release.yml creates, which match its expected pattern (include-component-in-tag: false). Docs (docs/release-please.md) now have a "Who owns the GitHub release?" section, and note the alternative if you'd rather flip ownership to release-please later (drop skip-github-release + remove release_github) — kept out of scope to honor the additive/coexist approach.

---

Generated by Claude Code

[sakul-learning]

I ran a release-please release-pr --dry-run against this PR’s release-please config and also simulated main at this PR head to approximate what would happen after merge.

The release mechanics look broadly healthy:

• release-please finds the seeded release v0.23.3.
• It computes the next version as 0.23.4.
• It would open one release PR.
• It would update 7 files, including CHANGELOG.md, root package.json, and .release-please-manifest.json.
• skip-github-release: true means this remains release-PR/version/changelog automation only; tag + GitHub release creation stays with the existing release.yml path.

However, there is one blocking-looking issue from the dry-run: the generated release PR title does not match the repository’s PR title lint requirements.

Dry-run output from the main simulation:

Would open 1 pull requests
fork: false
title: chore: release main
branch: release-please--branches--main
draft: false
updates: 7

The repository PR title lint workflow uses amannn/action-semantic-pull-request and documents/validates titles in the conventional form. The lint error text says:

The format is "type(scope): message"

with release included as an allowed scope. So the generated title:

chore: release main

is unlikely to satisfy the repo’s expected release PR title format. The intended title appears to be something like:

chore(release): release v0.23.4

The CLI output also points at why this is happening. During the dry-run it emitted:

⚠ pullRequestTitlePattern miss the part of '${scope}'
⚠ pullRequestTitlePattern miss the part of '${component}'
⚠ pullRequestTitlePattern miss the part of '${version}'

The configured pattern is:

"pull-request-title-pattern": "chore(release): release v${version}"

but in manifest/merge mode the effective generated title falls back to release-please’s manifest branch-shaped title behavior (chore: release ${branch}), hence chore: release main. I would verify/fix the title pattern in the exact manifest mode used here before merging, otherwise the release PR created by this automation may fail the repo’s own PR title linter.

I also checked the repository merge settings via GitHub GraphQL:

mergeCommitAllowed: true
squashMergeAllowed: true
rebaseMergeAllowed: true
autoMergeAllowed: true
deleteBranchOnMerge: true
squashMergeCommitTitle: PR_TITLE
squashMergeCommitMessage: PR_BODY

So the repository is not squash-only; it allows merge commits, squash merge, and rebase merge. That said, squash merge is enabled and configured to use the PR title/body, which is the important path for preserving a clean conventional commit message from PRs.

This aligns with release-please guidance: release-please supports both squash merge and merge commits for release PRs, but strongly recommends squash merge for cleaner history and more predictable release notes. Given this repo’s PR-title-driven release/changelog conventions, I’d recommend using squash merge for release-please PRs and ensuring the generated release PR title passes the semantic PR title linter.

[so0k]

Thanks for the dry-run @sakul-learning — spot on. Fixed in 88f091c.

Root cause: in manifest mode the release PR title is driven by group-pull-request-title-pattern (default chore: release ${branch} → chore: release main), not the pull-request-title-pattern I'd set. Per the docs, group-pull-request-title-pattern inherits ${version} from the root . package, so I set both patterns to:

"pull-request-title-pattern": "chore(release): release v${version}",
"group-pull-request-title-pattern": "chore(release): release v${version}"

The generated title becomes chore(release): release v0.23.4, which passes the existing pr-lint (amannn/action-semantic-pull-request) unchanged — type chore, allowed scope release. I went with fixing the bot's title rather than loosening the linter so the shared PR-title gate stays intact for all release PRs. Documented the title/linter interaction in docs/release-please.md.

On squash merge: agreed, and the repo already allows it with squashMergeCommitTitle: PR_TITLE. With the conventional title above, squashing the release PR yields a clean chore(release): release vX.Y.Z commit on main (and release-please skips its own release commits on the next run). 👍

One thing I'll verify on the first real release PR: your dry-run noted it would update 7 files. With only the root . package configured (and no node-workspace plugin), I expect just root package.json, CHANGELOG.md, and .release-please-manifest.json — the sub-package package.jsons must stay at 0.0.0 (they're aligned in CI by align-version.sh). If the first release PR touches more than those three, I'll constrain it. Couldn't reproduce your --dry-run from here (no token / egress), so thanks for running it.

---

Generated by Claude Code

[sakul-learning]

I reran the release-please release-pr --dry-run after the latest change (88f091c) using a fresh temp clone that simulates this PR having landed on main.

Simulation directory:

/tmp/cdk-terrain-pr243-merged-to-main-sim-v2

Simulated main at:

88f091c1b fix(release): use conventional release PR title in manifest mode

Dry-run log:

/tmp/cdk-terrain-pr243-release-please-dry-run-main-sim-v2.log

The title issue is fixed. The dry-run now produces:

Would open 1 pull requests
fork: false
title: chore(release): release v0.23.4
branch: release-please--branches--main
draft: false
updates: 7

I also checked that generated title against this repo’s semantic PR title requirements:

title: chore(release): release v0.23.4
shape_match: True
type: chore allowed: True
scope: release allowed: True
subject: release v0.23.4

So the generated release PR title should now pass pr-lint (amannn/action-semantic-pull-request).

On the updates: 7 point: I looked into this in more detail and I do not think it indicates unwanted broad package changes.

The dry-run prints:

updates: 7
❯ Fetching file contents for file package-lock.json on branch main
file package-lock.json did not exist
❯ Fetching file contents for file npm-shrinkwrap.json on branch main
file npm-shrinkwrap.json did not exist
❯ Fetching file contents for file samples/package.json on branch main
file samples/package.json did not exist
❯ Fetching file contents for file CHANGELOG.md on branch main
❯ Fetching file contents for file package.json on branch main
✔ updating from 0.23.3 to 0.23.4
❯ Fetching file contents for file changelog.json on branch main
file changelog.json did not exist
❯ Fetching file contents for file .release-please-manifest.json on branch main

Release-please’s Node strategy creates updater entries for these possible files:

package-lock.json
npm-shrinkwrap.json
samples/package.json
CHANGELOG.md
package.json
changelog.json
.release-please-manifest.json

But the optional files that do not exist are configured with createIfMissing: false. I verified the release-please implementation skips those missing files:

if (!update.createIfMissing) {
  console.warn(`file ${update.path} did not exist`);
  continue;
}

So although the dry-run reports updates: 7, four of those are optional missing-file updater entries and are skipped:

package-lock.json         missing, skipped
npm-shrinkwrap.json       missing, skipped
samples/package.json      missing, skipped
changelog.json            missing, skipped

The actual existing update targets are therefore the expected three files:

CHANGELOG.md
package.json
.release-please-manifest.json

I did not see any sub-package package.json updates in the dry-run output. That matches the intended setup: root . package only, no node-workspace plugin, and subpackages staying at 0.0.0 for the existing build-time alignment flow.

One small remaining note: the CLI still warns that the title pattern is missing ${scope} and ${component}:

⚠ pullRequestTitlePattern miss the part of '${scope}'
⚠ pullRequestTitlePattern miss the part of '${component}'

Since this config intentionally hard-codes the conventional scope as release, and the generated title is now valid, I read those warnings as harmless here rather than a blocker.

Overall: the latest dry-run validates successfully, the generated title now matches the repo linter, and the updates: 7 output does not appear to mean release-please will touch extra workspace package manifests.

[jsteinich]

I still need to look into the action a bit more, but we should add all of the ci/skip-x labels as the release PR doesn't need to run any of those (only updating a version and the changelog).

[sakul-learning]

I ran the follow-up release-please simulations against a temporary main-based workspace with this PR's release-please config/manifest applied, then added one synthetic conventional commit per scenario and ran release-please release-pr --dry-run --local.

Results

Scenario	Synthetic commit	Generated release PR title	Version bump
Non-breaking feature	feat: add simulated non-breaking feature	chore(release): release v0.24.0	0.23.3 → 0.24.0
Breaking feature	feat!: add simulated breaking feature	chore(release): release v1.0.0	0.23.3 → 1.0.0

Both dry-runs opened one release PR and kept the previously validated release PR title shape.

Labels confirmed

The generated release PR object includes these labels:

autorelease: pending
ci/skip-unit
ci/skip-examples
ci/skip-integration
ci/skip-provider-integration

So the configured skip labels are being attached in addition to release-please's default autorelease: pending label.

Pre-v1 / alpha note

Because this repo is still pre-1.0.0, the breaking-change result is the important finding: with the config as currently written, release-please treats a feat! commit as a major release and proposes 1.0.0.

If the intended alpha/pre-v1 policy is instead:

• breaking changes stay within 0.x and bump minor, e.g. 0.23.3 → 0.24.0; and optionally
• regular feat commits bump patch, e.g. 0.23.3 → 0.23.4,

then the config should explicitly set the pre-major bump behavior. I verified the knobs behave as expected in the same simulation:

"bump-minor-pre-major": true
feat! => 0.24.0

"bump-patch-for-minor-pre-major": true
feat => 0.23.4

both options together
feat! => 0.24.0

So I would clarify the intended pre-v1 release policy before merging this automation. If feat! should not cut 1.0.0 yet, add the pre-major bump option(s) now so the first breaking change on main does not unexpectedly graduate the project to v1.

[so0k]

Thanks for the thorough simulation @sakul-learning — and confirming the skip labels attach. Pre-v1 policy is now set in 2920baf.

Confirmed intent: the project stays alpha (0.x) for now — a feat! should not cut 1.0.0. So I added both pre-major flags:

"bump-minor-pre-major": true,
"bump-patch-for-minor-pre-major": true

Which gives exactly the policy you verified, while < 1.0.0:

Commit	Bump	Example
feat! / fix! / BREAKING CHANGE	minor	0.23.3 → 0.24.0
feat (non-breaking)	patch	0.23.3 → 0.23.4
fix	patch	0.23.3 → 0.23.4
chore (dep bumps), docs, …	patch	rides along

Documented the table in docs/release-please.md, including how to graduate to standard semver later (drop the flags). One nuance I called out there: per standard release-please behavior, a chore/docs-only batch won't open a release PR on its own (only feat/fix/breaking do) — those changes ride along as patch-level content in the next release. If you'd want dependency bumps to trigger a patch release on their own, that's a separate cadence decision — happy to look into it if desired.

---

Generated by Claude Code

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days. This helps our maintainers find and focus on the active issues. If you've found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.