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

​
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: All images also have a :latest tag.

​
Pulling Images

​
NPM Package Versioning

​
Current State

This is a monorepo with workspace packages:
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.
Since packages aren’t published to npm, sync versions with Docker releases:

​
Option 3: Changesets (For Published Packages)

When to use: If you plan to publish packages 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:

​
Commit Message Convention

Use Conventional Commits: