Awesome Open Source
Awesome Open Source


Current Gem Version Build Status Maintainability Test Coverage

An extension to ActiveJob for running background jobs periodically, according to a schedule. Inspired by its predecessors, resque-scheduler and sidekiq-scheduler, ActiveJob::Scheduler hopes to bring the power of scheduled jobs into everyone's hands, by way of the pre-defined ActiveJob API which most popular queueing backend choices already support.

Like its predecessors, ActiveJob::Scheduler uses the same powerful syntax for describing when periodic jobs should run as Rufus::Scheduler. However, unlike its predecessors, ActiveJob::Scheduler does not require a separate process to be run. Instead, it uses an after_perform callback to re-enqueue the job after it has been performed.


Add this line to your application's Gemfile:

gem 'activejob-scheduler'

And then execute:

$ bundle

Or install it yourself as:

$ gem install activejob-scheduler


To schedule your jobs, add the repeat macro to the job definition:

class GenerateSitemapsJob < ApplicationJob
  repeat 'every day at 2am'

  def perform

This macro can also be used to configure the job event, like its name or arguments:

class GenerateSitemapsJob < ApplicationJob
  repeat every: '1d', name: 'Sitemap Generator', arguments: %w(foo bar)

  def perform(foo, bar)
    SitemapGenerator.generate(foo, bar) # => foo == "foo", bar == "bar"

The DSL also allows you to iterate over a collection and pass in a different argument for each item:

class SyncOrdersJob < ApplicationJob
  repeat 'every day at 11:30am', each: -> { Order.not_synced }

  def perform(order)

This will trigger the event every day at 11:30am, but enqueue a job for each model in the collection, and pass it into the job arguments. You can specify static arguments here as well, they will be passed in prior to the item argument at the end.

class SyncOrdersJob < ApplicationJob
  repeat 'every day at 11:30am',
    arguments: ['synced'],
    each: -> { Order.not_synced }

  def perform(type, order)
    ExternalSystem.create(type: type, order: order) # type is "synced"

Start the schedule by running this command:

./bin/rails activejob:schedule

YAML Schedule

Much like resque-scheduler, you can use a YAML schedule file with activejob-scheduler with a very similar syntax. To generate a new one, run:

$ rails generate activejob:schedule

Then, add your jobs into the YAML like so:

    every: '1d'

This is entirely optional, however, and both DSL-based jobs and YAML-based jobs will be included in the schedule at runtime.


class AdminMailer < ApplicationMailer
  repeat :daily_status, 'every day at 8am'
  def daily_status
    mail to: User.admins.pluck(:email)

This will send the email every day at 8:00am. You can also pass all the regular fields from repeat in the job DSL like arguments and the various fugit-parsed intervals.

You can also send a different email for each recipient:

class UserMailer < ApplicationMailer
  repeat :status, 'every day at 8am', each: -> { User.receive_email }
  def status(user)

This lambda will be called when the event is enqueued, and individual mails will be sent out for each user in the collection.


After checking out the repo, run bin/setup to install dependencies. Then, run rake rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bin/rake install. To release a new version, update the version number in version.rb, and then run bin/rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
ruby (12,901
rails (667
queue (182
ruby-on-rails (142
schedule (76
sidekiq (30
scheduled-jobs (20