Pantheon Community

Custom Upstreams

If you are using or considering using Custom Upstreams here are some tips, tricks and best practices. These came from the discussion during our Custom Upstream office hours and the research beforehand.

The what and why

  • Custom Upstreams act as a scaffold for new sites allowing a shared start state.
  • Upstreams are tied to an organization and each organization can have many upstreams, but a single site can only directly inherit from one upstream. Want to nest your upstreams? Check out the workflows below.
  • Custom Upstreams solve a lot of the problems that are encountered when trying to use a multisite environment on WordPress or Drupal.
  • For organizations responsible for managing a portfolio of sites. Custom Upstreams offer a great way for a small team to manage brand and code consistency at scale. For example:


  • As a best practice create a single site outside the upstream that uses the same code base. You can then test changes there before adding them to the upstream.
  • You can further test your upstream changes by creating two upstreams and setting both as remotes. Use one as a test upstream that you first push to to validate and then push to the other.
  • Some organizations are complex enough that they need multiple layers of upstreams. Since an upstream is really just a Git repository, it is possible to pull data from other repositories into your Custom Upstream repository. For example, sometimes an organization may want to set branding from the top down but still allow each department to manage their own Custom Upstream. One way to do this is to have one main Git repository that is forked into other Git repositories. Those forked repositories are then used as individual Custom Upstreams.
  • You can run scripts across all your sites on an upstream using the Terminus mass update plugin. For more information on that, check out this couch coding session. The mass update script is a great starting point for any custom mass updates needed.
  • You can deploy an upstream.pantheon.yml file to apply settings or enable workflows across all your sites. For example you could define the version of PHP for all your sites or use the deploy_product Quicksilver hook to post to Slack whenever a new site is spun up.


  • You can only pull upstreams from the master branch.
  • Sites need to be in Git deploy mode to pull in upstream changes.
  • You can’t deploy Composer with upstreams yet, though it is in the works. For now run Composer first and commit those files to the repository.
  • Once set up, you can’t adjust the repository connection setting. You will need to create a new upstream if you want to point to a new repository. You can switch a specific site’s upstream using Terminus. (Pair with the Terminus mass update script above to do this in bulk)
  • Some repositories, like GitLab or if you have a custom Git URL, can’t be automatically validated. Send those to the Pantheon support team who will manually validate and create the repository for you. Information on setting this up can be found under the GitLab tab in our docs.

Looking to get started? Check out our guides on how to create an upstream and how to maintain an upstream.