Munawaba

On-call rotations inside your Rails application.

Munawaba helps your team share on-call duty. Build a rotation, see who's on call, and cover a teammate's shift when plans change. Connect Slack to announce handoffs and assignment changes.

• Requirements
• Installation
• Dashboard
• Background Jobs
• Scope
• Documentation
• Contributing
• License

• Ruby 3.4+
• Rails 8.1
• PostgreSQL 15+

See the compatibility matrix for tested combinations.

Add Munawaba to your host application's Gemfile:

gem "munawaba"

bundle install
bin/rails generate munawaba:install

The generator creates an initializer and copies the migrations. For an existing installation, follow upgrading.

Mount the dashboard:

# config/routes.rb
mount Munawaba::Engine => "/on-call"

Configure access using your application's authentication and authorization. This example uses authenticate_user! and current_user:

# config/initializers/munawaba.rb
Munawaba.configure do |config|
  config.authenticate = ->(controller) do
    controller.send(:authenticate_user!)
    controller.current_user.present?
  end
  config.authorize = ->(controller, _action, _record) { controller.current_user.admin? }
  config.actor = ->(controller) do
    user = controller.current_user
    { type: "User", id: user.id.to_s, name: user.name }
  end
  config.application_base_url = "https://example.com/on-call"
  config.notifications_enabled = false
end

Access is denied until both callbacks are configured to return true. The optional actor callback identifies who made each change in Activity. See access and configuration for the full reference.

bin/rails db:migrate

The migration enables btree_gist automatically for shift overlap checks. If it is missing and your database restricts extension creation, ask your database administrator to enable it first.

Follow Slack setup to enable notifications and send your first test message.

Open /on-call in your host application after installation. The dashboard provides:

• People and ordered rotations with one-week, two-week, or calendar-month schedules.
• Current coverage, upcoming handoffs, and agenda or month calendars.
• Previews before activation, rotation changes, and whole-shift overrides, including cross-schedule conflict warnings.
• Activity history and per-schedule Slack settings and delivery history.

See using the dashboard for roster changes, previews, and calendars.

Schedule these two jobs using your host's Active Job adapter and recurring scheduler. All jobs use job_queue_name.

With GoodJob, add these entries to your cron configuration:

# config/initializers/good_job.rb
Rails.application.configure do
  config.good_job.cron = {
    munawaba_maintenance: { cron: "* * * * *", class: "Munawaba::MaintenanceJob" },
    munawaba_projection: { cron: "0 0 * * *", class: "Munawaba::MaintainProjectionJob" }
  }
end

Start the worker with cron enabled:

bundle exec good_job start --enable-cron

See maintenance for troubleshooting and timezone-data updates.

Munawaba manages on-call schedules for one workspace. Overrides cover a whole shift, and conflicts between schedules appear as warnings for you to review.

Usage and reference covers scheduling, access, configuration, Slack delivery, and maintenance. See the changelog for releases.

See CONTRIBUTING.md for the local demo, development setup, and test commands. Report security issues as described in SECURITY.md.

MIT License.