# How to Integrate rowboatlabs/rowboat with CI/CD Pipelines

> Automate building, testing, signing, and publishing with rowboatlabs/rowboat CI/CD. Integrate easily using GitHub Actions for streamlined workflows.

- Repository: [RowBoat Labs/rowboat](https://github.com/rowboatlabs/rowboat)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/rowboat-build.yml):

```bash

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

```bash

# 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`](https://github.com/rowboatlabs/rowboat/blob/main/electron-build.yml) to:
1. Extract the version from the tag
2. Patch all [`package.json`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/x-publish.yml).

### Extending Workflows for Custom Deployments

Add custom deployment steps after the artifact upload in [`electron-build.yml`](https://github.com/rowboatlabs/rowboat/blob/main/electron-build.yml). For example, to push builds to an S3 bucket:

```yaml

# 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`](https://github.com/rowboatlabs/rowboat/blob/main/.github/workflows/rowboat-build.yml) | Core library build and test automation |
| [`.github/workflows/electron-build.yml`](https://github.com/rowboatlabs/rowboat/blob/main/.github/workflows/electron-build.yml) | Electron app compilation, signing, and artifact generation |
| [`.github/workflows/x-publish.yml`](https://github.com/rowboatlabs/rowboat/blob/main/.github/workflows/x-publish.yml) | npm workspace publishing on release |
| [`apps/x/pnpm-workspace.yaml`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/apps/renderer/vite.config.ts) | Vite configuration for React UI |

## Summary

- **Rowboat uses three GitHub Actions workflows** ([`rowboat-build.yml`](https://github.com/rowboatlabs/rowboat/blob/main/rowboat-build.yml), [`electron-build.yml`](https://github.com/rowboatlabs/rowboat/blob/main/electron-build.yml), [`x-publish.yml`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/.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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/.github/workflows/rowboat-build.yml) or [`.github/workflows/x-publish.yml`](https://github.com/rowboatlabs/rowboat/blob/main/.github/workflows/x-publish.yml). The repository already contains a commented placeholder (`# - run: npm test`) in [`x-publish.yml`](https://github.com/rowboatlabs/rowboat/blob/main/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.