Skip to content

ombulabs/claude-code_rails-upgrade-skill / rails-upgrade

rails-upgrade

Verified

Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.

FileKindSize
SKILL.mdskill md11.0 KB
detection-scripts/gem_limits.rbscript6.0 KB
detection-scripts/hop.rbscript2.2 KB
detection-scripts/patterns/rails-40-patterns.expectations.ymlconfig43.8 KB
detection-scripts/patterns/rails-40-patterns.ymlconfig96.5 KB
detection-scripts/patterns/rails-41-patterns.expectations.ymlconfig25.6 KB
detection-scripts/patterns/rails-41-patterns.ymlconfig59.8 KB
detection-scripts/patterns/rails-42-patterns.expectations.ymlconfig27.5 KB
detection-scripts/patterns/rails-42-patterns.ymlconfig48.7 KB
detection-scripts/patterns/rails-50-patterns.expectations.ymlconfig1.9 KB
detection-scripts/patterns/rails-50-patterns.ymlconfig8.1 KB
detection-scripts/patterns/rails-51-patterns.expectations.ymlconfig4.2 KB
detection-scripts/patterns/rails-51-patterns.ymlconfig15.0 KB
detection-scripts/patterns/rails-52-patterns.expectations.ymlconfig5.0 KB
detection-scripts/patterns/rails-52-patterns.ymlconfig14.7 KB
detection-scripts/patterns/rails-60-patterns.expectations.ymlconfig1007 B
detection-scripts/patterns/rails-60-patterns.ymlconfig14.2 KB
detection-scripts/patterns/rails-70-patterns.expectations.ymlconfig4.0 KB
detection-scripts/patterns/rails-70-patterns.ymlconfig11.2 KB
detection-scripts/patterns/rails-71-patterns.expectations.ymlconfig3.1 KB
detection-scripts/patterns/rails-71-patterns.ymlconfig9.5 KB
detection-scripts/patterns/rails-72-patterns.expectations.ymlconfig1.2 KB
detection-scripts/patterns/rails-72-patterns.ymlconfig6.1 KB
detection-scripts/patterns/rails-80-patterns.expectations.ymlconfig6.6 KB
detection-scripts/patterns/rails-80-patterns.ymlconfig21.2 KB
detection-scripts/patterns/rails-81-patterns.expectations.ymlconfig4.3 KB
detection-scripts/patterns/rails-81-patterns.ymlconfig13.2 KB
detection-scripts/scan_patterns.rbscript42.8 KB
examples/multi-hop-upgrade.mdmarkdown18.9 KB
examples/simple-upgrade.mdmarkdown4.0 KB
references/breaking-changes-by-version-reference.mdmarkdown3.9 KB
references/deprecation-warnings-reference.mdmarkdown10.7 KB
references/gem-compatibility-reference.mdmarkdown8.2 KB
references/js-compressor-sprockets-mismatch-reference.mdmarkdown4.7 KB
references/multi-hop-strategy-reference.mdmarkdown8.8 KB
references/next-hop-readiness-reference.mdmarkdown2.1 KB
references/no-test-suite-smoke-reference.mdmarkdown4.7 KB
references/request-patterns-reference.mdmarkdown3.7 KB
references/sequential-strategy-reference.mdmarkdown2.1 KB
references/staying-current-reference.mdmarkdown7.8 KB
references/testing-checklist-reference.mdmarkdown6.3 KB
templates/app-update-preview-template.mdmarkdown4.3 KB
templates/upgrade-report-template.mdmarkdown10.2 KB
version-guides/upgrade-3.2-to-4.0.mdmarkdown68.0 KB
version-guides/upgrade-4.0-to-4.1.mdmarkdown66.7 KB
version-guides/upgrade-4.1-to-4.2.mdmarkdown60.7 KB
version-guides/upgrade-4.2-to-5.0.mdmarkdown9.7 KB
version-guides/upgrade-5.0-to-5.1.mdmarkdown19.1 KB
version-guides/upgrade-5.1-to-5.2.mdmarkdown17.7 KB
version-guides/upgrade-5.2-to-6.0.mdmarkdown6.4 KB
version-guides/upgrade-6.0-to-6.1.mdmarkdown6.8 KB
version-guides/upgrade-6.1-to-7.0.mdmarkdown14.7 KB
version-guides/upgrade-7.0-to-7.1.mdmarkdown13.2 KB
version-guides/upgrade-7.1-to-7.2.mdmarkdown11.2 KB
version-guides/upgrade-7.2-to-8.0.mdmarkdown23.1 KB
version-guides/upgrade-8.0-to-8.1.mdmarkdown14.0 KB
workflows/00-verify-latest-patch-workflow.mdmarkdown1.7 KB
workflows/01-run-test-suite-workflow.mdmarkdown12.7 KB
workflows/02-resolve-deprecation-warnings-workflow.mdmarkdown6.3 KB
workflows/03-validate-upgrade-path-workflow.mdmarkdown1.8 KB
workflows/04-setup-next-rails-workflow.mdmarkdown1.5 KB
workflows/05-detect-breaking-changes-workflow.mdmarkdown20.0 KB
workflows/06-check-gem-compatibility-workflow.mdmarkdown11.1 KB
workflows/07-boot-smoke-test-workflow.mdmarkdown7.3 KB
workflows/08-generate-upgrade-report-workflow.mdmarkdown12.7 KB
workflows/09-generate-app-update-preview-workflow.mdmarkdown7.3 KB
workflows/10-implement-and-upgrade-workflow.mdmarkdown2.5 KB
workflows/11-sync-ci-workflow.mdmarkdown8.6 KB
workflows/12-align-load-defaults-workflow.mdmarkdown952 B
workflows/13-mention-cleanup-workflow.mdmarkdown1.3 KB

