Skip to main content
Last Reviewed: April 17, 2023

Custom Upstream Best Practices

Detailed information on how to maintain Custom Upstreams.

This section provides information to help you manage and maintain your Custom Upstream.

Upstream Configuration File

Use the pantheon.upstream.yml file when working with Custom Upstreams to set default values for advanced site configurations to be used downstream. Review the Pantheon YAML Configuration Files documentation for details.


We normally suggest PHP redirects be placed into wp-config.php for WordPress and settings.php for Drupal. You will lose any customizations to your PHP files every time you update your Custom Upstream. It will also be difficult to implement site-specific configurations added on these files.

You can use a require_once statement to point to an external file since this file is shared on all environments, including Multidevs. It is also separate from the Custom Upstream and unique to each site:

if ( file_exists( dirname( __FILE__ ) . '/guides/redirect.php' ) && isset( $_ENV['PANTHEON_ENVIRONMENT'] ) ) {
  require_once( dirname( __FILE__ ) . '/guides/redirect.php' );

Remember that this file is not included in the Custom Upstream and must exist uniquely on each site. You can then expand the conditional statement to load on specific environments using the FAQ section in the wp-config-php doc.

WordPress sites can also store redirects in an MU-Plugin.

WordPress MU-Plugins

Be sure to include and update the MU-Plugins if you are using WordPress.

Refer to the WordPress Configuration guide for more information about MU-Plugins on the platform.

More Resources