Omaship
Documentation Menu ▼

How Omaship Works

Omaship uses Rails engines to provide functionality while letting you customize everything.

The Engine Model

Your app includes several Omaship engines—Ruby gems that provide features. Each engine adds:

  • Controllers and views
  • Background jobs
  • Database migrations
  • GitHub Actions workflows

Engines are installed in your Gemfile and receive updates when you run bundle update.

Managed vs User Files

This is the key concept. Omaship creates two types of files:

Managed Files

Updated automatically. Don't edit these directly.

  • _omaship-*.yml workflows
  • Engine gem code
  • Core migrations

User Files

Yours to customize. Never overwritten.

  • deploy-production.yml
  • ci.yml
  • Your app code
  • Template overrides

How Updates Work

  1. We release a new version of an engine
  2. Omaship opens a PR in your repo with the update
  3. You review the changes
  4. Merge when ready

Managed files are updated. Your customizations in user files stay intact.

No surprises. Updates come as PRs you can review, not automatic changes to your running app.

Overriding Engine Behavior

Rails looks for files in your app first, then falls back to engine files. To customize anything:

  1. Find the engine file you want to change
  2. Create the same file path in your app
  3. Your version takes precedence

See Overriding Templates for examples.

The Engines

Your app includes these engines:

  • omaship_base — CI/CD, deployment, infrastructure
  • omaship_preview — PR preview deployments
  • omaship_backup — Automated database backups
  • omaship_payments — Stripe integration
  • omaship_admin — Admin dashboard
  • omaship_landing — Landing page components
  • omaship_newsletter — Email campaigns

See Engine Reference for detailed documentation on each.