What Is an Upstream?
Each Pantheon site is version controlled with Git and can receive core updates when available. When you create a new site on Pantheon and select WordPress, the new site is provisioned from the Pantheon WordPress repository.
The default Pantheon WordPress repository is a fork of WordPress with a few minor changes, such as injecting database credentials for the Dev, Test and Live environments on Pantheon. We update this repository when a new version of WordPress is released.
When the Pantheon WordPress repository is updated you will see a notification in the site dashboard for any sites that were created by selecting “Install WordPress”.
An upstream is simply an additional Git remote that acts as a parent for the main repository. Changes to the upstream repository flow downstream into any sites created from the upstream repository.
For example, if you fork a public, open source Git project, your fork would be the child repository and the the original repository you forked from would be the upstream repository. If there were changes made the the original repository after you forked, in order to pull those changes into your child repository, the upstream repository can be added as an additional remote repository and the changes pulled into your child (forked) repository. See GitHub’s help articles on configuring a remote for a fork and syncing a fork for details.
Custom Upstream Workflow
Agencies using Pantheon have access to all sorts of great features, including using a custom upstream repository for their Pantheon sites, instead of the default WordPress installation Pantheon provides. If you don’t have a Pantheon for agencies account you can create one here.
All new sites created from the custom upstream repository will have the common starting codebase, e.g. a parent theme and plugins used on all sites. Any updates made in the custom upstream will become available to sites created from it, making pushing out common code changes, plugin updates, etc. to all your sites easier.
This also allows for separation of concerns by keeping site specific code, like a WordPress child theme or customized plugins for each site, in the site level repository. Finally, this configuration also allows any updates to the Pantheon WordPress repository (e.g. core updates) to be merged into the custom upstream.
In this workflow, all updates flow downstream. Starting from the Pantheon WordPress repository, to your custom upstream repository and, finally, to each individual site created from your custom upstream.
Creating a Custom Upstream Repository
First, create a repository to use as a custom upstream remote on Pantheon. Custom upstream repositories must be hosted outside of Pantheon. This can be a hosted solution, such as GitHub, BitBucket or GitLab, or a Git repository hosted on your own.
Next, you will need to provide Pantheon access to the repository and open a support ticket to request the custom upstream be associated with your organization. See our doc on creating a custom upstream for details.
After the custom upstream repository is associated with your organization, clone the repository locally.
Assuming it’s a new repository, the next step is to add the Pantheon WordPress repository as an upstream and merge it into the master branch of your new custom upstream repository.
git remote add pantheon-wordpress git://github.com/pantheon-systems/WordPress.git
git checkout master
git fetch pantheon-wordpress
git merge pantheon-wordpress/master
git push origin master
Now you can commit changes to your custom upstream repository just like any other git repository. Anything committed to the master branch will be sent downstream to the individual sites using the upstream.
When there are updates to the Pantheon WordPress repository, after your initial merge, you can rebase the Pantheon WordPress repository. Assuming the remote is still named pantheon-wordpress on your local checkout, this is a quick process.
git fetch pantheon-wordpress
git rebase pantheon-wordpress/master
In summary, this custom upstream workflow allows separation between common code across all sites, tracked in the custom upstream, and site specific customizations, tracked in each individual site and facilitates rolling out updates quickly and easily.
Have you used a custom upstream before? If so, what are your thoughts on this workflow? I’d love to hear your feedback in the comments.
: Development, WordPress