If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/railsadminteam/rails_admin shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 8mo ago
• 16 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 8mo ago
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live railsadminteam/rails_admin repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/railsadminteam/rails_admin.

What it runs against: a local clone of railsadminteam/rails_admin — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in railsadminteam/rails_admin | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 268 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of railsadminteam/rails_admin. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/railsadminteam/rails_admin.git
#   cd rails_admin
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of railsadminteam/rails_admin and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "railsadminteam/rails_admin(\\.git)?\\b" \\
  && ok "origin remote is railsadminteam/rails_admin" \\
  || miss "origin remote is not railsadminteam/rails_admin (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/generators/rails_admin/install_generator.rb" \\
  && ok "lib/generators/rails_admin/install_generator.rb" \\
  || miss "missing critical file: lib/generators/rails_admin/install_generator.rb"
test -f "app/controllers/rails_admin/main_controller.rb" \\
  && ok "app/controllers/rails_admin/main_controller.rb" \\
  || miss "missing critical file: app/controllers/rails_admin/main_controller.rb"
test -f "app/helpers/rails_admin/form_builder.rb" \\
  && ok "app/helpers/rails_admin/form_builder.rb" \\
  || miss "missing critical file: app/helpers/rails_admin/form_builder.rb"
test -f "config/routes.rb" \\
  && ok "config/routes.rb" \\
  || miss "missing critical file: config/routes.rb"
test -f "app/views/rails_admin/main/index.html.erb" \\
  && ok "app/views/rails_admin/main/index.html.erb" \\
  || miss "missing critical file: app/views/rails_admin/main/index.html.erb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 268 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~238d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/railsadminteam/rails_admin"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

RailsAdmin is a Rails engine (v3.3.0) that auto-generates a complete CRUD admin interface for your database models without writing controllers or views. It provides search, filtering, export (CSV/JSON/XML), custom actions, and form validation out-of-the-box by introspecting ActiveRecord/Mongoid models and rendering them through a Bootstrap 5 UI. Rails engine structure: app/ contains controllers (rails_admin/main_controller.rb, application_controller.rb), views (layouts, partials for Kaminari pagination), helpers (form_builder.rb for custom form rendering), and assets (app/assets/javascripts/ and app/assets/stylesheets/ with SCSS custom theme system). Configuration lives in initializers. Spec suite in spec/dummy_app/ provides a runnable Rails app for testing.

Rails developers building internal admin panels or data management tools who want to expose CRUD operations for multiple models without manually building admin controllers, views, or authorization logic. Also used by teams integrating with Devise for auth and CanCanCan/Pundit for authorization.

Production-ready and actively maintained. The project has a stable v3.x release series, comprehensive test coverage (indicated by Coveralls badge integration), CI/CD via GitHub Actions (test.yml, code-ql.yml), RuboCop linting enforced, and recent Webpack/Webpacker support added in v3.x. Changelog is actively updated.

Moderate dependency surface: core deps include Bootstrap 5, jQuery 3.6, Flatpickr, Turbo Rails, FontAwesome, and @popperjs. jQuery dependency is somewhat dated for new projects but backward-compatible. Single-maintainer risk is present (Mitsuhiro Shibuya listed as primary author). Breaking changes occurred between v2.x and v3.x (Webpack introduction). Security depends on integrations (Devise, CanCanCan) being kept updated.

Currently maintaining v3.x with focus on modern Rails compatibility (Webpacker/Webpack support, Turbo Rails integration). Recent work includes TypeScript support (142 lines present), Prettier code formatting standardization, and RuboCop compliance. The project tracks issues via GitHub Issues and uses Appraisals for multi-Rails-version testing.

Clone and set up: git clone https://github.com/railsadminteam/rails_admin.git && cd rails_admin && bundle install && yarn install. Run specs: bundle exec rspec. Start the dummy app: cd spec/dummy_app && bundle exec rails s (will be available at http://localhost:3000/admin by default).

Daily commands: Development: bundle exec rails s (runs spec/dummy_app by default via Procfile.teatro). Tests: bundle exec rspec or bundle exec rake spec. Linting: bundle exec rubocop (auto-fix: bundle exec rubocop -a). Code formatting: yarn format (runs Prettier).

