How to Integrate rowboatlabs/rowboat with CI/CD Pipelines

Rowboat provides a complete GitHub Actions-based CI/CD setup that automates building, testing, signing, and publishing across three specialized workflows.

Integrating rowboatlabs/rowboat with your CI/CD pipeline leverages the repository's existing automation infrastructure. The project uses pnpm workspaces and GitHub Actions to manage a complex build graph spanning shared libraries, core business logic, and an Electron desktop application.

Understanding Rowboat's GitHub Actions Workflows

The repository defines three primary workflows under .github/workflows/ that handle different aspects of the delivery pipeline.

Core Library Build (rowboat-build.yml)

The rowboat-build.yml workflow handles continuous integration for the core packages. It triggers on every push and pull_request event, ensuring code quality before merging.

In rowboat-build.yml, the pipeline:

• Checks out the repository using actions/checkout@v4
• Sets up Node.js 20 and pnpm via actions/setup-node@v4 and pnpm/action-setup@v2
• Runs pnpm install --frozen-lockfile for deterministic dependencies
• Executes npm run build to compile the shared and core packages

Electron App Compilation (electron-build.yml)

The electron-build.yml workflow manages the desktop application build, including cross-platform compilation and code signing. It triggers on push, pull_request, and tag pushes matching v*.

Key steps in this workflow include:

• Version stamping: Extracts the version from Git tags using git describe --tags --abbrev=0 and patches package.json files across all workspaces
• Dependency installation: Uses pnpm install --frozen-lockfile to maintain consistency
• Bundling: Executes apps/x/apps/main/bundle.mjs to create a single-file Electron main process (main.cjs) using esbuild, eliminating the need for node_modules in the packaged app
• Code signing: For macOS builds, imports Apple certificates using APPLE_ID, APPLE_PASSWORD, and APPLE_TEAM_ID environment variables, then removes the keychain entry post-build for security
• Artifact upload: Uploads .app, .dmg, .zip, and other distributables as GitHub Actions artifacts under the distributables name

npm Workspace Publishing (x-publish.yml)

The x-publish.yml workflow handles automated publishing to the npm registry. It triggers exclusively on Release creation events (published).

This workflow:

• Updates npm to the latest version
• Installs the workspace using pnpm install
• Runs a clean build across all packages
• Executes npm pack and npm publish --access public for each workspace (@x/shared, @x/core, @x/preload, @x/renderer)

Build Pipeline Architecture and Dependencies

Rowboat's CI/CD pipeline respects a strict dependency graph defined in apps/x/pnpm-workspace.yaml. The build order enforced by the scripts mirrors this workspace structure:

shared → core → preload → renderer → main

• apps/x/packages/shared/: Shared TypeScript utilities and validators used by every package
• apps/x/packages/core/: Business logic, AI providers, and OAuth implementations
• apps/x/apps/preload/: Electron preload scripts
• apps/x/apps/renderer/: React UI built with Vite (vite.config.ts)
• apps/x/apps/main/: Electron main process bundled via bundle.mjs

Step-by-Step Integration Guide

Setting Up Local Pre-Commit Validation

Before pushing to CI, validate your changes locally using the same commands executed in rowboat-build.yml:

# Install the exact toolchain used by the CI

pnpm install

# Build shared and core packages (respects dependency graph)

pnpm --filter @x/shared... build
pnpm --filter @x/core... build

# Bundle the Electron main process (same as CI)

node apps/x/apps/main/bundle.mjs

# Run the renderer build (Vite)

pnpm --filter @x/renderer... build

Triggering Production Releases with Git Tags

To initiate a full production build including code signing and artifact generation:

# Tag a new version (e.g., v1.2.3)

git tag v1.2.3
git push origin v1.2.3

This triggers electron-build.yml to:

1. Extract the version from the tag
2. Patch all package.json files in the workspace
3. Build and sign the Electron app for macOS, Linux, and Windows
4. Upload distributables as artifacts

To publish to npm, create a GitHub Release from the tag, which triggers x-publish.yml.

Extending Workflows for Custom Deployments

Add custom deployment steps after the artifact upload in electron-build.yml. For example, to push builds to an S3 bucket:

# In .github/workflows/electron-build.yml, after artifact upload

- name: Upload to S3
  uses: jakejarvis/s3-sync-action@master
  with:
    args: --acl public-read
  env:
    AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    SOURCE_DIR: ./dist

Key Configuration Files and Scripts

File	Role
.github/workflows/rowboat-build.yml	Core library build and test automation
.github/workflows/electron-build.yml	Electron app compilation, signing, and artifact generation
.github/workflows/x-publish.yml	npm workspace publishing on release
apps/x/pnpm-workspace.yaml	Workspace dependency graph definition
apps/x/apps/main/bundle.mjs	esbuild bundler for Electron main process
apps/x/packages/shared/	Shared TypeScript utilities
apps/x/packages/core/	Business logic and AI providers
apps/x/apps/renderer/vite.config.ts	Vite configuration for React UI

Summary

• Rowboat uses three GitHub Actions workflows (rowboat-build.yml, electron-build.yml, x-publish.yml) to automate testing, building, signing, and publishing.
• The build respects a strict dependency order: shared → core → preload → renderer → main, enforced by pnpm workspaces.
• Version stamping occurs automatically when pushing Git tags matching v*, patching all workspace package.json files before building.
• macOS code signing is supported via repository secrets (APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID) in the Electron workflow.
• npm publishing triggers on GitHub Release creation, not tag pushes, ensuring artifacts are built before publication.

Frequently Asked Questions

Can I use GitLab CI or other providers instead of GitHub Actions?

Yes. The same build scripts used in the GitHub Actions workflows can run in any CI system. Replicate the steps from .github/workflows/rowboat-build.yml: checkout code, install pnpm and Node.js 20, run pnpm install --frozen-lockfile, then execute npm run build and node apps/x/apps/main/bundle.mjs. The pnpm workspace commands are portable across CI providers.

How do I enable macOS code signing for the Electron app?

Configure three repository secrets in your GitHub repository settings: APPLE_ID (your Apple ID email), APPLE_PASSWORD (an app-specific password), and APPLE_TEAM_ID (your Apple Developer Team ID). The electron-build.yml workflow automatically detects these secrets and executes the signing step, importing the certificate into a temporary keychain and removing it after the build completes.

What triggers the npm publish workflow?

The x-publish.yml workflow triggers exclusively on the published event of a GitHub Release, not on Git tag pushes. To publish to npm, first push a Git tag (which triggers the Electron build), then create a GitHub Release from that tag via the GitHub UI or API. This ensures that built artifacts are ready before the npm packages are published to the registry.

How do I add custom test suites to the pipeline?

Insert a test execution step after the pnpm install phase in .github/workflows/rowboat-build.yml or .github/workflows/x-publish.yml. The repository already contains a commented placeholder (# - run: npm test) in x-publish.yml that you can uncomment. Alternatively, add pnpm test or npm test as a discrete step in the Electron build workflow to validate the application before packaging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}