Skip to main content
This document describes the release process for ShipSec Studio, including Docker image releases and npm package versioning.

​
Docker Image Releases

When you push a git tag matching the pattern v*.*.* (e.g., v1.0.0, v1.2.3), the GitHub Actions workflow automatically:
  1. Builds all three Docker images (backend, worker, frontend)
  2. Tags images with:
    • Version tag: ghcr.io/shipsecai/studio-{service}:{version}
    • Latest tag: ghcr.io/shipsecai/studio-{service}:latest
  3. Pushes images to GitHub Container Registry (GHCR)
  4. Creates a GitHub release with changelog

​
Creating a Release

# 1. Ensure you're on main branch and up to date
git checkout main
git pull origin main

# 2. Create and push a tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# The workflow will automatically build and release

​
Manual Release

You can also trigger a release manually via GitHub Actions UI:
  1. Go to Actions → Release workflow
  2. Click “Run workflow”
  3. Enter the version tag (e.g., v1.0.0)

​
Image Tags

Images are tagged as:
ServiceImage
Backendghcr.io/shipsecai/studio-backend:{version}
Workerghcr.io/shipsecai/studio-worker:{version}
Frontendghcr.io/shipsecai/studio-frontend:{version}
All images also have a :latest tag.

​
Pulling Images

# Pull a specific version
docker pull ghcr.io/shipsecai/studio-backend:1.0.0

# Pull latest
docker pull ghcr.io/shipsecai/studio-backend:latest

​
NPM Package Versioning

​
Current State

This is a monorepo with workspace packages:
PackageVersionPublished
@shipsec/sharedv0.1.0No
@shipsec/component-sdkv0.1.0No (private)
@shipsec/backend-clientv0.1.0No
@shipsec/studio-backendv0.1.0No
@shipsec/studio-workerv0.1.0No (private)
@shipsec/studio-frontendv1.0.0No
These packages are workspace dependencies and are not published to npm. They’re consumed internally within the monorepo.

​
Versioning Options

​
Option 1: Manual Versioning (Current)

When to use: Small teams, infrequent releases, packages not published to npm. 
# Update package.json versions manually before release
# Commit version changes
# Tag release
Since packages aren’t published to npm, sync versions with Docker releases: 
# Sync all package versions with release tag
bun run scripts/sync-versions.ts v1.0.0

​
Option 3: Changesets (For Published Packages)

When to use: If you plan to publish packages to npm. 
bun add -D @changesets/cli
bun changeset init
bun changeset          # Add changeset
bun changeset version  # Version packages
bun changeset publish  # Publish to npm

​
Release Checklist

Before creating a release:
  • Update CHANGELOG.md (if maintained)
  • Run tests: bun run test
  • Run typecheck: bun run typecheck
  • Run lint: bun run lint
  • Update package versions (if syncing): bun run scripts/sync-versions.ts v1.0.0
  • Commit version changes (if any)
Create the release:
  • Create and push tag: git tag -a v1.0.0 -m "Release v1.0.0" && git push origin v1.0.0
  • Verify GitHub Actions workflow completes
  • Verify images are available in GHCR
  • Verify GitHub release is created

​
Required GitHub Secrets

The release workflow uses GITHUB_TOKEN which is automatically provided by GitHub Actions. No additional secrets are required for GHCR.

​
Troubleshooting

​
Images not appearing in GHCR

  1. Check workflow logs for errors
  2. Verify GITHUB_TOKEN has packages:write permission
  3. Ensure repository has GitHub Packages enabled

​
Release not created

  1. Check workflow logs
  2. Verify tag format matches v*.*.*
  3. Check GitHub Actions permissions

​
Build failures

  1. Run tests locally: bun run test
  2. Run typecheck: bun run typecheck
  3. Check for uncommitted changes
  4. Verify all dependencies are installed

​
Semantic Versioning

Follow Semantic Versioning:
Change TypeVersion BumpExample
Breaking changesMajor1.0.0 → 2.0.0
New featuresMinor1.0.0 → 1.1.0
Bug fixesPatch1.0.0 → 1.0.1

​
Commit Message Convention

Use Conventional Commits: 
feat: add new workflow component
fix: resolve authentication issue
docs: update installation guide
chore: update dependencies