Navigating Drupal 9 to Drupal 10 Upgrade on Pantheon

Introduction

When a prominent cybersecurity firm, already influential on the global stage, sought to fortify its web presence, they turned to Axelerant for strategic Drupal expertise. Their primary platform, a critical touchpoint for cybersecurity content and product showcases, needed not just technical updates but a forward-looking transformation to support scale, security, and credibility.

Our preliminary audit revealed critical modernization needs. The platform was running on Drupal 9 and PHP 7, both of which had reached end-of-life. This posed risks not just to site stability but also to long-term security and compliance. To ensure sustainability and align with current best practices, we recommended a comprehensive upgrade to Drupal 10 and PHP 8.1+, laying the groundwork for a more resilient, secure, and future-ready digital experience.

Preliminary Audit

Our first step was a comprehensive audit of the site’s codebase to evaluate its readiness for a Drupal 10 upgrade. This involved a detailed analysis of critical components, including:

• The core Drupal version
• Contributed modules
• Custom modules and themes
• PHP compatibility
  
  

To streamline this process, we utilized the Upgrade Status module. This tool provided a visual report categorizing each module and theme by:

• Immediate compatibility with Drupal 10
• Compatibility with an available upgrade path, pending updates
• Deprecated or incompatible components lacking a clear path forward
  
  

The report enabled us to not only estimate the effort required for a successful upgrade but also map out the key technical challenges, giving us a strategic foundation to prioritize remediation and modernization efforts.

Key Challenges Uncovered During the Readiness Audit

Our audit surfaced several critical roadblocks that needed to be addressed before a seamless Drupal 10 upgrade could be achieved. 

No Straight Path Forward: Major Upgrade Gaps

The site was running on Drupal 9.4, a version far enough behind that a direct upgrade to Drupal 10 would lead to immediate breakages. Deprecated code and removed APIs made it clear that intermediary upgrades or major refactoring would be necessary to ensure stability.

Deprecated Themes and Modules

Several themes and modules used on the site were deprecated or no longer maintained. Key changes included:

• Replacing the Seven admin theme with Claro
• Migrating from CKEditor 4 to CKEditor 5
• Uninstalling deprecated modules that no longer have a version compatible with Drupal 10. 

Custom Code Compatibility

Unlike core and contributed modules, which have community-reviewed Drupal 10 releases, the site’s custom modules and themes required manual updates to:

• Remove deprecated Drupal 9 APIs
• Refactor code for compatibility with PHP 8.1+

This effort was crucial to minimize regression risk and ensure long-term maintainability.

Pantheon Deployment Restrictions

The site was hosted on Pantheon, which made deployments easier but introduced certain workflow restrictions like:

1. A linear Git model (Dev → Test → Live) restricted our ability to cherry-pick changes
2. Multi-step deployments became cumbersome, requiring us to rework our CI/CD practices.

PHP 8.1+ Compatibility

Since Drupal 10 requires PHP 8.1+, we had to ensure that all custom code and contributed modules worked with the upgraded PHP version.

Plan and Approach

To address these challenges, we devised a step-by-step upgrade strategy rather than attempting a direct upgrade.

Step 1: Upgrade to Drupal 9.5, Switch to Claro & CKEditor 5

The site was originally on Drupal 9.4, and best practice dictates first upgrading to the latest minor version before jumping to a major release. So, we planned to do the following:

• Upgrade to Drupal 9.5
• Replace Seven with Claro
• Switch from CKEditor 4 to CKEditor 5
• Uninstall all deprecated modules

Step 2: Upgrade Contributed Modules & PHP

We:

• Updated contributed modules to their latest Drupal 9.5-compatible versions
• Removed any deprecated modules
• Upgraded PHP to 8.1+

Step 3: Remove Google Analytics (GA) Login

Unexpectedly, our local setup threw errors due to incompatibility with the GA Login module. After thorough troubleshooting, we decided to remove it before proceeding.

Step 4: Upgrade to Drupal 10.3

After we had all modules, themes, and PHP updates in place, we proceeded with the Drupal core upgrade to 10.3.

Handling Pantheon Deployment Challenges

