rails-local-ci

Backport of Rails 8.1's ActiveSupport::ContinuousIntegration for Rails 5.2–7.x

Rails 8.1 introduced a standardized bin/ci script and ActiveSupport::ContinuousIntegration class (PR #54693) that runs the same CI steps locally and in the cloud. This gem ships that class for apps on Rails 5.2–7.x so you don't have to wait for an upgrade.

When you do upgrade to Rails 8.1, remove the gem — bin/ci and config/ci.rb stay unchanged because Rails 8.1 provides the class at the same load path.

• Prerequisites
• Installation
• Usage
• DSL Reference
• Parallel Groups
• Fail-Fast Mode
• Commit Signoff
• CI Integration
• Running Tests
• Upgrading to Rails 8.1
• Compatibility
• How It Works
• License

• Ruby >= 2.4
• Rails >= 5.2 and < 8.1

Add to your Gemfile:

gem "rails-local-ci"

Install:

bundle install

Run the generator:

rails generate rails_local_ci:install

The generator copies two files into your app:

• bin/ci — the runner script (set to executable)
• config/ci.rb — your CI step definitions

Run all CI steps locally:

./bin/ci

Expected output:

Continuous Integration
Running tests, style checks, and security audits

Setup
bin/setup --skip-server

✅ Setup passed in 2.31s

Style: Ruby
bin/rubocop

✅ Style: Ruby passed in 1.04s

Tests: Rails
bin/rails test

✅ Tests: Rails passed in 4.17s

✅ Continuous Integration passed in 8.34s

Define your steps in config/ci.rb:

CI.run do
  step "Setup", "bin/setup --skip-server"
  step "Style: Ruby",                      "bin/rubocop"        if File.exist?("bin/rubocop")
  step "Security: Gem audit",              "bin/bundler-audit"  if File.exist?("bin/bundler-audit")
  step "Security: Brakeman code analysis", "bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error" if File.exist?("bin/brakeman")
  step "Tests: Rails",                     "bin/rails test"

  if success?
    heading "All CI checks passed!", "Your changes are ready for review"
  else
    failure "CI checks failed", "Fix the issues above before submitting your PR"
  end
end

CI.run sets ENV["CI"] = "true" for the duration of the run, which Rails uses to enable eager loading and disable verbose logging.

All methods are available inside the CI.run do ... end block in config/ci.rb.

Color types for echo and heading:

CI.run accepts optional title and subtitle overrides:

CI.run "My App CI", "Linting, security, and tests" do
  # ...
end

Run multiple independent steps concurrently using group:

CI.run do
  step "Setup", "bin/setup --skip-server"

  group "Checks", parallel: 3 do
    step "Style: Ruby",        "bin/rubocop"
    step "Security: Brakeman", "bin/brakeman --quiet"
    step "Security: Gems",     "bin/bundler-audit"
  end

  step "Tests: Rails", "bin/rails test"
end

parallel: N runs up to N steps in concurrent threads. Output is captured per-step (via PTY when available, Open3 otherwise) and displayed in declaration order after all steps complete — no interleaving. A live progress indicator shows which steps are running.

group without parallel: (or parallel: 1) runs steps sequentially, useful for visual grouping.

Nested groups: a group inside a parallel group runs its steps sequentially within that thread slot. Sub-groups cannot themselves be parallelized — attempting to set parallel: on a nested group raises ArgumentError.

Stop at the first failing step instead of running all steps:

./bin/ci --fail-fast
./bin/ci -f

After a successful local CI run, post a green commit status directly to your Git host to unblock PR merge — no cloud CI runner needed.

Requires the gh CLI and the gh-signoff extension:

gh extension install basecamp/gh-signoff

Add to config/ci.rb:

if success?
  step "Signoff: All systems go. Ready for merge and deploy.", "gh signoff"
end

Install bb-signoff:

curl -fsSL https://raw.githubusercontent.com/its-magdy/bb-signoff/main/bb-signoff \
  -o /usr/local/bin/bb-signoff && chmod +x /usr/local/bin/bb-signoff

Create a Bitbucket repository access token with these scopes:

• Repositories: Read, Write, Admin
• Pull Requests: Read, Write

Store the token in ~/.bb-signoff or export it as BB_API_TOKEN.

Add to config/ci.rb:

if success?
  step "Signoff: All systems go. Ready for merge and deploy.", "bb-signoff"
end

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - run: bin/ci

pipelines:
  default:
    - step:
        name: CI
        script:
          - bundle install
          - bin/ci

bundle exec ruby test/continuous_integration_test.rb

1. Remove gem "rails-local-ci" from your Gemfile
2. Run bundle install

bin/ci and config/ci.rb require no changes. Rails 8.1 ships ActiveSupport::ContinuousIntegration at the same load path this gem uses.

The gem places ActiveSupport::ContinuousIntegration at lib/active_support/continuous_integration.rb — the identical load path Rails 8.1 uses. The generated bin/ci does:

require_relative "../config/boot"
require "active_support/continuous_integration"  # resolved by this gem, or Rails 8.1 built-in

CI = ActiveSupport::ContinuousIntegration
require_relative "../config/ci.rb"

The generator copies only bin/ci and config/ci.rb into your app. The class itself lives in the gem.

MIT