• lib/generators/rails_admin/install_generator.rb — Entry point for installing RailsAdmin into a Rails app; all users must understand the initialization flow
• app/controllers/rails_admin/main_controller.rb — Core request dispatcher for all admin CRUD operations; handles routing to edit, show, delete, export actions
• app/helpers/rails_admin/form_builder.rb — Renders dynamic form fields (text, datetime, associations, file uploads); critical for data entry UI
• config/routes.rb — Defines all RailsAdmin admin paths and action mappings; essential for understanding URL structure
• app/views/rails_admin/main/index.html.erb — List view template with filtering, sorting, and pagination; most-visited page in the admin UI
• app/assets/javascripts/rails_admin/application.js.erb — Frontend asset manifest and initialization; wires together Bootstrap, Turbo, and custom UI behaviors
• config/locales/rails_admin.en.yml — All user-facing strings (labels, buttons, errors); required for supporting internationalization

Add a new admin page (custom action)

1. Create a new action method in app/controllers/rails_admin/main_controller.rb (e.g., def my_action) (app/controllers/rails_admin/main_controller.rb)
2. Create the view template at app/views/rails_admin/main/my_action.html.erb (app/views/rails_admin/main/my_action.html.erb)
3. Register the route in config/routes.rb under scope :root_path do (e.g., get :my_action, on: :collection) (config/routes.rb)
4. Add navigation link in app/views/layouts/rails_admin/_navigation.html.erb or sidebar (app/views/layouts/rails_admin/_navigation.html.erb)
5. Add i18n strings for labels/titles in config/locales/rails_admin.en.yml (config/locales/rails_admin.en.yml)

Add a new form field type (custom input widget)

1. Create a form field partial at app/views/rails_admin/main/_form_my_type.html.erb with input markup (app/views/rails_admin/main/_form_my_type.html.erb)
2. Update app/helpers/rails_admin/form_builder.rb to add a method that renders your partial (e.g., def my_type_field) (app/helpers/rails_admin/form_builder.rb)
3. Add JavaScript initialization in app/assets/javascripts/rails_admin/custom/ui.js to bind event handlers (app/assets/javascripts/rails_admin/custom/ui.js)
4. Update the field type detection logic (typically in the model DSL or type resolver) to map your custom type (app/helpers/rails_admin/form_builder.rb)
5. Add CSS styling in app/assets/stylesheets/rails_admin/custom/theming.scss if needed (app/assets/stylesheets/rails_admin/custom/theming.scss)

Customize the admin layout and branding

1. Create a layout override or child layout extending app/views/layouts/rails_admin/application.html.erb (app/views/layouts/rails_admin/application.html.erb)
2. Modify brand/logo in app/views/layouts/rails_admin/_head.html.erb or _navigation.html.erb (app/views/layouts/rails_admin/_navigation.html.erb)
3. Update colors and variables in app/assets/stylesheets/rails_admin/custom/variables.scss (app/assets/stylesheets/rails_admin/custom/variables.scss)
4. Override theme styles in app/assets/stylesheets/rails_admin/custom/theming.scss (app/assets/stylesheets/rails_admin/custom/theming.scss)

Add a custom filter or search option to the list view

1. Extend or override the filtering logic in app/controllers/rails_admin/main_controller.rb (e.g., in the index action) (app/controllers/rails_admin/main_controller.rb)
2. Create a filter partial at app/views/rails_admin/main/_filter_my_field.html.erb if a custom UI is needed (app/views/rails_admin/main/index.html.erb)
3. Register the filter in the model DSL or field configuration (likely in an initializer or model patches) (config/initializers/active_record_extensions.rb)
4. Add i18n strings for the filter label in config/locales/rails_admin.en.yml (config/locales/rails_admin.en.yml)

• Rails Engine — Allows RailsAdmin to mount as a plug-and-play admin interface into any Rails app without modifying the host application structure
• ERB Templates — Native Rails view layer; simplifies access to helpers and AR/Mongoid model methods for dynamic CRUD UI
• Bootstrap 5 — Battle-tested, responsive CSS framework; reduces custom styling burden and ensures consistent mobile/desktop UI
• Kaminari — Lightweight, Rails-native pagination gem with custom view over

1. Devise/CanCanCan/Pundit are optional but strongly recommended—without them, the entire admin interface is unauthenticated by default. 2) Asset pipeline must be configured correctly; missing require rails_admin/application in app/assets/javascripts/application.js will break admin UI. 3) Model configuration must happen inside rails_admin { } blocks on model classes, not in initializers, to ensure proper introspection. 4) The dummy app at spec/dummy_app/ uses SQLite and migrations—running migrations is required before tests pass. 5) Bootstrap 5 is hardcoded; upgrading or replacing requires changes across multiple view partials.

