Bitrix Upgrade Lifecycle Planning: A Practitioner's Playbook

Bitrix upgrade lifecycle planning isn't something most teams think about at project kickoff. They think about it when a security advisory lands in their inbox on a Friday afternoon.

We learned this the hard way. Bitrix 18, PHP 7.2, three years without a major update. Then a critical vulnerability in the core. The client called at 6:30 PM. Three and a half days of work — retesting every custom module, two rollbacks, one hosting emergency. Total: 28 person-hours to do what we now handle in 6.

That incident changed how we start every project. Not "we'll upgrade when we have to" but "we build the upgrade plan before the first deploy."

Why Bitrix upgrades become emergencies

A major Bitrix upgrade is a core platform migration that requires coordinating PHP version changes, marketplace module compatibility, and custom code updates simultaneously. Unlike a routine patch, it can't be safely deployed without a test environment and a known dependency list.

Most teams treat it like a package swap. It isn't — it touches:

Component APIs (old D6 templates, shortcodes, custom event handlers)
PHP version requirements (Bitrix 23+ needs PHP 8.1; older code was written for 7.4)
Marketplace modules (each vendor ships updates on their own schedule)

When it's planned, you know all of this in advance. You spin up a test environment on the target PHP version, fix compatibility issues, deploy in a scheduled maintenance window.

When it's an emergency, you have none of that. No test environment matched to the new version. No list of custom dependencies. No idea what will break. You're guessing, and the meter's running.

The root cause isn't technical. Nobody asked "how do we upgrade this in two years?" on day one.

The day-zero project checklist

Every new project gets a Technical Passport document. One section is the lifecycle plan.

Four things we lock in before the first deploy:

Current version and freeze date — which Bitrix version we're starting on, when official support ends, when we consider it frozen and stop patching without a maintenance window.
PHP version and LTS end date — PHP 8.1 reaches end of life in December 2025, PHP 8.2 in December 2026. I add calendar reminders on day one.
Custom module and vendor list — every marketplace module is a separate risk point for upgrades. We log the name, current version, and a link to the vendor's changelog. Twenty minutes now saves hours later.
First scheduled review date — typically 12–14 months after launch, before the next major Bitrix release cycle.

None of this is complicated. But the document exists from day one instead of getting assembled in a crisis.

Building a dependency map before it matters

A dependency map is a list of everything that could break during a major upgrade if you don't prepare.

We track three categories for every Bitrix project:

Core and D7 API — old D6 templates, direct calls to deprecated methods. We don't rewrite them immediately; we log them. They're the first thing to check when upgrade time comes.
Custom modules and event handlers — everything we built ourselves: event handlers, agents, custom components. For each one, a short note: "depends on API X, verify compatibility before upgrading."
PHP compatibility — deprecated functions that disappear in the next major version. We run php -l and PHPStan at the minimum level when code ships. Ten minutes per release, but it shows you exactly what needs refactoring.

The goal isn't to fix everything upfront. It's to have the list — and keep it updated with every deploy.

Triggers that force an unplanned review

An unplanned upgrade review is a mid-cycle assessment triggered by external events — security advisories, vendor end-of-life announcements, or custom module deprecations — that require action before the scheduled annual window.

Planned review is once a year. But some events move it up automatically.

Three signals I watch:

Bitrix releases a critical-severity security patch. Our rule: deploy within 72 hours, without major refactoring.
A PHP version goes end-of-life within 6 months. We start the migration plan — not wait for the deadline.
A vendor drops support for our version of a custom module. We check changelogs every time we update a module.

These triggers live in the Technical Passport too. When one fires, it creates a task in the tracker automatically.

It sounds like overhead. In practice it's three lines in a document that will, once, save you from a multi-day incident.

What our upgrade playbook looks like

When the planned window arrives, we work through a fixed sequence.

Four weeks out:

Spin up a test environment on the target PHP and Bitrix versions
Walk the dependency map and mark what's changed since the last review
Contact custom module vendors for any compatibility updates needed

Two weeks out:

Run the test suite against the new environment (automated + manual smoke)
Fix critical incompatibilities
Confirm the maintenance window with the client (usually 2–3 hours on a Sunday night)

Upgrade day:

Database and file backup
Deploy the upgrade per checklist
Smoke test production

After:

Update the Technical Passport with the new version and next review date
Close out the dependency map tasks

Total time across all of this: 6–8 hours. An unplanned emergency upgrade in our history: 3 to 5 working days.

The numbers

Three years ago — emergency upgrade from Bitrix 18 to 20, PHP 7.2 to 7.4: 28 person-hours, including rollbacks and retesting. Client lost 1.5 business days.

Most recent planned upgrade (Bitrix 22 to 23, PHP 8.0 to 8.1): 6 hours, zero rollbacks, maintenance window as scheduled.

The difference isn't experience or skill. It's that the dependency list and review schedule existed from day one.

If your Bitrix project has been running for a year and you can't answer "when are we upgrading next, and what will break?" — that's not a technical problem. It's the absence of a two-page document that takes 40 minutes to create at project start.

Starting it now isn't too late. But day one would have been better.

*Internal links: Bitrix doesn't slow down. The way teams use it does. · PHP-FPM pm.max_children: The Setting That Brings Bitrix Down Under Load*