feat: add GitHub workflow and scripts for publishing dev packages to npm #729

Muhammad-Altabba · 2025-10-20T09:11:57Z

PR Description: Automated Dev Package Publishing

Type of PR:

Bugfix
Feature
Documentation
Other

Required reviews:

1
2
3

What this does:

This PR implements an automated CI/CD pipeline for publishing development
versions of npm packages. The workflow publishes packages automatically when
code is merged into epic-** branches and can also be triggered manually via
GitHub Actions UI.

1. GitHub Actions Workflow (`.github/workflows/publish-dev.yml`)

✅ Triggers automatically on push to epic-** branches
✅ Supports manual dispatch with optional reason input
✅ Uses concurrency control to prevent overlapping publishes
✅ Generates detailed release summaries with installation instructions
✅ Builds all packages before publishing
✅ Uses frozen lockfile for reproducible installs

2. Publish Script (`scripts/publish-dev.sh`)

✅ Generates dev versions following format:
{next-version}-dev.{branch-name}.{date}.{commit-hash}.{build-number}
- Example: 1.2.3 → 1.2.4-dev.epic-new-feature.20250120.aeed464a.17 The
  code was tested by publishing to an experimental versions at:
  
  https://www.npmjs.com/package/@nucypher-experimental/taco?activeTab=versions
✅ Handles first-time dev publishes by bumping patch version
✅ Subsequent publishes from same branch reuse base version
✅ Publishes to npm with dev tag for easy installation
✅ Restores original package.json versions after publish (no git changes by a chance if someone executed the publishing locally)
✅ Tracks and reports all published packages with a summary which will be
like:

https://github.com/Muhammad-Altabba/taco-web/actions/runs/18629604101/attempts/1#summary-53112397136
✅ Sanitizes branch names for npm version compatibility

For example change epic-123/test/branch → epic-123-test-branch

3. Package.json Update

✅ Added publish:dev script: ./scripts/publish-dev.sh

4. README.md Documentation

✅ Added "Development Versions" section with:
- Installation instructions for dev packages
- Version format explanation
- Clear guidance on when to use/not use dev versions
- Examples

Issues fixed/closed:

Closes https://github.com/nucypher/sprints/issues/268

Why it's needed:

This feature addresses a critical development workflow gap. Currently,
developers testing new features from epic-** branches must either:

❌ Manually publish packages (time-consuming and error-prone)
❌ Use local linking with npm link or pnpm link (complex setup, path
issues)
❌ Wait for the next official release (delays feedback cycles, blocks testing)

Benefits with automated dev package publishing:

✅ Immediate Testing: Install pre-release versions directly from npm using
@dev tag that is usable in other projects without local linking.

✅ CI/CD Integration: Automated publishing ensures consistency, speed and
reduces human error.

✅ Manual Control: Maintainers can trigger publishes on-demand when needed.

Notes:

To see the manual publishing option, the changes needs to be merged to the default branch. However, for testing the target branch could be set as default, merge to it, then set back the old default branch.
It is easy to change this PR so the publish happens only automatically or manually, if wanted.

Muhammad-Altabba · 2025-10-20T16:11:45Z

At the last commit:

Branch Pattern Restriction

Updated workflow to only trigger automatically on epic branches following the
pattern: epic-v[0-9]+.[0-9]+.x
Examples: epic-v1.0.x, epic-v2.3.x
Auto-trigger temporarily disabled (commented out)

Package Exclusion

Added exclusion logic for pre and test-utils packages.
Manual Version Suffix Support

Added a required version_suffix input for manual workflow triggers
Manual mode: Creates versions like x.y.z-dev.{suffix}.{8-char-hash} with
tag dev-{suffix}
- Example: 0.5.1-dev.access-client.a1b2c3d4 → tag: dev-access-client
Auto mode: Creates versions like x.y.z-dev.{8-char-hash} with tag dev
- Example: 0.5.1-dev.a1b2c3d4 → tag: dev

Version Format Examples

Mode	Version Example	Tag Example	Use Case
Manual	`0.5.1-dev.access-client.a1b2c3d4`	`dev-access-client`	Specific test versions
Auto	`0.5.1-dev.a1b2c3d4`	`dev`	Latest dev from commit

- Support custom version suffixes for manual workflow triggers - Exclude 'pre' and 'test-utils' from dev publishing - Simplify auto-publish versions to use only git hash - Restrict auto-trigger to epic-v*.*.x branches and comment the logic for now

Copilot

Pull Request Overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-20T17:27:10Z

README.md

+- ❌ Production environments
+- ❌ Stable development work
+
+**Note:** Dev versions are automatically published when code is merged to `epic-v*.*.x` branches and can be manually published with custom tags. These versions are unstable and may contain breaking changes or even sometimes broken code..


Double period at the end of the sentence should be a single period.

Suggested change

**Note:** Dev versions are automatically published when code is merged to `epic-v*.*.x` branches and can be manually published with custom tags. These versions are unstable and may contain breaking changes or even sometimes broken code..

**Note:** Dev versions are automatically published when code is merged to `epic-v*.*.x` branches and can be manually published with custom tags. These versions are unstable and may contain breaking changes or even sometimes broken code.

Copilot · 2025-10-20T17:27:11Z

.github/workflows/publish-dev.yml

@@ -0,0 +1,98 @@
+name: Publish Dev Packages
+
+on:


