Skip to content

Upgrade status

The upgrade status job runs commands to help you review the Drupal next major upgrade readiness of the environment and components of the module. It is part of the Upgrade Status project. Use it to prepare for a Drupal 10 to 11 upgrade, and 11 to 12 upgrade.

The module provides the following key features:

  • Checks if you are using a version of Drupal that supports an upgrade.
  • Checks if your system meets the next major version's system requirements.
  • Integrates with the Update Status core module to inform you to update your contributed projects. Projects can be compatible with multiple major Drupal versions, so most projects can be updated on your existing site before doing the core major update.
  • Runs PHPStan checks and a whole set of other checks to find any compatibility issues with the next Drupal major version that may remain (see more details below).
  • Integrates with drush.

Enabling this job

This experimental job is controlled by the variable RUN_JOB_UPGRADE_STATUS which is set to 0 by default. To run the job you need to set the value to 1 in your .gitlab-ci.yml file or in a manually created pipeline. 

variables:
  RUN_JOB_UPGRADE_STATUS: '1'
Ideally you should only enable this job in an MR where you are actively porting your module to a new major branch of core. It is not recommended to have it enabled in all your pipelines.

Once enabled, the job will still not start automatically by default, it will need to be manually triggered when viewing the pipeline. It can be run automatically by setting the variable _AUTORUN_UPGRADE_STATUS to mr. The only other valid value is none (which is the default). Thus the job can only be automatically run within a Merge Request pipeline.

Core version

By default, this job will use the value of DRUPAL_CORE based on what these templates define as 'current'. For example, at the time of writing, Drupal 11 is the 'current' major and Drupal 12 is 'next major'. So the upgrade status job will run using Drupal 11 and check for compatibility with Drupal 12.

If instead, you want to run the job from the previous major to check for compatibility with the current major, you need to define the DRUPAL_CORE variable to point to the previous major. In the scenario above, Drupal 10 is 'previous major'. So if you want to run upgrade status on a project to check for D11 compatibility, you would need: 

composer:
  variables:
    DRUPAL_CORE: $CORE_PREVIOUS_STABLE

Arguments to the analyze call

You can pass additional arguments to the drush upgrade_status:analyze command by setting the _UPGRADE_STATUS_ANALYZE_EXTRA variable. 

variables:
  _UPGRADE_STATUS_ANALYZE_EXTRA: '--extra --options'

How does this job compare with the "next major" job?

The "Upgrade status" job is an individual job as opposed to a full variant (composer + phpstan + phpunit + nightwatch). It can also help you with the fixes, as opposed to just showing the errors.