Pantheon Workflow & Why Cherry-Picking Is Restricted

For those unfamiliar with Pantheon hosting, it provides three standard environments:

• Dev
• Test
• Live

Additionally, it allows temporary "Multidev" environments for development or testing.

Why We Couldn't Cherry-Pick Commits

Pantheon enforces a sequential Git-based deployment workflow (Dev → Test → Live), meaning:

• You cannot push specific commits to Test or Live
• Test and Live are in a "detached HEAD" state (they don’t actively track a Git branch)
• Code and database updates must stay in sync—cherry-picking could cause schema mismatches

How We Adapted The Deployment Process

After discussion with Pantheon tech support, we decided to alter our usual deployment approach. Instead of deploying each upgrade step separately, we:

1. Used Multidev as a temporary UAT environment
2. Temporarily treated Dev, Test, and Live as a "single production environment"
3. Deployed Step 1 separately in production (to allow the admin team to adapt to Claro & CKEditor 5)

Upgrading To Drupal 9.5 In Local 

During the upgrade, it's recommended to repeat the steps multiple times locally and thoroughly test each one. 

We used the Upgrade Status module report as a reference and started the core upgrade to 9.5. 

Upgrading the modules was primarily done by Composer install and Drush. Each step was followed by a cache clear. 

We also switched to CKEditor 5 and the Claro theme via the UI and exported the configuration. We also uninstalled the old Seven theme and migrated the CKEditor editor and filter formats. 

For testing deployment, we used the following order to install the core and run the upgrades. 

Once testing was completed on the test server, we deployed to production. 

Upgrading Contributed And Custom Modules 

This is the part that can consume the most time, depending on the number of contributed modules and the number of custom themes and custom modules. 

1. After upgrading the local version to PHP 8, we used the Upgrade Status module again to determine which contributed modules needed to be updated. We then used composer to upgrade each module to the desired version. Each time we upgraded a module (simply replacing the old one via composer), we ran the database updates and revised the Upgrade Status module report to verify whether the report picked up the updated version.

Note: You also need to upgrade Drush along with the composer PHP version.

2. As soon as the PHP version was upgraded, the custom modules started throwing errors. We ensured that debugging mode was enabled in the settings.php file and proceeded to manually fix the errors and make the error-prone code compatible with PHP 8 and D10. After the site was stable, we proceeded to upgrade the Drupal core to 10.3. 

3. We had to test each step multiple times with the latest copy of the production database on our local site. In the local testing, errors occurred, and we thoroughly documented each error. We also documented all the individual routes we took on each step. This way, if an error occurs, it would be easy to retrace the steps and justify the effort we took if it exceeds the estimate.

4. Once everything looked good, we deployed each step to Pantheon multidev, which acted as the UAT environment.

Note: It is recommended to review the dblog/watchdog for errors and warnings related to PHP 8.1 compatibility and tackle each one of them once all the modules are upgraded. 

Final Deployment On Pantheon

After the UAT sign-off was received:

• We synced Dev & Test with Live
• Put the site into maintenance mode

• Merged Step 2 into master and pushed to Pantheon

• Deployed from Dev → Test → Live in quick succession

Since Pantheon enforces linear deployments, we had to deploy each upgrade step sequentially rather than all at once. While this took extra time, it ensured a smooth transition.

Reflections on Our Drupal 10 Upgrade Journey

Upgrading incrementally, rather than all at once, allows organizations to proactively identify and address issues. Our move to Drupal 9.5 first helped surface potential challenges we might encounter with Drupal 10. Testing with a local copy of the production database proved critical in uncovering errors that would otherwise have only appeared post-deployment.

Additionally, working within Pantheon’s Git restrictions required thoughtful planning; by leveraging Multidev environments and using the Test environment as a temporary UAT space, we ensured smoother coordination.

The outcome? A seamless deployment, and the client’s website is now running securely and efficiently on Drupal 10.3.

Ready To Tackle Your Next Drupal Upgrade?

If your team is planning a Drupal upgrade or facing similar challenges, we’re here to help. Reach out to the Axelerant team to explore how we can support your smooth, secure, and future-ready platform upgrade.