This document explains the GitHub Actions workflows structure and strategy for this JavaScript monorepo managed with Lerna and pnpm.
- Overview
- Workflow Structure
- Workflow Execution Flow
- Workflow Details
- Custom Actions
- Secrets
- Troubleshooting
- Additional Resources
Our CI/CD pipeline is designed around a monorepo strategy with multiple packages managed by Lerna and pnpm workspaces. The workflows are optimized for:
- Fast feedback on pull requests through linting, testing, and builds
- Reliable releases with Lerna-driven versioning
- Clear separation between production, pre-release, and storybook preview flows
- Storybook publishing to GitHub Pages for both stable and alpha docs
- Per-workflow step summary generated as a dedicated
summaryjob - Comprehensive testing and quality checks
.github/
├── workflows/
│ ├── ci.yml # Pull request validation
│ ├── publish-dev.yml # Storybook publishing from dev branch
│ ├── publish-master.yml # Production releases (master branch) + storybook
│ └── publish-prerelease.yml # Alpha/Beta pre-releases to Nexus
├── actions/
│ └── node-setup/ # Node.js + pnpm environment setup
└── README.md # This file
| Workflow | Trigger | Purpose |
|---|---|---|
| CI | Pull requests to dev or master |
Validate code quality, run tests, build packages and storybook |
| Publish Dev | Push to dev branch |
Rebuild and deploy the alpha storybook alongside the master storybook to GitHub Pages |
| Publish Master | Push to master branch |
Version, publish packages to NPM, and deploy storybook to GitHub Pages |
| Publish Pre-Release | Push to alpha/beta branches (or manual dispatch) |
Publish pre-release packages to the internal Nexus registry |
Each workflow terminates in a dedicated summary job that runs with if: always() and writes a Markdown report to $GITHUB_STEP_SUMMARY, regardless of whether the upstream job succeeded, failed, or was skipped.
graph TD
PR[PR to dev/master] --> L[Lint]
PR --> B[Build and core typecheck]
B --> D[Documentation]
B --> T[Unit tests]
B --> C[React compatibility, browser tests and Storybook]
L --> S[Summary]
D --> S
T --> S
C --> S
graph TD
A[Push to dev] --> B[publish job]
B --> C[lint]
C --> D[test]
D --> E[build:packages]
E --> S["storybook job (one deploy at a time)"]
S --> F[Build master storybook → ./gp]
F --> G[Build dev storybook → ./gp/alpha]
G --> H[Deploy combined output to gh-pages]
H --> I[summary]
I --> J[End]
graph TD
A[Push to master] --> B[publish job]
B --> C[lint]
C --> D[test]
D --> E[sync lerna.json to latest tag + lerna version → outputs new-version]
E --> F[build:packages]
F --> G[tag vX.Y.Z on the pushed commit + lerna publish from-package → NPM]
G --> H[Create GitHub Release for vX.Y.Z]
H --> I["Remove pre-release tags ≤ vX.Y.Z (*-alpha.* / *-beta.*)"]
I --> S["storybook job (one deploy at a time)"]
S --> J[Build master storybook → ./gp]
J --> K[Build dev storybook → ./gp/alpha]
K --> L[Deploy combined output to gh-pages]
L --> M[summary]
M --> N[End]
graph TD
A[Push to alpha/beta] --> B[publish job]
B --> C[Validate branch]
C --> D[Resolve last + current version]
D --> E[lerna version prerelease]
E --> F[Capture new-version output]
F --> G[build:packages]
G --> H[Configure Nexus auth]
H --> I[lerna publish --canary → Nexus]
I --> J[Push git tag]
J --> K[summary]
K --> L[End]
Purpose: Validates pull requests targeting dev or master with linting, tests, and full builds.
Lint and Build run independently on Ubuntu 24.04 with Node 24. Documentation, Unit tests and React consumers download the package outputs and Stencil metadata from Build. The separate core typecheck runs after Stencil generates components.d.ts. Summary runs even after a failure and requires every job to succeed.
The Documentation job tests generators, explicitly generates catalogs, checks freshness and verifies committed outputs. The consumer job tests isolated React 18 and React 19 installs before browser tests and Storybook. Command semantics and build prerequisites are in code quality.
Purpose: Keeps the public storybook on GitHub Pages up to date with the dev (alpha) branch, alongside the latest master storybook.
Strategy: A publish job that validates the branch, a storybook job that deploys both storybooks, and a summary job.
Jobs:
├── publish # Lint + Test + Build
├── storybook # Build master + dev storybooks, deploy them to gh-pages (same job as publish-master)
└── summary # Writes Publish Dev Summary to $GITHUB_STEP_SUMMARY (if: always())Why this approach?
- Single source of truth for docs:
gh-pagesalways contains the latestmasterstorybook at the root and thedev(alpha) storybook under/alpha. - Lint + test gate: The storybook is only deployed if the working branch passes validation.
- Summary always runs: Reports deployment status for both storybooks even on failure.
Purpose: Creates production releases from master and redeploys the storybook site.
Strategy: Sequential publish job covering versioning and publishing, a storybook job that redeploys the docs once the release is out, and a summary job that surfaces the released version.
Jobs:
├── publish # Lint + Test + lerna version (from latest tag) + build + tag + lerna publish from-package
│ # + GitHub Release + pre-release tag cleanup
│ # Exposes outputs: new-version, release-tag (read from lerna.json after version)
├── storybook # Build master + dev storybooks, deploy them to gh-pages (same job as publish-dev)
└── summary # Writes Release Summary (including version/tag) to $GITHUB_STEP_SUMMARY (if: always())Permissions:
contents: write— required to push the release tag, create the GitHub Release, and delete pre-release tags.id-token: write— required for NPM provenance via OIDC (NPM_CONFIG_PROVENANCE: true).- The
storybookjob overrides both withcontents: writealone, which is all agh-pagespush needs.
No release commit on master:
master only accepts changes through pull requests, so the workflow never pushes a commit to it. The latest production vX.Y.Z tag is the source of truth for the version, not the manifests in git (which stay at whatever version was last committed):
- Sync:
lerna.jsonis rewritten in the working tree to the latestvX.Y.Ztag (pre-release tags excluded). The step fails if the pushed commit already carries a production tag (a re-run after a failed publish needs that tag deleted first) or if the latest release is not an ancestor of the commit (re-running an old run after a newer release would otherwise publish stale source under a higher version). - Bump:
lerna version --conventional-commits --no-git-tag-version --no-pushcomputes the next version from the commits since that tag and writes it to the manifests, without committing. - Publish: after the build, the bump is committed locally (Lerna refuses a dirty tree), an annotated
vX.Y.Ztag is created on the commit that was pushed tomaster, the tag is pushed with the built-inGITHUB_TOKEN, andlerna publish from-package --git-head $GITHUB_SHApublishes the manifests' versions to NPM with registry metadata pointing at the pushed commit. The local commit is discarded with the runner.
Release notes live on the GitHub Release; no CHANGELOG.md is generated.
Release & pre-release tag cleanup:
After the publish step pushes the production vX.Y.Z tag, the workflow:
-
Creates a GitHub Release for
vX.Y.Zwithgh release create— auto-generated notes (--generate-notes), marked as--latest, and tag-verified (--verify-tag). The step is idempotent: if a release for the tag already exists it is skipped rather than failing the run. -
Removes the pre-release tags matching
*-alpha.*or*-beta.*whose base version (X.Y.Z) is<=the version just released, from both the remote and the local checkout. Once a production version ships, the alpha/beta tags that led up to it are no longer needed, so the tag list stays limited to shipped production releases. The cleanup deletes each tag individually so an already-removed tag does not abort the run, and logs when there is nothing to remove.The
<=bound is deliberate. It keeps the cleanup correct even whendev/alphais ahead ofmaster: pre-release tags for a future version (e.g.v1.4.0-alpha.*still in active use while master shipsv1.3.1) have a higher base version and are left untouched. It is also a second line of defense against a mid-release tag push — the concurrency serialization below is the primary guard for that.⚠️ Base versions are compared withsort -V, which is not semver-aware for pre-release suffixes (it orders1.3.0-alpha.0after1.3.0). The workflow therefore strips the-alpha.N/-beta.Nsuffix and compares only the plainX.Y.Zbase versions, whichsort -Vorders correctly (including1.10.0 > 1.3.0).
Why this approach?
- Atomic release: Versioning, building, publishing, GitHub release creation, and tag cleanup live in one job; a failure in any step halts the release. The docs deploy runs in its own job afterwards. A failed deploy still fails the run, but the
publishjob and the summary's release rows stay green, and Re-run failed jobs redeploys the docs without re-running the release. - Provenance: Production packages are published with NPM provenance for supply-chain traceability.
- Discoverable releases: Every production version gets a corresponding GitHub Release with generated notes, so the Releases page mirrors what is on NPM.
- Clean tag history: Pre-release (
*-alpha.*/*-beta.*) tags are pruned on each production release, keeping the tag list focused on shipped versions. - Consistent docs: Storybook for
masteranddevis refreshed together so GitHub Pages always reflects the latest released and in-flight docs. - Summary with version context: The
summaryjob consumesneeds.publish.outputs.new-version/release-tagso the report shows exactly what was (or would have been) released.
Purpose: Publishes alpha and beta pre-release packages to the internal Nexus registry for testing.
Strategy: Sequential publish job with branch-aware version resolution, followed by a summary job. Also supports manual runs via workflow_dispatch.
Jobs:
├── publish # Validate branch + resolve versions + lerna prerelease + build + publish to Nexus
│ # Exposes outputs: new-version, release-tag, prerelease-id
└── summary # Writes Pre-Release Summary (including channel + version) to $GITHUB_STEP_SUMMARY (if: always())Why this approach?
- Channel isolation: Tag lookup filters out the opposite channel (e.g. on
alpha,-betatags are ignored), preventing versions from jumping between channels. - Resync guard: When
lerna.jsondrifts from the latest tag, the workflow re-aligns it before versioning solernacomputes the next prerelease from a clean baseline. - Canary publish:
lerna publish from-git --canarypublishes exactly the tagged versions to Nexus, keeping pre-releases clearly separated from production NPM. - Summary with channel context: The
summaryjob reports the resolved pre-release channel (alpha/beta) and the exact version published to Nexus.
publish-master.yml and publish-prerelease.yml share a single top-level concurrency group so the release workflows are never in flight at the same time:
concurrency:
group: release-pipeline
cancel-in-progress: false- Same group name across both workflows means GitHub treats their runs as one serialized queue: while a
masterrelease runs, analpha/betapush is held as pending and only starts once the release finishes (and vice versa). cancel-in-progress: falseensures a running release is never cancelled by a newly queued run — releases always complete.- Why it matters: the master release pushes the
vX.Y.Ztag and then prunes pre-release tags. Serializing guarantees no concurrentalpha/betarun pushes a tag during that window, so the cleanup can't race a fresh tag. (The pre-release cleanup is also version-bounded as a second line of defense — see Publish Master Workflow.)
ℹ️ Queue depth: A concurrency group keeps at most one running and one pending run. If several release runs pile up behind an in-flight one, only the newest pending run is retained; older pending runs are cancelled. In practice releases don't stack this quickly, but be aware a rapid burst of
alpha/betapushes during a long master release may collapse to the latest one.publish-dev.yml(storybook only) is intentionally left out of the group so docs previews are never blocked by a release.
publish-dev.yml and publish-master.yml both force-push gh-pages from their storybook job. That job, and only that job, is in a second group:
storybook:
concurrency:
group: storybook-pages
cancel-in-progress: false- Deploys take turns. Without the group, two deploys could overlap and one push fails with
cannot lock ref 'refs/heads/gh-pages'. - Set on the job, not the workflow. A release or a
devvalidation run is never held behind a deploy, and is never the pending run that gets replaced. A pending pre-release still waits for the whole master run, deploy included. - Replacing a pending deploy loses nothing. Each deploy checks out and builds the latest
masteranddev, so the newer one covers the older one. The replaced job shows as cancelled, and the summary reports it as replaced. - Branch tips, not the event's commit. The job checks out
ref: dev. Without aref,actions/checkoutpins the branch that triggered the run to the event's commit, so a deploy that ran late, or a re-run of an old run, would publish stale docs for that branch. - The
storybookjob is the same in both files; change them together.
All four workflows end with a summary job that:
- Runs on
ubuntu-24.04 - Declares
needson the workflow's other jobs ([publish, storybook]in the two Storybook-deploying workflows) so it runs after them - Uses
if: always()so the summary is written on success, failure, and cancelation - Appends a Markdown report to
$GITHUB_STEP_SUMMARY, which GitHub renders on the workflow run page
Each report includes:
| Section | Content |
|---|---|
| Header | Workflow name + context (commit, branch, environment) |
| Version info | new-version / release-tag (release workflows only) |
| Component Status | Status chip per job (Success / Skipped / Failed) |
| Action-specific summary | NPM publish, Nexus publish, storybook deploy status, git tag push, etc. |
| Next steps / outcome | Short closing note about what just happened |
The status chips are rendered from the needs.<job>.result expression using a GitHub Actions ternary:
${{ needs.publish.result == 'success' && '✅ Success'
|| needs.publish.result == 'skipped' && '⏭️ Skipped'
|| '❌ Failed' }}Purpose: Standardizes the pnpm + Node.js environment (and Puppeteer Chrome cache) across all workflows.
Inputs:
node-version— Node.js version to set up (e.g.24.x).
Steps:
- Install pnpm (
pnpm/action-setup@v6) — the version is read from the rootpackage.jsonpackageManagerfield, so it is not duplicated here. - Setup Node.js (
actions/setup-node@v7) with pnpm cache enabled. pnpm install(withPUPPETEER_SKIP_DOWNLOAD=trueto defer Chrome download).- Resolve the installed Puppeteer version — a Puppeteer release pins exactly one Chrome build, so its version is what the Chrome cache is keyed on.
- Cache Puppeteer Chrome binary under
~/.cache/puppeteer/, keyed by${{ runner.os }}-chrome-puppeteer-<version>. - Run
pnpm postinstallinsidepackages/ui-components/node_modules/puppeteerto materialize the Chrome binary (cache hit or download).
Usage:
- name: Setup Node.js
uses: ./.github/actions/node-setup
with:
node-version: 24.x| Branch | Event | Workflow | Purpose |
|---|---|---|---|
master |
push | publish-master.yml |
Production NPM release + storybook |
dev |
push | publish-dev.yml |
Alpha storybook deploy |
alpha |
push / dispatch | publish-prerelease.yml |
Alpha pre-release to Nexus |
beta |
push / dispatch | publish-prerelease.yml |
Beta pre-release to Nexus |
dev/master |
pull request | ci.yml |
Validation only |
- Production (
master):1.2.3— semantic versioning vialerna versionwith conventional commits, published to NPM with provenance. - Alpha (
alphabranch):1.2.3-alpha.N—lerna version prerelease --preid=alpha, canary-published to Nexus. - Beta (
betabranch):1.2.3-beta.N—lerna version prerelease --preid=beta, canary-published to Nexus.
| Secret | Purpose | Used In |
|---|---|---|
GITHUB_TOKEN |
Built-in token for checkout, tagging, and gh-pages deploy | All workflows |
NPM_TOKEN |
NPM registry authentication for production publishes | publish-dev.yml, publish-master.yml |
NEXUS_AUTH |
Base64 auth string for the internal Nexus registry | publish-prerelease.yml |
| Workflow | contents |
id-token |
Notes |
|---|---|---|---|
ci.yml |
default | — | Read-only validation |
publish-dev.yml |
write |
— | Required to push storybook to gh-pages |
publish-master.yml |
write |
write |
id-token: write enables NPM provenance |
publish-prerelease.yml |
write |
— | Needed for version commits and tag pushes |
# Production (publish-master): check NPM_TOKEN is valid and has publish rights
# Nexus (publish-prerelease): check NEXUS_AUTH is a valid base64 "user:token" string
# For gh-pages deploys: ensure GITHUB_TOKEN has contents: write permission# Ensure full git history is fetched
fetch-depth: 0 in the checkout step
# Inspect what lerna would do locally before pushing:
pnpm lerna version --dry-run
pnpm lerna version prerelease --preid=alpha --dry-runIf publish-prerelease.yml fails because lerna.json doesn't match the latest tag of the current channel, the workflow's resync step should handle it automatically. If it still fails:
# Manually align lerna.json with the latest alpha/beta tag, commit, and rerun
git tag -l --sort=-version:refname | grep -v '\-beta' # for alpha channel
git tag -l --sort=-version:refname | grep -v '\-alpha' # for beta channel# node-setup caches Chrome under ~/.cache/puppeteer/.
# If the cache key changes (puppeteer upgrade), the postinstall step downloads Chrome again.
# Verify packages/ui-components/node_modules/puppeteer exists after pnpm install.# publish-dev and publish-master build two storybooks into ./gp and ./gp/alpha
# with --dry-run, then deploy with --existing-output-dir='./gp'. Only that last
# call pushes to gh-pages, so a failed build deploys nothing.
#
# Pass the flags after exactly one `--`:
# pnpm storybook:deploy -- --out='./gp' --dry-run
# lerna forwards everything after it to storybook-to-ghpages. An extra `--` gets
# forwarded as well, and the deployer then ignores every flag after it: each call
# builds into a temporary directory and force-pushes it to gh-pages.# The summary job uses `if: always()` and `needs` on the workflow's other jobs.
# If no summary appears, check:
# - The `needs` reference matches the actual job id (e.g. `ci`, `publish`).
# - The primary job is not producing an `outputs` name that differs from the summary
# references (e.g. `needs.publish.outputs.new-version`).
# - The workflow run didn't fail before any job started (e.g. YAML parse error).- Enable Debug Logging: Set
ACTIONS_STEP_DEBUG: trueas a secret. - Local Testing: Run
pnpm lint,pnpm test,pnpm build:packages, andpnpm storybook:buildlocally before pushing. - Lerna Dry Runs: Use
--dry-runonlerna version/lerna publishwhen diagnosing release issues. - Workflow Logs: Each job's step logs show the exact pnpm / lerna command and its output.
- Step Summary: Each workflow run's landing page renders the
summaryjob's Markdown output — a quick glance shows job status, released version, and deployment outcomes.
- Lerna Documentation
- pnpm Documentation
- GitHub Actions Documentation
- GitHub Actions Job Summaries
- Semantic Versioning
- NPM Provenance
For questions or issues, please contact the frontend team or create an issue in the repository.