The commented-out push trigger should either be removed or accompanied by a comment explaining why it's disabled, especially since the PR description mentions auto-publishing on push to epic-** branches.

Suggested change

on:

on:

# The push trigger is currently disabled.

# Reason: Auto-publishing on push to epic-v* branches is temporarily suspended pending workflow review and improvements.

# See PR description for details. Uncomment to re-enable automatic publishing on push.

Copilot · 2025-10-20T17:27:11Z

scripts/publish-dev.sh

+    CURRENT_VERSION=$(node -p "require('./${package_json}').version")
+
+    # Check if this is the first dev publish (version doesn't have -dev suffix)
+    if [[ ! "$CURRENT_VERSION" =~ -dev\. ]]; then


The regex pattern -dev\. will not match versions like 1.2.3-dev without a dot after 'dev'. This could cause incorrect version bumping if a package has a -dev suffix without the dot separator. Consider using -dev instead of -dev\. to match both cases.

Suggested change

if [[ ! "$CURRENT_VERSION" =~ -dev\. ]]; then

if [[ ! "$CURRENT_VERSION" =~ -dev(\.|$) ]]; then

Copilot · 2025-10-20T17:27:11Z

scripts/publish-dev.sh

+      echo -e "${BLUE}dev publish - bumping patch version${NC}"
+    else
+      # Subsequent dev publish: strip existing -dev.* suffix to prevent duplication
+      BASE_VERSION="${CURRENT_VERSION%%-dev.*}"


This string manipulation is inconsistent with the regex check on line 46. If line 46 is changed to match -dev without requiring a dot, this line should use ${CURRENT_VERSION%%-dev*} to handle both -dev and -dev. prefixes consistently.

Suggested change

BASE_VERSION="${CURRENT_VERSION%%-dev.*}"

BASE_VERSION="${CURRENT_VERSION%%-dev*}"

manumonti

LGTM! I left some comments tho

manumonti · 2025-10-27T11:24:41Z

README.md

+
 ## Tutorial

 To learn more, follow the tutorial at Threshold


Not related with this PR, but we could also change this line and substitute Threshold Network's docs by TACo's docs.

manumonti · 2025-10-29T10:41:29Z

.github/workflows/publish-dev.yml

+name: Publish Dev Packages
+
+on:
+  #push:


Just curious. Why are we preventing to have this run on push? Maybe I miss some chat about it.

manumonti · 2025-10-29T10:49:17Z

.github/workflows/publish-dev.yml

+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0


nitpick, but this should be enough, shouldn't it?

Suggested change

fetch-depth: 0

fetch-depth: 1

manumonti · 2025-10-29T11:47:06Z

scripts/publish-dev.sh

+      return 0  # true, is excluded
+    fi
+  done
+  return 1  # false, not excluded


in bash 1 is false and 0 is true 🤯

Muhammad-Altabba added 2 commits October 20, 2025 10:22

feat: add GitHub workflow and scripts for publishing dev packages to npm

670c09b

docs: add development version installation guide and usage guidelines

da03a07

Muhammad-Altabba requested review from Copilot, cygnusv, derekpierre, manumonti and theref October 20, 2025 16:24

This comment was marked as outdated.

Sign in to view

Muhammad-Altabba force-pushed the ci/publish-dev-versions-manually-or-on-epic-merge branch from bf6ce81 to fe3f015 Compare October 20, 2025 17:07

Muhammad-Altabba requested a review from Copilot October 20, 2025 17:26

Copilot AI reviewed Oct 20, 2025

View reviewed changes

manumonti approved these changes Oct 29, 2025

View reviewed changes

	Note: Dev versions are automatically published when code is merged to `epic-v..x` branches and can be manually published with custom tags. These versions are unstable and may contain breaking changes or even sometimes broken code..
	Note: Dev versions are automatically published when code is merged to `epic-v..x` branches and can be manually published with custom tags. These versions are unstable and may contain breaking changes or even sometimes broken code.

-on:
+on:
+  # The push trigger is currently disabled.
+  # Reason: Auto-publishing on push to epic-v* branches is temporarily suspended pending workflow review and improvements.
+  # See PR description for details. Uncomment to re-enable automatic publishing on push.

	if [[ ! "$CURRENT_VERSION" =~ -dev\. ]]; then
	if [[ ! "$CURRENT_VERSION" =~ -dev(\.\|$) ]]; then

	BASE_VERSION="${CURRENT_VERSION%%-dev.*}"
	BASE_VERSION="${CURRENT_VERSION%%-dev*}"

feat: add GitHub workflow and scripts for publishing dev packages to npm #729

Are you sure you want to change the base?

feat: add GitHub workflow and scripts for publishing dev packages to npm #729

Uh oh!

Conversation

Muhammad-Altabba commented Oct 20, 2025

PR Description: Automated Dev Package Publishing

What this does:

1. GitHub Actions Workflow (.github/workflows/publish-dev.yml)

2. Publish Script (scripts/publish-dev.sh)

3. Package.json Update

4. README.md Documentation

Issues fixed/closed:

Why it's needed:

Benefits with automated dev package publishing:

Uh oh!

Muhammad-Altabba commented Oct 20, 2025

Version Format Examples

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

manumonti left a comment

Choose a reason for hiding this comment

Uh oh!

manumonti Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

manumonti Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

manumonti Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

manumonti Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

1. GitHub Actions Workflow (`.github/workflows/publish-dev.yml`)

2. Publish Script (`scripts/publish-dev.sh`)