Repository navigation
ci(release): add CalVer release guards and cut-sdk-release workflow - #96
Conversation
damaz91
left a comment
There was a problem hiding this comment.
Thanks for putting this together—the pre-publish guards, checksum-verified ucp-schema setup, dist-tag epoch gating, and GitHub App release automation align well with ucp#909 and python-sdk#106.
Requesting changes mainly to hold merging until the prerequisite lockfile branch lands and to address a couple of workflow ordering/concurrency issues:
- Sequencing & rebase: Both workflows depend on
ucp-lock.jsonand the new./generate_models.shflags (--from-lock,--channel,--ref,--write-lock) fromfeat/ucp-lock-and-draft-channel, which has not merged intomainyet. Once that branch merges, please rebase ontomain(which now includes#95) to clear the failingCommitted models match regenerationcheck. - Cross-branch test compatibility for
2026-08-25: See inline note oncut-sdk-release.ymlregardingdraft-onlycart_idassertions intests/open-unions.test.jsonfeat/ucp-lock-and-draft-channelwhen cuttingrelease/2026-08-25. - Workflow fixes (inline):
- Add a workflow-level
concurrencygroup torelease.ymlso concurrent releases across epochs cannot race ondist-tags.latest. - Run
npm run buildbeforenpm testincut-sdk-release.ymlso tests validate freshly compileddist/output rather than stale artifacts built duringnpm ci. - Validate
ucp_shaanducp_schema_versioninucp-lock.jsonand pass--ignore-scriptswhen upgrading globalnpmin thereleaseenvironment.
- Add a workflow-level
Operational reminder before the first cut:
- Enable Allow npm dist-tag on
@ucp-js/sdkin the npmjs.com Trusted Publisher settings sonpm dist-tag addcan attachrelease-YYYY-MM-DD. - When
release/**branch protection rulesets are added onjs-sdk, include theucp-automationGitHub App in the bypass list socut-sdk-release.ymlcan push directly torelease/YYYY-MM-DD.
| if [[ "$BUMP" == "initial" ]]; then | ||
| if git show-ref --verify --quiet "refs/remotes/origin/release/${SPEC_VERSION}"; then | ||
| echo "::error::Branch release/${SPEC_VERSION} already exists; use bump=patch or bump=minor" | ||
| exit 1 | ||
| fi | ||
| git checkout -B "release/${SPEC_VERSION}" origin/main | ||
| NEW_VERSION="${YYYYMMDD}.0.0" |
There was a problem hiding this comment.
bump=initial branches release/${SPEC_VERSION} from origin/main. Now that the CalVer floor includes 2026-08-25, note that feat/ucp-lock-and-draft-channel updates tests/open-unions.test.js with two draft-only cart_id assertions (CheckoutCompleteRequestSchema.shape.cart_id === undefined and cart_id-only CheckoutCreateRequestSchema), which fail npm test when src/spec_generated.ts is regenerated from ucp release/2026-08-25.
Before cutting release/2026-08-25 via this workflow, tests/open-unions.test.js on feat/ucp-lock-and-draft-channel should gate those two assertions on ucp-lock.json (channel === "draft" vs release/2026-08-25)—or release/2026-08-25 should be branched before main switches to draft-only test assertions.
| exit "$TAG_CHECK_RC" | ||
| fi | ||
|
|
||
| UCP_SCHEMA_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('ucp-lock.json', 'utf8')).ucp_schema_version")" |
There was a problem hiding this comment.
Validate UCP_SCHEMA_VERSION (e.g., [[ "$UCP_SCHEMA_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]) before writing it to $GITHUB_ENV and interpolating it into the download URL below—if the key is missing in ucp-lock.json, node -p prints literal "undefined". Also consider adding --retry 3 and trap 'rm -rf "$TMP_BIN"' EXIT to the curl download step below to match python-sdk#106.
There was a problem hiding this comment.
Done in c7578ee. Added strict jq -er SemVer validation on UCP_SCHEMA_VERSION (plus canonical date -u -d calendar validation on SPEC_VERSION), and added curl --retry 3 with trap 'rm -rf "$TMP_BIN"' EXIT on the binary download.
| npm test | ||
| npm run build |
There was a problem hiding this comment.
Swap these two lines so npm run build runs before npm test:
| npm test | |
| npm run build | |
| npm run build | |
| npm test |
With "prepare": "npm run build" in package.json (on feat/ucp-lock-and-draft-channel), npm ci in the previous step populates dist/ from the pre-regeneration src/spec_generated.ts (for example, draft models from origin/main during bump=initial). Because tests/lockfile-and-build.test.js only runs npm run build when dist/ is missing, running npm test first tests the stale dist/ artifacts rather than the newly regenerated release models.
There was a problem hiding this comment.
Done in c7578ee. Swapped the order so npm run build runs before npm test, ensuring tests/lockfile-and-build.test.js validates freshly compiled dist/ artifacts from the regenerated release models.
| git push "$REMOTE_URL" "HEAD:refs/heads/release/${SPEC_VERSION}" | ||
|
|
||
| if [[ "$PUBLISH_RELEASE" == "true" ]]; then | ||
| git tag -a "v${NEW_VERSION}" -m "Release v${NEW_VERSION}" | ||
| git push "$REMOTE_URL" "refs/tags/v${NEW_VERSION}" | ||
| gh release create "v${NEW_VERSION}" \ | ||
| --repo "$REPOSITORY" \ | ||
| --target "release/${SPEC_VERSION}" \ | ||
| --title "v${NEW_VERSION}" \ | ||
| --generate-notes | ||
| fi |
There was a problem hiding this comment.
If this workflow is run with publish_release: false (or if gh release create fails transiently after line 223 pushes chore(release): v${NEW_VERSION} to release/${SPEC_VERSION}), re-running the workflow cannot publish v${NEW_VERSION}: bump=initial fails because the branch now exists, and bump=patch skips v${NEW_VERSION} and bumps to .1.
Consider either supporting tagging/releasing an existing untagged HEAD version on retry, or noting in the workflow description that commits pushed with publish_release: false must be tagged and released manually.
There was a problem hiding this comment.
Done in c7578ee. Added bump=publish-existing (with remote head non-movement verification) to validate, tag (--verify-tag), and publish an existing untagged HEAD version on release/YYYY-MM-DD, plus a loud failure if git diff --cached is empty during bump=initial or bump=patch, and epoch-guarded --latest / --latest=false on gh release create.
| # limitations under the License. | ||
|
|
||
| name: Release | ||
| on: |
There was a problem hiding this comment.
Add a workflow-level concurrency group so two releases across different epochs cannot run concurrently and race on dist-tags.latest:
concurrency:
group: npm-release-publish
cancel-in-progress: falseWithout serialization, if 2026-08-25 and 2026-12-08 releases are published around the same time (for example, while dist-tags.latest is 0.5.1 -> LATEST_EPOCH=0), both runs can observe LATEST_EPOCH=0 and pass 10#$YYYYMMDD >= 10#$LATEST_EPOCH; if the older epoch finishes npm publish --tag latest second, it will overwrite latest.
There was a problem hiding this comment.
Done in c7578ee. Added workflow-level concurrency (group: npm-release-publish, cancel-in-progress: false) along with timeout-minutes: 15 so concurrent releases across epochs serialize cleanly before evaluating dist-tags.latest.
| LOCK_CHANNEL="$(node -p "JSON.parse(require('fs').readFileSync('ucp-lock.json', 'utf8')).channel")" | ||
| LOCK_REF="$(node -p "JSON.parse(require('fs').readFileSync('ucp-lock.json', 'utf8')).ucp_ref")" | ||
| UCP_SCHEMA_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('ucp-lock.json', 'utf8')).ucp_schema_version")" | ||
| if [[ "$LOCK_CHANNEL" != "release" || "$LOCK_REF" != "$EXPECTED_BRANCH" ]]; then | ||
| echo "::error::ucp-lock.json must have channel='release' and ucp_ref='$EXPECTED_BRANCH' (got channel='$LOCK_CHANNEL', ucp_ref='$LOCK_REF')" | ||
| exit 1 | ||
| fi |
There was a problem hiding this comment.
Mirroring python-sdk#106, also validate ucp_sha (^[0-9a-f]{40}$) and ucp_schema_version (^[0-9]+\.[0-9]+\.[0-9]+$) from ucp-lock.json here before using UCP_SCHEMA_VERSION in the binary download URL below (and consider adding --retry 3 + trap 'rm -rf "$TMP_BIN"' EXIT on lines 112–121).
There was a problem hiding this comment.
Done in c7578ee. Added fail-closed jq -er validation for ucp_sha (^[0-9a-f]{40}$) and ucp_schema_version (^[0-9]+\.[0-9]+\.[0-9]+$), curl --retry 3 + trap cleanup, an upstream blobless ucp clone verifying ucp_sha is an ancestor of origin/release/${YYYY}-${MM}-${DD} via --spec-dir, and untracked-aware git status --porcelain drift verification.
| EXPECTED_VERSION: ${{ env.EXPECTED_VERSION }} | ||
| run: | | ||
| set -euo pipefail | ||
| npm install -g "npm@^11.21.0" |
There was a problem hiding this comment.
Since this step runs inside the release environment with id-token: write, pass --ignore-scripts (and consider pinning an exact tested 11.x version, e.g. npm@11.21.3) so global npm installation from the public registry cannot execute package lifecycle scripts in the Trusted Publisher environment:
| npm install -g "npm@^11.21.0" | |
| npm install -g --ignore-scripts "npm@^11.21.0" |
There was a problem hiding this comment.
Done in c7578ee. Updated the global npm upgrade step to npm install -g --ignore-scripts "npm@^11.21.0" inside the release environment.
ea0d18c to
c1819f5
Compare
cb7dee9 to
c7578ee
Compare
damaz91
left a comment
There was a problem hiding this comment.
LGTM! Thanks for addressing all the review feedback, @gsmith85—the npm-release-publish concurrency serialization, npm run build before npm test ordering, publish-existing recovery mode, upstream ucp_sha ancestry and lockfile provenance checks, and --ignore-scripts global npm upgrade all look solid, and #98 has landed on main.
Summary
release.ymlwith serializednpm-release-publishconcurrency, full-history checkouts, SHA256-verifieducp-schemainstallation, canonical CalVer tag and calendar-date validation (>= 20260825), manifest version anducp-lock.jsonprovenance guards, upstreamucprelease-branchucp_shaancestry verification,pre-commitPrettier andgit status --porcelaindrift checks, and--ignore-scriptsnpm@^11.21.0Trusted Publisher dist-tag epoch gating.cut-sdk-release.ymlsupportinginitial,patch,minor, andpublish-existingcuts forrelease/YYYY-MM-DD(>= 2026-08-25), runningnpm run buildprior tonpm test, enforcing tag non-existence preflight checks, and publishing tag-verified GitHub Releases with epoch-guarded--latest/--latest=falseflags via the automation GitHub App.Refs Universal-Commerce-Protocol/ucp#909