Skip to content

Ruby SDK Deployment Cookbook

Opinionated guidance for packaging, deploying, and validating Sinatra-based extensions.

Scaffold & testing

kiket extensions scaffold my-ruby-extension --sdk ruby
# install dependencies with your preferred Ruby package manager

The scaffold includes replay fixtures, GitHub Actions, and .kiket/manifest.yaml. Use the CLI helpers:

kiket extensions lint
kiket extensions test
kiket extensions replay --template issue_created --url http://localhost:8080/webhooks/issue.created

Hosting patterns

  • Heroku / Render / Fly.io – set PORT and call sdk.run!(host: '0.0.0.0', port: ENV.fetch('PORT', 8080)).
  • Cloud Run – start the app with ruby main.rb (or your preferred process manager) and configure min instances for latency-sensitive guards.
  • AWS Lambda / API Gateway – wrap sdk with Rack::Handler::Lambda.

Always expose /health for readiness checks and keep idle timeouts ≥10 seconds, otherwise workflow.before_transition will fail.

Secrets & configuration

  • Declare secrets in the manifest (settings[].secret: true) and sync them via kiket marketplace secrets sync.
  • During deploys, set KIKET_SECRET_<KEY> environment variables; the SDK hydrates context[:settings].
  • Use context[:secrets].rotate when you need JIT credentials for downstream APIs.

Telemetry & logging

  • Keep telemetry enabled so admins can see performance in the marketplace dashboard.
  • Provide a feedback_hook (e.g., ship JSON to STDOUT) to capture traces locally.
  • Wrap handlers in begin/rescue only for expected errors; re-raising ensures telemetry records the failure.

Custom data workflow

  1. Define schemas under .kiket/modules/<namespace>/schema.yml.
  2. Add custom_data.permissions to the manifest.
  3. Use context[:endpoints].custom_data(project_id) as a repository.
  4. Guard access with role checks inside handlers if the module contains sensitive data.

Deployment checklist

  • kiket extensions lint and kiket extensions test pass.
  • Replay templates cover your critical workflows.
  • Health endpoint returns {"status":"ok"}.
  • KIKET_WEBHOOK_SECRET, KIKET_WORKSPACE_TOKEN, and required KIKET_SECRET_* vars are set.
  • Telemetry shows up under Admin → Marketplace → SDK Telemetry after a dry run.

References