This doc includes instructions to make core updates to WordPress and Drupal sites hosted on the Pantheon WebOps platform.
Drupal 9 sites on Pantheon use Integrated Composer to allow one-click core updates through the Dashboard.
To check for available updates, navigate to Code in the Dev tab of the site's Dashboard. Click Check Now. If updates are available, click Apply Updates.
Drupal 8 sites managing core with Composer are not compatible with Pantheon's One-click updates and must update core using Composer exclusively. For instructions, see Build Tools or convert the site to Integrated Composer.
Pantheon maintains core upstream repositories for WordPress, Drupal 8, and Drupal 7 which act as a parent repository to site repositories. Updates made by Pantheon in the core upstream repository, in addition to updates made by maintainers of Custom Upstreams, become available downstream as a one-click update.
Apply one-click updates to individual sites repositories using the Site Dashboard on Pantheon, via Terminus, or manually from the command line. Do not update core using the WordPress Dashboard, Drush, or WP-CLI; you will overwrite your core. For additional details, see Scope of Support.
Navigate to the Code tab in the Site Dashboard on the Dev environment to check available updates:
If you have SFTP changes you want to commit and deploy, do so now. Then set the site's connection mode to Git.
From the Update Options menu, you can select whether or not you want to automatically resolve conflicts. Drupal users can opt to run
update.phpafter updates are applied:
Click Apply Updates.
Click Visit Development Site in the Development Environment to test and QA the site.
Follow the standard Pantheon Workflow to deploy changes up to Test and on to Live.
In the event that the update fails, you may see an error indicating a conflict with some files in core. Try the "Auto-Resolve" option when applying updates. Pantheon will try to automatically resolve conflicts in favor of the upstream Git repository. This does not solve all problems that may arise, but it should take care of most situations.
If the "Auto-Resolve Conflicts" option fails, the next step is to manually pull your changes in using Git, resolve the conflicts, and then push the update up to your Pantheon site. This does not solve all problems that may arise, but it should take care of most situations.
If you prefer using the command line, you can apply updates with Terminus.
terminus upstream:updates:apply site.env --updatedb
env with your site name and the correct environment. Learn more about this command by running
terminus help upstream:updates:apply.
The Terminus Mass Update Plugin can apply core updates to multiple sites at once:
For details, see Terminus Mass Update Plugin.
If the automated core update doesn't appear to be working, it's possible there are conflicts with your codebase in the update. You can resolve by overwriting your CMS core with the upstream, or attempt a manual merge conflict resolution.
If you receive the error that you have conflicts while updating core, the fastest resolution is often the
-Xtheirs flag. This will attempt to automatically resolve the conflicts with a preference for upstream changes and is safe to run if you don't have your own changes in any of the conflicting files (e.g. problems with
This process can potentially cause loss of data. Be sure you have no custom code in your CMS core before proceeding.
git pull -Xtheirs git://github.com/pantheon-systems/drops-8.git master # resolve conflicts git push origin master
git pull -Xtheirs git://github.com/pantheon-systems/drops-7.git master # resolve conflicts git push origin master
git pull -Xtheirs git://github.com/pantheon-systems/WordPress.git master # resolve conflicts git push origin master
Double-check the files before going forward to make sure no bugs were introduced.
If this procedure fails with the message
Already up to date. refer to this troubleshooting section to reset your git repository.
In the case where you're unable to use Git, you can use SFTP to overwrite core files.
Confirm that the Site Connection Mode is set to SFTP. Then, via SFTP, delete these files and folders:
├── README.md ├── index.php ├── license.txt ├── readme.html ├── wp-activate.php ├── wp-blog-header.php ├── wp-comments-post.php ├── wp-config-sample.php ├── wp-cron.php ├── wp-links-opml.php ├── wp-load.php ├── wp-login.php ├── wp-mail.php ├── wp-settings.php ├── wp-signup.php ├── wp-trackback.php ├── xmlrpc.php ├── wp-admin ├── wp-includes ├── wp-content └── index.php └── mu-plugins └── pantheon.php
Do not remove
Re-upload the corresponding files from GitHub.
Commit and switch back to Git mode.
Apply 1-click core updates via the dashboard and the auto-resolve should be checked. The update warning should disappear after a successful update.
This process lets you manually resolve the conflict using the command line and a text editor.
git remote add pantheon-wordpress git://github.com/pantheon-systems/WordPress.git
git remote add pantheon-drops-8 git://github.com/pantheon-systems/drops-8.git
git remote add pantheon-drops-7 git://github.com/pantheon-systems/drops-7.git
Replace the remote name (
custom-upstream-example) and repository URL (
git://github.com/example-org/custom-upsream-example.git) with values specific to your existing Custom Upstream:
git remote add custom-upstream-example git://github.com/example-org/custom-upsream-example.git
Pull down changes from the appropriate upstream:
git fetch pantheon-wordpress git rebase pantheon-wordpress/master
git fetch pantheon-drops-8 git rebase pantheon-drops-8/master
git fetch pantheon-drops-7 git rebase pantheon-drops-7/master
Replace the remote name (
git fetch custom-upstream-example git rebase custom-upstream-example/master
If a conflict is introduced, use the output provided to resolve. For example:
git rebase pantheon-wordpress/master First, rewinding head to replay your work on top of it... Applying: Adjust rendering of version release notes Using index info to reconstruct a base tree... M wp-admin/about.php Falling back to patching base and 3-way merge... Auto-merging wp-admin/about.php CONFLICT (content): Merge conflict in wp-admin/about.php error: Failed to merge in the changes. Patch failed at 0001 Adjust rendering of version release notes The copy of the patch that failed is found in: .git/rebase-apply/patch When you have resolved this problem, run "git rebase --continue". If you prefer to skip this patch, run "git rebase --skip" instead. To check out the original branch and stop rebasing, run "git rebase --abort".
In this example, you would open
wp-admin/about.phpin your preferred text editor.
Then look for the conflict markers starting with
<<<<<<< HEADand manually edit the file to merge changes between Pantheon's upstream (shown first between
=======) and changes made downstream in the Custom Upstream repository (shown second between
>>>>>>> Adjust rendering of version release notes).
Delete the conflict markers and double-check the changes.
git statusto see conflicting files in the current index again. Once all conflicts have been addressed, you can add them to your index and continue pulling in updates:
git add . git rebase --continue
Push updates to the Site Dashboard on Pantheon:
git push origin master
Whenever there's a new release of WordPress or Drupal core, updates will be available within 72 hours of upstream availability. Security related updates will be made available within 24 hours.
Drupal 8.7.x sites that have modified the
config_sync_directory value in
settings.php may see this error when upgrading to Drupal 8.8.x:
CONFIGURATION SYNC DIRECTORY
The directory sites/default/config does not exist.
To resolve (or avoid before upgrading), update the modified code as follows:
$config_directories = array( CONFIG_SYNC_DIRECTORY => dirname(DRUPAL_ROOT) . '/config', );
Replace it with:settings.php
$settings['config_sync_directory'] = dirname(DRUPAL_ROOT) . '/config';
example-drops-8-composer (the starting template for all Composer-managed sites on Pantheon) includes this configuration in
settings.php. Any site built from this example (e.g., using either the No CI workflow or the Build Tools workflow) will need to be updated.
By default WordPress admin will check for new upstream updates instead of the default WordPress update nag. You can disable this by setting the
DISABLE_PANTHEON_UPDATE_NOTICES constant to
true in your
wp-config.php file. This only disables the text and notice in the WordPress admin, you will still see upstream updates in the Pantheon dashboard.
define( 'DISABLE_PANTHEON_UPDATE_NOTICES', true );
Squashing and rewriting history may cause one-click updates to break, meaning updates will no longer appear on your Site Dashboard once available. Instead of using squash and rebase to clean up commits from merges occurring upstream, we recommend reviewing history locally with
git log --first-parent. This provides the same history shown on the Site Dashboard and prevents conflicts with our one-click updates.
If you are in a situation where you've altered the commit history in such a way that the dashboard is no longer able to determine if your site is up to date with the upstream, the simplest course of corrective action is to use
git reset --hard to reset the site repository to the last known good commit before the squash/rebase/revert was applied. This will result in losing all changes that have happened since this commit. You will need to re-apply all custom/contributed code updates that occurred in the interim, so make sure to take stock of these changes first and develop a plan to reapply them with the fixed Git history.
Core updates for Custom Upstreams are initiated by the repository maintainer, not Pantheon. Please report issues directly to the project maintainer for expected updates.
It's important to relay the need for updating core to maintainers, even if you plan on manually pulling in core version updates. First, file an issue in the queue of your repository and reach out to a maintainer. Even better - submit a pull request for the update.
Once you have communicated the issue, you can manually apply updates from the command line.
If you know your site's Custom Upstream has updated code, but it's not visible on your Site Dashboard, click on Check now:
This will trigger a "Code Cache Clear" to verify that the Site Dashboard has fetched the most recent commit. Please note that even after the workflow completes, it may take up to a minute before updates appear on the dashboard.
If updates are still not showing on the site, it may be necessary to re-set the site's upstream via Terminus. Please note that only the Site Owner or owning Organization Administrators can change a site's upstream.
There are multiple reasons that 503 errors might occur when updating:
PHP segfault: These are tricky to troubleshoot because very little debugging information is present. A temporary fix is available. Contact Pantheon Customer Support if you think you have been affected.
Timeouts are another cause of 503 errors, though they are much less likely to occur if you are using the Pantheon domains. If the operation takes more than 60 seconds, you might see a timeout occur.
Error updating: CONFLICT (modify/delete): pantheon.upstream.yml deleted in HEAD and modified in upstream/master. Version upstream/master of pantheon.upstream.yml left in tree
This issue happens when you attempt to update very outdated core files from the Dashboard. Perform the following to resolve:
.gitignoreand add a
#at the beginning of the
pantheon.upstream.ymlline to comment it out
Set the Site Connection Mode to SFTP
pantheon.upstream.ymlfile if missing:pantheon.upstream.yml
# IMPORTANT NOTE: # Do not edit this file unless you are doing so in your custom upstream repository. # Override the defaults specified here in a site-specific `pantheon.yml` file. # For more information see: https://pantheon.io/docs/pantheon-upstream-yml api_version: 1 php_version: 7.3 # See https://pantheon.io/docs/pantheon-yml/#enforce-https--hsts for valid values. enforce_https: transitional # See https://pantheon.io/docs/pantheon-yml#protected-web-paths for usage. protected_web_paths: - /private/ - /wp-content/uploads/private/ - /xmlrpc.php # By default, any 'protected_web_paths' added to the pantheon.yml file # are combined with the paths from the pantheon.upstream.yml file. If # 'protected_web_paths_override' is set to true, then the upstream paths # are disabled. protected_web_paths_override: falsepantheon.upstream.yml
# IMPORTANT NOTE: # Do not edit this file unless you are doing so in your custom upstream repository. # Override the defaults specified here in a site-specific `pantheon.yml` file. # For more information see: https://pantheon.io/docs/pantheon-upstream-yml api_version: 1 php_version: 7.3 # See https://pantheon.io/docs/pantheon-yml/#enforce-https--hsts for valid values. enforce_https: transitional # See https://pantheon.io/docs/pantheon-yml#protected-web-paths for usage. protected_web_paths: - /private/ - /sites/default/files/private/ - /sites/default/config/ - /sites/default/files/config/ # By default, any 'protected_web_paths' added to the pantheon.yml file # are combined with the paths from the pantheon.upstream.yml file. If # 'protected_web_paths_override' is set to true, then the upstream paths # are disabled. protected_web_paths_override: falsepantheon.upstream.yml
# IMPORTANT NOTE: # Do not edit this file unless you are doing so in your custom upstream repository. # Override the defaults specified here in a site-specific `pantheon.yml` file. # For more information see: https://pantheon.io/docs/pantheon-upstream-yml api_version: 1 php_version: 7.2 drush_version: 8 # See https://pantheon.io/docs/pantheon-yml/#enforce-https--hsts for valid values. enforce_https: transitional # See https://pantheon.io/docs/pantheon-yml#protected-web-paths for usage. protected_web_paths: - /private/ - /sites/default/files/private/ # By default, any 'protected_web_paths' added to the pantheon.yml file # are combined with the paths from the pantheon.upstream.yml file. If # 'protected_web_paths_override' is set to true, then the upstream paths # are disabled. protected_web_paths_override: false
Return to the Commit in dashboard, and note that
pantheon.upstream.ymlcan now be committed
Set the Site Connection Mode to Git and reapply updates
.gitignoreand remove the
pantheon.upstream.ymlline to instruct Git to ignore the file again