• Rails Engine — RailsAdmin is implemented as a Rails engine (mountable gem), meaning it auto-registers routes, loads assets, and runs migrations in host apps without explicit configuration—understanding engine lifecycle is critical for debugging initialization
• ActiveRecord Reflection / Model Introspection — RailsAdmin auto-detects columns, associations, and validations via ActiveRecord's reflection API (columns_hash, associations, validators), enabling zero-code UI generation—changes to model structure instantly reflect in admin UI
• Form Builder Pattern — The custom FormBuilder (app/helpers/rails_admin/form_builder.rb) extends Rails' ActionView::Helpers::FormBuilder to render context-aware inputs (select for foreign keys, date input for timestamps), avoiding repetitive partial logic
• SCSS Variable & Mixin Theming — RailsAdmin uses SCSS variables (app/assets/stylesheets/rails_admin/custom/variables.scss) to expose Bootstrap theme customization without modifying framework code—understanding variable shadowing is key to skinning the UI
• Turbo Rails Frame Navigation — RailsAdmin uses Turbo Rails (v7.1) for fast page transitions and partial updates—CRUD actions may use turbo_frame_tag to replace sections without full page reloads, affecting how navigation and authorization checks work
• Devise Integration Pattern — RailsAdmin delegates authentication to Devise (optional but standard); the initializer config must call current_user and authorize via user.admin? or similar—without this, the admin is fully public
• Kaminari Pagination with Custom Renderer — RailsAdmin provides custom Kaminari paginator templates (app/views/kaminari/ra-twitter-bootstrap/) that render Bootstrap-styled pagination—understanding Kaminari's custom renderer override is needed for modifying pagination behavior

• activeadmin/activeadmin — Direct competitor in the Rails admin UI space; uses DSL-based configuration (similar pattern) but with heavier customization and built-in authorization
• thoughtbot/administrate — Alternative Rails admin generator focused on simplicity and customization; generates explicit controller/view code instead of runtime introspection like RailsAdmin
• plataformatec/devise — Authentication engine that RailsAdmin integrates with; provides user sign-in and session management for securing admin routes
• CanCanCommunity/cancancan — Authorization library for role-based access control; RailsAdmin can delegate model/action visibility to CanCanCan ability definitions
• airblade/paper_trail — Audit trail gem that RailsAdmin can integrate with to display action history and enable record recovery in the admin UI

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive JavaScript unit tests for rails_admin/application.js.erb and custom/ui.js

The repo has extensive JavaScript assets (app/assets/javascripts/rails_admin/) but no visible Jest/Mocha test configuration. Given the complexity of form handling, UI interactions, and the presence of jQuery and Bootstrap dependencies, these files need unit test coverage. This would improve maintainability and prevent regressions in UI behavior.

• [ ] Set up Jest or Mocha test runner in package.json devDependencies
• [ ] Create spec/javascripts/ directory with test files for app/assets/javascripts/rails_admin/application.js.erb
• [ ] Create spec/javascripts/ directory with test files for app/assets/javascripts/rails_admin/custom/ui.js covering jQuery interactions, form submission, and Bootstrap integration
• [ ] Add npm test script to run JavaScript tests
• [ ] Integrate JavaScript tests into .github/workflows/test.yml CI pipeline
• [ ] Document testing approach in CONTRIBUTING.md

Add missing form field type partials and tests for app/views/rails_admin/main/

The views directory shows several form field partials (form*.html.erb) but the list appears truncated. Verify if all supported field types have corresponding partials, and add unit/integration tests for each form field type. This ensures consistency across the admin interface and prevents regressions when Rails versions update.

• [ ] Audit lib/rails_admin/config/fields/ to identify all supported field types
• [ ] Cross-reference with existing partials in app/views/rails_admin/main/ to identify missing views
• [ ] Create missing form*.html.erb partials for any unrepresented field types
• [ ] Add view spec tests in spec/rails_admin/views/ for each form field partial, testing rendering with valid/invalid data
• [ ] Add integration tests in spec/features/ covering form submissions with each field type

Create GitHub Actions workflow for testing CSS/SCSS asset compilation and visual regression detection

The repo has extensive stylesheets (app/assets/stylesheets/rails_admin/) with custom theming, mixins, and variables, but the test.yml workflow doesn't explicitly validate CSS compilation or check for breaking style changes. Adding SCSS linting and basic visual regression testing would catch styling issues early.

• [ ] Add sass-lint or stylelint to devDependencies in Gemfile/package.json
• [ ] Create .stylelintrc.json configuration file for SCSS linting rules
• [ ] Add new GitHub Actions workflow .github/workflows/assets.yml to run: SCSS linting on app/assets/stylesheets/
• [ ] Add CSS compilation test step to ensure all SCSS files in app/assets/stylesheets/rails_admin/ compile without errors
• [ ] Optionally integrate BackstopJS or Percy.io for visual regression testing of rendered admin interface
• [ ] Document asset testing requirements in CONTRIBUTING.md

