Skip to content

ci(release): add CalVer release guards and cut-sdk-release workflow - #96

Merged
damaz91 merged 7 commits into
mainfrom
feat/calver-release-workflows
Nov 19, 2026
Merged

damaz91 merged 7 commits into
mainfrom
feat/calver-release-workflows

Conversation

@gsmith85

@gsmith85 gsmith85 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Updates release.yml with serialized npm-release-publish concurrency, full-history checkouts, SHA256-verified ucp-schema installation, canonical CalVer tag and calendar-date validation (>= 20260825), manifest version and ucp-lock.json provenance guards, upstream ucp release-branch ucp_sha ancestry verification, pre-commit Prettier and git status --porcelain drift checks, and --ignore-scripts npm@^11.21.0 Trusted Publisher dist-tag epoch gating.
  • Adds cut-sdk-release.yml supporting initial, patch, minor, and publish-existing cuts for release/YYYY-MM-DD (>= 2026-08-25), running npm run build prior to npm test, enforcing tag non-existence preflight checks, and publishing tag-verified GitHub Releases with epoch-guarded --latest / --latest=false flags via the automation GitHub App.

Refs Universal-Commerce-Protocol/ucp#909

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Nov 5, 2026
@gsmith85
gsmith85 requested a review from damaz91 November 18, 2026 07:33
@damaz91 damaz91 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Nov 18, 2026

@damaz91 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Sequencing & rebase: Both workflows depend on ucp-lock.json and the new ./generate_models.sh flags (--from-lock, --channel, --ref, --write-lock) from feat/ucp-lock-and-draft-channel, which has not merged into main yet. Once that branch merges, please rebase onto main (which now includes #95) to clear the failing Committed models match regeneration check.
  2. Cross-branch test compatibility for 2026-08-25: See inline note on cut-sdk-release.yml regarding draft-only cart_id assertions in tests/open-unions.test.js on feat/ucp-lock-and-draft-channel when cutting release/2026-08-25.
  3. Workflow fixes (inline):
    • Add a workflow-level concurrency group to release.yml so concurrent releases across epochs cannot race on dist-tags.latest.
    • Run npm run build before npm test in cut-sdk-release.yml so tests validate freshly compiled dist/ output rather than stale artifacts built during npm ci.
    • Validate ucp_sha and ucp_schema_version in ucp-lock.json and pass --ignore-scripts when upgrading global npm in the release environment.

Operational reminder before the first cut:

  • Enable Allow npm dist-tag on @ucp-js/sdk in the npmjs.com Trusted Publisher settings so npm dist-tag add can attach release-YYYY-MM-DD.
  • When release/** branch protection rulesets are added on js-sdk, include the ucp-automation GitHub App in the bypass list so cut-sdk-release.yml can push directly to release/YYYY-MM-DD.

Comment on lines +109 to +115
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"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great catch! Addressed in #98 (9329bce): tests/open-unions.test.js (and tests/fulfillment-request-projection.test.js) now branch on ucp-lock.json ucp_ref so both release/2026-08-25 and draft/future release branches pass all unit tests without drift.

Comment thread .github/workflows/cut-sdk-release.yml Outdated
exit "$TAG_CHECK_RC"
fi

UCP_SCHEMA_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('ucp-lock.json', 'utf8')).ucp_schema_version")"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/cut-sdk-release.yml Outdated
Comment on lines +181 to +182
npm test
npm run build

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Swap these two lines so npm run build runs before npm test:

Suggested change
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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/cut-sdk-release.yml Outdated
Comment on lines +223 to +233
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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: false

Without 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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/release.yml Outdated
Comment on lines +79 to +85
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/release.yml Outdated
EXPECTED_VERSION: ${{ env.EXPECTED_VERSION }}
run: |
set -euo pipefail
npm install -g "npm@^11.21.0"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
npm install -g "npm@^11.21.0"
npm install -g --ignore-scripts "npm@^11.21.0"

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in c7578ee. Updated the global npm upgrade step to npm install -g --ignore-scripts "npm@^11.21.0" inside the release environment.

@gsmith85
gsmith85 force-pushed the feat/calver-release-workflows branch from ea0d18c to c1819f5 Compare November 18, 2026 22:38
@gsmith85
gsmith85 force-pushed the feat/calver-release-workflows branch from cb7dee9 to c7578ee Compare November 19, 2026 05:00

@damaz91 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@damaz91
damaz91 merged commit d6bec30 into main Nov 19, 2026
14 checks passed
@damaz91
damaz91 deleted the feat/calver-release-workflows branch November 19, 2026 08:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants