Notify Shipyrd with the Ruby gem

For Kamal-deployed Rails (or any Ruby) apps. Add the gem, drop in two hook files, ship.

What it does

The shipyrd gem wires into Kamal’s lifecycle hooks. Kamal calls the hook scripts you create in .kamal/hooks/, the gem reads the standard KAMAL_* environment variables (destination, version, performer, runtime), and POSTs to Shipyrd’s API. The canonical setup uses pre-deploy and post-deploy; the gem also accepts pre-connect and pre-build if you want to record those phases.

Setup

  1. Add the gem to your Gemfile.

    bundle add shipyrd

  2. Add SHIPYRD_API_KEY to your Kamal secrets so it’s available to hooks at deploy time.

    # config/deploy.yml
env:
  secret:
    - SHIPYRD_API_KEY

    Set the value in .kamal/secrets (or your secret manager of choice).

  3. Create the two hook files. Both must be executable.

    # .kamal/hooks/pre-deploy
#!/usr/bin/env ruby
require 'shipyrd'
Shipyrd::Client.new.trigger('pre-deploy')

    # .kamal/hooks/post-deploy
#!/usr/bin/env ruby
require 'shipyrd'
Shipyrd::Client.new.trigger('post-deploy')

    chmod +x .kamal/hooks/pre-deploy .kamal/hooks/post-deploy

  4. Deploy. The hooks fire automatically.

    kamal deploy

What gets recorded

The gem reads these from Kamal’s environment, so you don’t have to pass anything explicitly:

Override any of these with a SHIPYRD_-prefixed env var (e.g. SHIPYRD_PERFORMER).

Performer matching

The performer value decides which Shipyrd user “owns” a deploy — it matters for environment locking and Slack mentions. It must match one of:

  1. A GitHub profile URL — the gem sets this automatically if you have gh config set -h github.com user yourname configured locally.
  2. An email address — must match an email on a Shipyrd account in your team.

If neither matches, the deploy still records but isn’t attributed to a user.

Verify it worked

Run kamal deploy. You should see the hooks fire in Kamal’s output, then the deploy appears in your Shipyrd timeline within a second or two.