• Documentation: Add examples to CONTRIBUTING.md for the most common customization use cases (custom field types, custom actions, form validation hooks) with code snippets, since the wiki is separate and new contributors often miss it
• Test Coverage: Add RSpec tests for app/helpers/rails_admin/form_builder.rb's rendering of edge cases (nil values, empty arrays, non-ASCII characters in labels) to ensure robustness across different locales
• Accessibility: Audit app/views/kaminari/ra-twitter-bootstrap/ paginator templates for ARIA labels and semantic HTML (e.g., nav landmark, button roles) to improve screen reader support

• High · Outdated jQuery dependency with known vulnerabilities — package.json - dependencies.jquery. The package.json specifies 'jquery': '^3.6.0', which allows installation of jQuery 3.6.x versions. jQuery 3.6.0-3.6.3 contain known XSS vulnerabilities (CVE-2020-11023, CVE-2020-11022) related to HTML sanitization in the $.htmlPrefilter() method. RailsAdmin's extensive use of form rendering and dynamic HTML manipulation increases exploitation risk. Fix: Update to jQuery 3.6.4 or later: 'jquery': '^3.6.4'. Additionally, audit all uses of $.html(), $.append(), and similar methods in app/assets/javascripts/ for potential XSS vectors.
• High · Unvalidated jQuery-UI version range — package.json - dependencies.jquery-ui. The jquery-ui dependency is pinned as '^1.12.1 <1.14.0', which includes jQuery UI 1.12.x and 1.13.x versions. Multiple versions in this range contain CVE-2021-41182 (XSS vulnerability via the tabs widget) and other XSS issues. RailsAdmin uses various UI widgets throughout its interface. Fix: Update to jQuery UI 1.14.0 or later: 'jquery-ui': '^1.14.0' to address known vulnerabilities. If 1.14.0 is not available, at minimum upgrade to the latest patched 1.13.x version and audit widget usage.
• High · Potential XSS in form rendering templates — app/views/rails_admin/main/ - all _form_*.html.erb files. The extensive use of ERB templates in app/views/rails_admin/main/form*.html.erb files suggests dynamic HTML rendering. Without visible sanitization or context-aware escaping, user-supplied field names, labels, and values could be rendered unsafely. Particular concern for fields handling rich text editors (CKEditor, Froala, SimpleMDE, WYSIhtml5). Fix: Audit all ERB templates to ensure user input is properly escaped. Use Rails' html_safe sparingly and only on pre-sanitized content. For rich text editors, implement strict CSP policies and validate/sanitize server-side before storage.
• Medium · Missing explicit Content Security Policy — app/views/layouts/rails_admin/ - head configuration. No CSP configuration visible in the file structure. RailsAdmin loads inline JavaScript (application.js.erb) and uses multiple third-party libraries (Bootstrap, FontAwesome, jQuery plugins). Without CSP, XSS vulnerabilities have higher impact. Fix: Implement a strict Content Security Policy header. Minimally: script-src 'self', style-src 'self' 'unsafe-inline' (for Bootstrap), img-src 'self' data:. Prefer moving inline styles to external stylesheets and using nonces for dynamic scripts.
• Medium · Potential SQL injection in custom filtering/export — app/views/rails_admin/main/export.html.erb, index.html.erb; app/helpers/rails_admin/form_builder.rb. The export.html.erb and index.html.erb views suggest filtering and data export capabilities. If query parameters are directly used in SQL without parameterization or if the form_builder constructs queries dynamically, SQL injection is possible. Fix: Ensure all database queries use parameterized queries or Rails' ActiveRecord query interface. Never concatenate user input into SQL strings. Audit main_controller.rb for any direct SQL construction.
• Medium · Outdated Bootstrap version with deprecated defaults — package.json - dependencies.bootstrap; app/assets/stylesheets/rails_admin/application.scss.erb. Bootstrap ^5.1.3 is specified. While 5.1.x is relatively recent, the caret (^) allows up to 5.x.x. Ensure SCSS is properly compiled and no unsafe inline styles are rendered. Bootstrap 5 changed several security defaults from version 4. Fix: Update to Bootstrap 5.3.x for latest security patches. Review application.scss.erb for any unsafe style overrides. Use CSS custom properties instead of inline styles for dynamic theming.
• Medium · Turbo (formerly Turbo — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.