Skip to content

Latest commit

 

History

History
415 lines (321 loc) · 23.1 KB

README.md

File metadata and controls

415 lines (321 loc) · 23.1 KB

GitHub Workflows Documentation

This document explains the GitHub Actions workflows structure and strategy for this JavaScript monorepo managed with Lerna and pnpm.

📋 Table of Contents

🔍 Overview

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 summary job
  • Comprehensive testing and quality checks

🏗️ Workflow Structure

Workflow Files

.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

Trigger Strategy

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

Workflow Execution Flow

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.

CI Workflow

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
Loading

Publish Dev Workflow

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]
Loading

Publish Master Workflow

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]
Loading

Publish Pre-Release Workflow

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]
Loading

📋 Workflow Details

1. CI Workflow (ci.yml)

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.

2. Publish Dev Workflow (publish-dev.yml)

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-pages always contains the latest master storybook at the root and the dev (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.

3. Publish Master Workflow (publish-master.yml)

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 storybook job overrides both with contents: write alone, which is all a gh-pages push 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):

  1. Sync: lerna.json is rewritten in the working tree to the latest vX.Y.Z tag (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).
  2. Bump: lerna version --conventional-commits --no-git-tag-version --no-push computes the next version from the commits since that tag and writes it to the manifests, without committing.
  3. Publish: after the build, the bump is committed locally (Lerna refuses a dirty tree), an annotated vX.Y.Z tag is created on the commit that was pushed to master, the tag is pushed with the built-in GITHUB_TOKEN, and lerna publish from-package --git-head $GITHUB_SHA publishes 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:

  1. Creates a GitHub Release for vX.Y.Z with gh 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.

  2. 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 when dev/alpha is ahead of master: pre-release tags for a future version (e.g. v1.4.0-alpha.* still in active use while master ships v1.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 with sort -V, which is not semver-aware for pre-release suffixes (it orders 1.3.0-alpha.0 after 1.3.0). The workflow therefore strips the -alpha.N / -beta.N suffix and compares only the plain X.Y.Z base versions, which sort -V orders correctly (including 1.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 publish job 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 master and dev is refreshed together so GitHub Pages always reflects the latest released and in-flight docs.
  • Summary with version context: The summary job consumes needs.publish.outputs.new-version / release-tag so the report shows exactly what was (or would have been) released.

4. Publish Pre-Release Workflow (publish-prerelease.yml)

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, -beta tags are ignored), preventing versions from jumping between channels.
  • Resync guard: When lerna.json drifts from the latest tag, the workflow re-aligns it before versioning so lerna computes the next prerelease from a clean baseline.
  • Canary publish: lerna publish from-git --canary publishes exactly the tagged versions to Nexus, keeping pre-releases clearly separated from production NPM.
  • Summary with channel context: The summary job reports the resolved pre-release channel (alpha / beta) and the exact version published to Nexus.

🔒 Concurrency / Release Serialization

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 master release runs, an alpha/beta push is held as pending and only starts once the release finishes (and vice versa).
  • cancel-in-progress: false ensures a running release is never cancelled by a newly queued run — releases always complete.
  • Why it matters: the master release pushes the vX.Y.Z tag and then prunes pre-release tags. Serializing guarantees no concurrent alpha/beta run 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/beta pushes 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.

Storybook deploys

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 dev validation 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 master and dev, 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 a ref, actions/checkout pins 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 storybook job is the same in both files; change them together.

🧾 Summary Jobs

All four workflows end with a summary job that:

  • Runs on ubuntu-24.04
  • Declares needs on 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' }}

🔧 Custom Actions

node-setup Action

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:

  1. Install pnpm (pnpm/action-setup@v6) — the version is read from the root package.json packageManager field, so it is not duplicated here.
  2. Setup Node.js (actions/setup-node@v7) with pnpm cache enabled.
  3. pnpm install (with PUPPETEER_SKIP_DOWNLOAD=true to defer Chrome download).
  4. Resolve the installed Puppeteer version — a Puppeteer release pins exactly one Chrome build, so its version is what the Chrome cache is keyed on.
  5. Cache Puppeteer Chrome binary under ~/.cache/puppeteer/, keyed by ${{ runner.os }}-chrome-puppeteer-<version>.
  6. Run pnpm postinstall inside packages/ui-components/node_modules/puppeteer to materialize the Chrome binary (cache hit or download).

Usage:

- name: Setup Node.js
  uses: ./.github/actions/node-setup
  with:
      node-version: 24.x

Branch Types & Workflows

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

Version Strategy

  • Production (master): 1.2.3 — semantic versioning via lerna version with conventional commits, published to NPM with provenance.
  • Alpha (alpha branch): 1.2.3-alpha.N — lerna version prerelease --preid=alpha, canary-published to Nexus.
  • Beta (beta branch): 1.2.3-beta.N — lerna version prerelease --preid=beta, canary-published to Nexus.

🔐 Secrets

Required Secrets

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

Required Permissions

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

🔍 Troubleshooting

Common Issues

1. NPM / Nexus Authentication Failures

# 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

2. Lerna Version / Tag Issues

# 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-run

3. Pre-Release Version Drift

If 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

4. Puppeteer Chrome Download Failures

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

5. Storybook Deploy Problems

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

6. Missing / Empty Step Summary

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

Debug Tips

  1. Enable Debug Logging: Set ACTIONS_STEP_DEBUG: true as a secret.
  2. Local Testing: Run pnpm lint, pnpm test, pnpm build:packages, and pnpm storybook:build locally before pushing.
  3. Lerna Dry Runs: Use --dry-run on lerna version / lerna publish when diagnosing release issues.
  4. Workflow Logs: Each job's step logs show the exact pnpm / lerna command and its output.
  5. Step Summary: Each workflow run's landing page renders the summary job's Markdown output — a quick glance shows job status, released version, and deployment outcomes.

📚 Additional Resources


For questions or issues, please contact the frontend team or create an issue in the repository.