Skip to main content
Log inGet free account
Last Reviewed: December 09, 2022

Test Custom Upstream Changes Before Release

Create a test version of your Custom Upstream to review changes.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

Maintainers of Custom Upstreams bear the responsibility of pulling in core updates from Pantheon. Regardless of update type, always test changes before you distribute them to your sites. We recommend using the workflow example below to test and update core.

Note

Failure to run the most up-to-date version of core based on upstreams maintained by Pantheon (WordPress and Drupal may cause incompatibilities with the platform (for example, the clear cache button, launch checks, cron, and more).

Use the Pantheon Workflow

Create content on your test site and use the standard Pantheon workflow to push up to your Test and Live environments, and fully test core updates. Checkout our guide for an example of generating content from the command line.

Sample a Few Sites

We suggest picking a few sample sites with varying functionality and design to test updates on a Multidev environment or agencies that manage large portfolios. Release the update when things look good on these sites.

Before You Begin

Follow the procedure to create a custom upstream and confirm that you have:

  • A repository for your Custom Upstream hosted with your preferred provider (GitLab, Bitbucket, etc.)

  • A local clone of that repository, which tracks Pantheon's upstream as a remote

  • Pantheon's core code merged into your Custom Upstream repository

  • Your Custom Upstream repository connected to Pantheon

  • Terminus

Create a Test Site on Pantheon

This test site will be used later for evaluating Custom Upstream changes.

  1. Go to your Personal Workspace > click Create New Site.

  2. Name your site.

  3. Select your organization from the dropdown menu.

  4. Click Create Site.

  5. Select the desired repository from the Custom Upstream options.

  6. Click Visit your Pantheon Dashboard.

  7. Click Visit Development Site and complete the installation process for the selected framework.

Warning

Custom Upstreams cannot contain the tags pantheon_test_n or pantheon_live_n. Pantheon site level repositories use these tags to deploy code to Test and Live environments.

Test and Release Pantheon Core Updates

  1. Navigate to the local clone of your Custom Upstream repository > add Pantheon's Upstream as a remote if you haven't done so already:

    git remote add pantheon-wordpress https://github.com/pantheon-systems/WordPress.git

  2. Add the test site you created above as a remote to your Custom Upstream by grabbing the test site's repository URL on Pantheon using Terminus. Replace <site> with your site name:

    terminus connection:info <site>.dev --field=git_url

  3. Replace <git_url> in the following command to add your new test site as a remote:

    git remote add pantheon-test <git_url>

  1. Checkout a new branch:

    git checkout -b "core-update"

    It's important to use feature branches when applying and testing updates. Updates applied on the master branch and pushed to the remote repository on GitHub or Bitbucket become available to individual sites downstream. Using a feature branch gives you a chance to reveal issues before distributing updates.

  2. Pull down Pantheon's core updates from the appropriate upstream:

    git fetch pantheon-wordpress
git merge pantheon-wordpress/master

  3. Push to your new test site on Pantheon:

    git push pantheon-test core-update

  4. Return to the Site Dashboard for your test site > navigate to the Multidev overview tab > click Git Branches.

  5. Click the Create Environment button next to the core-update branch.

  6. Use the new Multidev environment to evaluate your core-update branch > merge the branch into master > push to your remote repository on GitHub or Bitbucket when you're ready to release:

    git checkout master
git merge --no-ff core-update
git push origin master

    The example command above assumes you are using the default remote destination (origin) for your Custom Upstream repository that's hosted with your preferred provider.

Updates will become available to sites downstream as one-click updates within an hour of being pushed to the remote repository on sites running the Custom Upstream within your Organization. You can apply the updates on each site individually within the Site Dashboard, or you can apply updates in bulk using Terminus and the Mass Update plugin. Review the WordPress and Drupal Core Updates documentation for more details.

More Resources