Verify every Rails deploy in production
DeployAngel compares each Rails release with your last healthy one, using real production traffic: error rate, p95 latency, exceptions, and jobs, app-wide and per route and job class. Then it clears the release or fails it, with the evidence, and tells you, your CI, or your coding agent when it's safe to stop watching. Setup is one gem and one environment variable, with no code changes.
Requires Ruby 3.1 or later and Rails 7.1 or later. The gem has no runtime dependencies. For Hanami and Sinatra, see Hanami and Sinatra.
1. Install the agent
Create an account and an app, then create its app token from the setup checklist. Then add the agent:
Add the gem and run bundle install:
# Gemfile gem "deployangel"
There's nothing else to add. A Railtie starts the agent in every process that boots Rails, web servers and job workers alike.
2. Set the token
Set the app token as DEPLOYANGEL_TOKEN in production, on every process: web servers and job workers alike. On Heroku, the DeployAngel add-on sets it for you.
The agent finds the release it's running by itself on Heroku (with dyno metadata enabled), Kamal, Render, Fly.io, Railway, Coolify, Dokku, Capistrano, ECS, and servers deployed from a git checkout. In other Docker deploys, bake the commit into the image: bundle exec deployangel install docker adds ARG GIT_SHA and ENV DEPLOYANGEL_REVISION=$GIT_SHA to your Dockerfile, and you build with --build-arg GIT_SHA=$(git rev-parse HEAD). Set it up for how you deploy has the steps for each host.
3. Check the setup
Once it's deployed, run:
bundle exec deployangel doctor
It checks your checkout and what DeployAngel has seen so far: which processes report and the release each runs, the routes, jobs, and scheduled jobs the agent found, and any setup problem, such as a worker that isn't running the agent, with what to do about it.
The first day is a warm-up. For an app's first 24 hours of telemetry, DeployAngel learns what's normal for it. Deploys during that time are still checked, and you'll hear right away if one fails, but they can't be cleared. Installing the agent a day before a deploy you care about means that deploy can be cleared.
What the Rails agent records
- Every request, by the route it matched (
GET /orders/:id), never the raw path: counts, status codes, and latency. - Exceptions: a fingerprint, the class, application frames (or the first library frames when none is the app's), and the first line of the message with numbers, IDs, emails, UUIDs, and quoted values replaced.
- Jobs from every ActiveJob adapter (Solid Queue, Sidekiq, GoodJob, and the rest) and native Sidekiq jobs: failures, duration, and queue latency.
- Schedules from Solid Queue's
config/recurring.yml, GoodJob's cron, sidekiq-cron, sidekiq-scheduler, and whenever, so DeployAngel expects each recurring job and notices when one stops running. Cron and Heroku Scheduler jobs can be declared. - Health checks aren't counted, because they make an app look busier and healthier than its real pages: Rails' own
/up, OkComputer, health_check, rails-healthcheck, and a lambda or Rack app at a conventional path such as/healthz. - Never sent: request bodies, parameters, headers, cookies, SQL, logs, or source code. Recording a request adds about 2 µs, one payload a minute goes out from a background thread, and memory stays under about 4 MB.
The privacy policy lists exactly what's collected. If DeployAngel is ever unreachable, your app keeps running normally, and the agent sends up to an hour of telemetry once it's back.
4. Wait for the verdict in CI or a coding agent
Each release is compared with your last healthy one for at least 15 minutes. A busy app usually clears in about that time; a quiet one can take longer, or run a smoke test after each deploy. With a "CI deploys" or "CLI & coding agents" token in DEPLOYANGEL_API_TOKEN, the CLI waits for the verdict and exits with a code a pipeline can act on:
bundle exec deployangel verify --wait --until=initial
- 0 cleared, 1 failed, 2 not cleared
- 6 no problems in the first 15 minutes, but not cleared yet
- 3 still verifying when the wait timed out
To give Claude Code, Cursor, and Codex the same verdicts through DeployAngel's read-only MCP server, run this in the project:
bundle exec deployangel install agents
The CLI reference lists every command and exit code, and set up your coding agent covers the MCP server.
Rails troubleshooting
Start with bundle exec deployangel doctor: it names most setup problems and what to do about each.
The app page says "Agent hasn't reported yet"
Check that DEPLOYANGEL_TOKEN is set on every process, including Sidekiq and Solid Queue workers, and that the app can reach https://api.deployangel.com. The agent reports from every Rails environment but development and test; DEPLOYANGEL_ENABLED=true forces it on.
"The agent doesn't say which release it's running"
The agent couldn't find a commit. On Heroku, run heroku labs:enable runtime-dyno-metadata and heroku labs:enable runtime-dyno-build-metadata, then deploy. In Docker, .dockerignore usually leaves out .git, so bake the commit in with bundle exec deployangel install docker. Anywhere else, set DEPLOYANGEL_REVISION to the deployed commit. If only some processes are affected, it's usually a job worker missing the setting.
My health check is my own controller
List its route the way the dashboard shows it, and HEAD requests to it are left out too:
# config/initializers/deployangel.rb DeployAngel.configure do |config| config.ignored_routes = [ "GET /healthz" ] end
A sidekiq-cron job isn't expected
The agent reads sidekiq-cron's schedule file, config/schedule.yml unless sidekiq-cron is configured otherwise. If your app loads jobs from another file, point the agent at it. Jobs that exist only in Redis, such as ones created in code or in the Sidekiq web UI, aren't read.
DeployAngel.configure do |config| config.sidekiq_cron_schedule_file = "config/sidekiq_schedule.yml.erb" end
Does staging report?
Yes. RAILS_ENV=staging reports with nothing extra. Add staging as an environment of the same app in the dashboard, and give it that environment's token. It gets its own verdicts, and its notifications are quiet by default.
A release failed on 500s from requests no route matched
Scanners send multipart bodies Rack can't parse, and Rack::MethodOverride reads them above Rails' exception handling, so they become 500s on POST unmatched and can fail a release that didn't cause them. A small middleware answers them with a 400: see requests that become 500s.
"Not cleared: this release never reported"
No process reported the registered release within 15 minutes. If another release kept running, the rollout failed or was rolled back. Otherwise the new version may never have started (check the boot logs, for example for a failed migration), or CI registered a different commit from the one the app runs. Register the commit that was built and deployed, after the deploy finishes.
More
- The full docs: each host, registering deploys from CI, staging, webhooks, PagerDuty, Honeybadger, and AppSignal, GitHub, and configuration
- The agent is open source: source and README on GitHub, and RubyGems
- Setup guides for other frameworks: Django, FastAPI, Flask, ASP.NET Core
Still stuck? Contact us.