Build Scripts and Tools in the OpenShip Repository: Complete Technical Guide

TLDR: The oblien/openship monorepo utilizes a sophisticated toolchain centered around Bun-executed TypeScript releases (scripts/release.ts), Turborepo for parallel task execution, pnpm workspace management, and GitHub Actions CI/CD pipelines that handle everything from Docker image publishing to cross-platform desktop installer generation.

The oblien/openship project is a multi-package monorepo that relies on purpose-built build scripts and tools to automate compilation, packaging, and publishing across its distributed architecture. These utilities manage local development bootstrapping, semantic version bumping, and artifact generation for the API, web dashboard, email server, and edge routing services.

Release Orchestration Scripts

At the heart of OpenShip's build system sits a custom release automation framework written in TypeScript and executed via the Bun runtime.

scripts/release.ts: Central Release CLI

The scripts/release.ts file serves as the primary release orchestrator—a Bun-executed CLI that automates version bumping, Git tagging, GitHub Release creation, Docker image publishing, and in-app update advisories. According to the oblien/openship source code, this script verifies a clean working tree, ensures the current branch is main, computes the next semantic version (e.g., 0.4.9 → 0.4.10), updates every package.json in the monorepo, commits the changes, and watches the CI run for live status.

scripts/release-args.ts: Interactive Argument Builder

Supporting the main release script, scripts/release-args.ts supplies the interactive prompt used to build consistent argv lists for all release paths, standardizing inputs across patch, minor, and major version workflows.

Development Environment Bootstrap

OpenShip provides platform-specific wrapper scripts to standardize local development setup across operating systems.

Cross-Platform Install Scripts

The repository includes three bootstrap scripts in the scripts/ directory:

• scripts/install.sh – For Linux/macOS environments
• scripts/install.ps1 – For Windows PowerShell
• scripts/install-source.sh – For source-based installations

These scripts automate Bun installation, cache restoration, and dependency installation via pnpm install, ensuring reproducible development environments without manual configuration.

Package Management and Build Orchestration

Turborepo Task Runner

The monorepo leverages Turborepo (invoked via turbo in root package.json scripts) to execute parallel builds (turbo run build), development servers (turbo run dev), linting, testing, and cleaning tasks across all workspaces. This enables efficient task scheduling with proper dependency graphs between apps/* and packages/*.

pnpm Workspace Configuration

Dependency management is handled by pnpm, configured through pnpm-workspace.yaml at the repository root. This declares the workspace layout, linking local packages under apps/* and packages/* while maintaining strict version consistency across the monorepo.

Bun Runtime Environment

All build scripts and tools execute using Bun, a fast JavaScript runtime. The repository pins the exact Bun version in .bun-version, ensuring deterministic behavior across development machines and CI pipelines.

Desktop Build Tooling

Electron-Forge Configuration

For desktop application builds, OpenShip utilizes Electron-Forge as configured in apps/desktop/forge.config.js. The build process is triggered via:

bun run --cwd apps/desktop make

This command produces platform-specific installers including AppImage, .deb, .rpm, Windows zip files, and macOS DMG packages. The release.ts script integrates this step into the automated release pipeline, invoking the desktop build during CI execution as defined in .github/workflows/release.yml.

CI/CD and Container Automation

GitHub Actions Workflows

The .github/workflows/ directory contains comprehensive automation pipelines:

• release.yml – Orchestrates API binary builds, email server compilation, dashboard bundling, desktop installer generation, NPM publishing, and GitHub Release creation
• docker-images.yml – Handles GHCR image publishing for the API, dashboard, and edge components

The publish-npm job specifically strips workspace-style dependencies, runs smoke tests, and publishes the CLI to the NPM registry using OIDC trusted publishing.

Docker Compose Configurations

Container orchestration is managed through:

• docker/docker-compose.yml – For local development and testing
• docker/docker-compose.build.yml – For production image builds

The release.ts script can dispatch the docker-images.yml workflow directly via the docker sub-command without requiring version bumps or Git tag creation.

Utility Scripts

GeoIP Data Updates

The scripts/update-geoip.mjs script maintains the edge routing service's geographic data by pulling the latest MaxMind GeoIP dumps (or fallbacks) and writing JSON files used for geographic request routing decisions.

Practical Usage Examples

Running a Full Release

To execute a patch version bump with user announcements:

bun run release patch publish

This command sequence:

• Verifies a clean working tree and main branch status
• Computes next version (e.g., 0.4.9 → 0.4.10)
• Updates all package.json files and creates Git tags
• Writes update advisories for desktop client banners
• Triggers the GitHub Release workflow and monitors CI status

Publishing Docker Images Only

For targeted container updates without version bumps:

bun run release docker v0.4.10

This dispatches the docker-images.yml workflow directly to build and push GHCR images for the specified version, leaving the :latest tag unchanged and skipping Git tagging entirely.

Bootstrapping a Fresh Development Environment

On Linux or macOS:

./scripts/install.sh

This installs Bun (if missing), reads the pinned version from .bun-version, restores the Bun cache, and executes pnpm install to prepare the workspace.

Building Desktop Installers Locally

bun run --cwd apps/desktop make

Invokes Electron-Forge's make target to generate OS-specific installers for the current architecture.

Summary

• Release Automation: The scripts/release.ts Bun script orchestrates version bumps, Git tagging, and multi-platform publishing via interactive CLI prompts
• Development Bootstrap: Shell and PowerShell scripts in scripts/ standardize environment setup across Linux, macOS, and Windows
• Build Orchestration: Turborepo manages parallel task execution while pnpm handles workspace dependency linking via pnpm-workspace.yaml
• Desktop Builds: Electron-Forge configured in apps/desktop/forge.config.js generates cross-platform installers (AppImage, .deb, .rpm, DMG, Windows zip)
• CI/CD Integration: GitHub Actions workflows in .github/workflows/ automate artifact building, Docker publishing to GHCR, and NPM releases via OIDC trusted publishing
• Utility Scripts: scripts/update-geoip.mjs maintains edge routing data for geographic request handling

Frequently Asked Questions

How does OpenShip handle version bumping across the monorepo?

OpenShip uses scripts/release.ts, a Bun-executed TypeScript CLI that automatically calculates semantic versions, synchronizes all package.json files across workspaces, commits changes, creates Git tags, and triggers GitHub Releases. The script validates repository state—requiring a clean tree, main branch, and up-to-date remote—before executing any modifications.

Can I build and publish Docker images without creating a new release tag?

Yes. The release script supports a docker sub-command: bun run release docker v0.4.10. This dispatches the docker-images.yml workflow directly to build and push GHCR images for the API, dashboard, and edge components without modifying version numbers or creating Git tags, leaving the :latest tag untouched.

What runtime is required to execute OpenShip's build scripts?

All build scripts require Bun, with the specific version pinned in .bun-version at the repository root. The scripts/install.sh and scripts/install.ps1 files can automatically install Bun if not present, ensuring consistent runtime behavior across development and CI environments.

How are desktop applications compiled for different operating systems?

Desktop builds use Electron-Forge as configured in apps/desktop/forge.config.js. The command bun run --cwd apps/desktop make generates platform-specific installers—AppImage, .deb, .rpm, Windows zip, or macOS DMG—based on the host OS. This step is integrated into the CI pipeline via .github/workflows/release.yml for automated release builds.

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