workflows/11-sync-ci-workflow.md

View on GitHub
# Workflow 11: Sync CI Config

**Purpose:** Verify every CI configuration file in the repo matches the versions declared in the upgraded `Gemfile` / `Gemfile.lock`. CI drift (old Ruby version, old Rails matrix, stale service versions) is a frequent cause of red builds on the upgrade PR and is easy to miss because the local test suite passes.

**When to use:** Workflow 10 Step 6 (`workflows/10-implement-and-upgrade-workflow.md`), immediately before declaring the upgrade complete or opening a PR. Also any time the user reports a red CI build after an upgrade PR is opened. This workflow is **mandatory**, not a reminder — produce a written CI sync report and do not open the PR until every CI file matches the Gemfile.

## Inputs

- The upgraded `Gemfile` / `Gemfile.lock`
- Every CI configuration file in the repo

## Outputs

- CI sync report with a per-file verdict

## Gates (must be true before the next workflow that runs)

- Overall verdict is `OK`. Do not open the PR until every CI file matches the Gemfile.

---

## Step 1: Enumerate CI files

Use Glob to find every CI configuration file in the repo. Check all of these locations — projects commonly have more than one:

- `.github/workflows/*.yml` and `.github/workflows/*.yaml` (GitHub Actions)
- `.circleci/config.yml` (CircleCI)
- `Jenkinsfile`, `Jenkinsfile.*`, `.jenkins/*` (Jenkins)
- `.gitlab-ci.yml` (GitLab CI)
- `appveyor.yml`, `.appveyor.yml` (AppVeyor)
- `.travis.yml` (Travis CI — rare today but still present on legacy apps)
- `azure-pipelines.yml` (Azure Pipelines)
- `bitbucket-pipelines.yml` (Bitbucket Pipelines)
- `buildkite/*.yml`, `.buildkite/*.yml` (Buildkite)

If none are found:

- The app may rely on an external CI system (Heroku CI, Render, etc.) that this skill cannot inspect — flag this to the user and stop; the user has to verify CI themselves.
- The app may have no CI at all. Do **not** create one from scratch as part of the upgrade — the shape of a CI setup depends on the team's deploy pipeline and is out of scope here. Note it in the report (`No CI files found — skipping CI sync`) and continue with the rest of Workflow 10; do not block the upgrade on it. Adding CI is a separate decision the team should make outside the upgrade flow.

## Step 2: Read the Gemfile baseline

**First, identify the upgrade scope:** is this a Rails upgrade or a Ruby upgrade? Check what changed in the Gemfile / `Gemfile.next` compared to current `Gemfile.lock`. Only sync the dimension that actually changed — a Rails upgrade leaves the Ruby matrix alone; a Ruby upgrade leaves the Rails matrix alone. Touching the unchanged dimension adds noise and risks breaking a currently-green CI job.

Then record the versions CI should match. Only read the ones relevant to this upgrade (Ruby for a Ruby upgrade, Rails for a Rails upgrade):

