Create a Custom Upstream

Connect a remote repository with Pantheon to use as a starting point for new sites.


Pantheon Custom Upstreams are a self-serve feature available to anyone with access to the Organization Dashboard. Once created, members of the organization will be able to create new sites from a set common codebase. For an overview of this feature, see Introduction to Custom Upstreams. In order to use a specific Custom Upstream on multiple Organizations, the upstream must be created within each Organization’s Dashboard.

Create and Host the Repository Remotely

This remote repository serves as the central location for the development and maintenance of your Custom Upstream. Changes are tracked here and distributed downstream to sites within your Organization as one-click updates in the Site Dashboard.

Choose your preferred Git host:

  1. Sign up for a GitHub account if you do not have one already.
  2. Log in to GitHub.
  3. If this is your first time logging into GitHub, click Start Project. Otherwise, click New Repository from the Repository sidebar on the right.
  4. Name the repository.
  5. Select whether the repository will be private or if it can be publicly accessible from outside your organization.
  6. Click Create Repository.
  7. Copy the repository URL (HTTPS), found in the Quick setup section:

    GitHub Repo URL

  8. Clone the repository to your local from the command line (replace the URL):

    git clone https://github.com/pantheondocs/agency-custom-upstream.git
    
  9. Navigate to the repository's root directory:

    cd agency-custom-upstream
    
  1. Sign up for a Bitbucket account if you do not have one already.
  2. Log in to Bitbucket and navigate to Repositories.
  3. Click Create a Repository.
  4. Name the repository.
  5. Select whether the repository will be private or if it can be publicly accessible from outside your organization.
  6. Click Create Repository.
  7. Copy the repository URL (HTTPS), found on the top right of the page:

    Bitbucket Repo URL

  8. Clone the repository to your local from the command line (replace the URL):

    git clone https://pantheondocs@bitbucket.org/pantheondocs/agency-custom-upstream.git
    
  9. Navigate to the repository's root directory:

    cd agency-custom-upstream
    

Pull in Core from Pantheon's Upstream

To avoid incompatibilities, you must track Pantheon's corresponding upstream repository within the Custom Upstream.

  1. Navigate to the Custom Upstream's root directory using the command line, then add the appropriate Pantheon upstream as a remote:

    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
  2. Now that the Custom Upstream repository is tracking the corresponding Pantheon core upstream, we can pull in core:

    git checkout master
    git fetch pantheon-wordpress
    git merge pantheon-wordpress/master
    git push origin master
    git checkout master
    git fetch pantheon-drops-8
    git merge pantheon-drops-8/master
    git push origin master
    git checkout master
    git fetch pantheon-drops-7
    git merge pantheon-drops-7/master
    git push origin master

Connect Repository to Pantheon

  1. Navigate to the Organizations tab within the Pantheon Dashboard and select your organization:

    Organization Dashobard

  2. Select the Upstreams tab.

  3. Click the Add New Upstream button. You must be an administrator of the organization to add a new upstream.
  4. Enter the following information about the Custom Upstream:

    • Name
    • Upstream Repository URL:

      GitHub HTTPS Repo URL

      Bitbucket HTTPS Repo URL

    • Authenticate (private repositories only): For privately hosted repositories, create a dedicated user with repository access. If your repository is publicly accessible, you can skip this step.

      1. Go to GitHub to generate a personal access token.
      2. Click Generate new token.
      3. Confirm your password if prompted.
      4. Enter a token description, such as "pantheon read my custom upstream"
      5. Select "repo" as the scope:

        GitHub generate token

      6. Click Generate token and copy the new token to your clipboard.

      7. Return to the Pantheon Organization Dashboard, where you are creating the Custom Upstream.
      8. Paste your new GitHub access token.
      1. Go to Bitbucket to generate an app password.
      2. Click Create app password.
      3. Enter a label and select the "Repositories:Read" permission:

        Bitbucket app password

      4. Click Create and copy the new password.

      5. Return to the Pantheon Organization Dashboard, where you are creating the Custom Upstream.
      6. The username field should already be populated, based on the repository URL. Paste your new Bitbucket app password.
    • Framework: Drupal 7, Drupal 8, or WordPress

    • Description: (Optional) Less than 200 characters, plain text and markdown supported
  5. Click Create.

Edit Existing Custom Upstream Settings

If you would like to change the name or description of your Custom Upstream:

  1. Navigate to the Organizations tab within the Pantheon Dashboard and select your organization.
  2. Select the Upstreams tab.
  3. Click Settings next to the existing upstream requiring an update.
  4. Make desired changes, then click Update.

Initial Connection Mode

The default connection mode for new sites created from a Custom Upstream is Git for WordPress and Drupal 7. Drupal 8 defaults to the SFTP connection mode.

Configure this setting after connecting your Custom Upstream to Pantheon if new sites need to use an initial connection mode other than the default:

  1. Navigate to the Organizations tab within the Pantheon Dashboard and select your organization.
  2. Select the Upstreams tab.
  3. Click Settings next to the existing upstream requiring an update.
  4. Select the desired connection mode, then click Update:

    Modify initial connection mode

New sites created from this Custom Upstream will use this connection mode by default going forward.

Repository URL and password

You cannot modify the repository details on existing Custom Upstreams. If there is a new URL or password you need to use, we recommend creating a new Custom Upstream and switching each site to the new upstream individually with Terminus:

terminus site:upstream:set my-site "My New Custom Upstream"

You must be a site owner to switch a site's upstream. After a site's upstream has been changed, you will need to merge changes as a one-click update. For details, see Example Usage.

Once all sites have been updated to track the new Custom Upstream, you can safely delete the old one:

  1. Navigate to the Organizations tab within the Pantheon Dashboard and select your organization.
  2. Select the Upstreams tab.
  3. Click Settings next to the existing upstream, then click Delete.

Switch an Existing Site to a Custom Upstream

Only a Site Owner can change an existing site to use a new custom upstream. Site owners can contact support, or use Terminus:

terminus site:upstream:set $site $upstream_id

In the example above, set or replace the variables $site and $upstream_id with your site name and upstream machine name, respectively. You can find your custom upstream's machine name using terminus org:upstream:list $org, where $org is your organization name.

Next Steps