- **Ruby version** — precedence: `Gemfile`'s `ruby "..."` line → current CI's Ruby → `.ruby-version`. The Gemfile is preferred because a `NextRails.next?` conditional makes both current and next Ruby explicit for the matrix.
- **Rails version constraint** — from `Gemfile` (`gem "rails", "~> X.Y.Z"`) and the resolved version in `Gemfile.lock`.
- **Next-Rails version** — if dual-boot is active, from `Gemfile.next.lock`.
- **Service versions** — default is to **replicate whatever the current CI already runs** (Postgres, Redis, MySQL, Elasticsearch, etc.). If CI is green today, those versions work. Only propose a bump when the upgrade explicitly requires it (e.g. the version guide or a bumped gem's changelog calls out a minimum). When in doubt, keep current CI service versions and note them in the report as `unchanged — matches current CI`.
- **Node / Yarn / bun version** — default to whatever the current CI uses. Only flag for change if the app's `package.json` engines, `.nvmrc`, or `.tool-versions` disagree with CI, or if the upgrade explicitly bumps the Node requirement.

## Step 3: Diff each CI file against the baseline

For each CI file, read it and check:

1. **Ruby version(s)** in the CI matrix, setup-ruby action, container image tag, or `rvm:` / `ruby:` key match the Gemfile baseline. For dual-boot, confirm both current Ruby AND (if applicable) next Ruby are present.
2. **Rails / BUNDLE_GEMFILE matrix** includes both `Gemfile` and `Gemfile.next` during dual-boot. After dual-boot cleanup, only `Gemfile`.
   - **If dual-boot is active but CI has no `Gemfile.next` matrix entry at all** (common when CI was set up before the upgrade started): this is a `DRIFT` finding. Extend the existing job matrix with a `BUNDLE_GEMFILE=Gemfile.next` entry (or duplicate the job and add the env var) so both versions run on every PR. Do NOT silently add it — show the user the proposed matrix diff and confirm before editing. Refer to the dual-boot skill's CI reference for platform-specific matrix patterns (GitHub Actions, CircleCI, etc.).
   - **If the CI file has no matrix concept at all** (single-job Jenkinsfile, simple Bitbucket pipeline): flag as `DRIFT — needs dual-boot wiring` and surface to the user rather than attempting an automatic rewrite; the shape of the fix depends on the pipeline.
3. **Service containers / images** (Postgres, Redis, MySQL, etc.) — default to leaving current CI service versions as-is. Only flag `DRIFT` if the upgrade explicitly requires a bump (called out in the version guide or a bumped gem's changelog). If a dual-boot job is being added, copy the services block from the current job rather than inventing new versions.
4. **Node / Yarn / bun** — keep the current CI value unless `package.json` engines / `.nvmrc` / `.tool-versions` disagree with it, or the upgrade explicitly bumps the Node requirement.
5. **Bundler version** pinned in CI (`bundler-cache: true` or `bundle install` step) is not older than `Gemfile.lock`'s `BUNDLED WITH`.
6. **Cache keys** that include Ruby or Rails version in the key string are updated, otherwise the cache will hit stale data and miss the new dependencies.
7. **Deprecated action versions** (e.g. `actions/checkout@v2`, `ruby/setup-ruby@v1` with an old Ruby) — optional to flag.

## Step 4: Produce the CI sync report

Emit a concise report. Only include CI files that were actually found in the repo — skip absent ones. One block per found file, plus a top-level verdict:

```
CI Sync Report
--------------
Gemfile baseline: Ruby 3.3.6, Rails 7.2.2, Node 20

.github/workflows/ci.yml
  Ruby matrix: [3.1, 3.2] ✗ (expected 3.3.6)
  Rails matrix: [Gemfile] (dual-boot removed — OK)
  Postgres service: 13 (unchanged — matches current CI)
  Verdict: DRIFT — fix before PR

Overall: 1 file needs changes. BLOCKING.
```

If the verdict is `DRIFT` for any file, do not mark Workflow 10 complete. Apply the edits, re-run the diff, and only proceed when the overall verdict is `OK`.

## Step 5: Apply fixes

Edit each drifting CI file directly. Prefer:

- **Reuse the existing matrix shape.** If a matrix is already defined (Ruby versions, Gemfile variants, service combinations), keep its structure and just update the values. Do not invent a new matrix layout when one exists.
- Bump matrix entries in place rather than adding new ones, unless the user explicitly wants to keep the old version running alongside.
- Only change service image tags when the upgrade explicitly requires it; otherwise preserve what the current CI runs.
- Remove `Gemfile.next` matrix entries only after the dual-boot cleanup step has run (coordinate with the dual-boot skill's cleanup contract).

After fixes, re-run Step 3 and regenerate the report. The report is part of the upgrade PR description when possible — it gives reviewers a clear audit trail.

---

## Common failure modes this workflow catches

- CI still running on the old Ruby patch after `.ruby-version` was bumped.
- Postgres / MySQL service container on a version the new Rails release dropped support for.
- Dual-boot removed locally but CI matrix still has `BUNDLE_GEMFILE=Gemfile.next` entries (builds fail because `Gemfile.next` no longer exists).
- Dual-boot set up locally but CI was never extended — the matrix still runs only the current `Gemfile`, so the next-Rails build never runs on PRs and breakages land unnoticed.
- GitHub Actions cache key pinned to old Rails version, causing phantom "works locally, fails in CI" bundle resolution mismatches.
- Node engine bumped in `package.json` but CI still using an older Node major — asset compilation fails.

---

## Self-review checklist

Before opening the PR, verify:

- [ ] Every CI file in the repo enumerated (GitHub Actions, CircleCI, Jenkins, GitLab, etc.)
- [ ] Ruby version, Rails matrix, and service versions diffed against the upgraded Gemfile
- [ ] CI sync report produced with per-file verdict
- [ ] All DRIFT entries fixed; overall verdict is OK
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall