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

Create a Custom Upstream

Connect a remote repository to your Pantheon account and use it as a starting point for new sites.

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

Pantheon Custom Upstreams are a self-serve feature available to anyone with access to the Workspace with an eligible plan. Workspace members will be able to create new sites from a set common codebase after an Workspace Administrator creates a Custom Upstream. The Custom Upstream must be created within each Workspace if you want to use a specific Custom Upstream for multiple Workspaces.

Note

Be aware that support for Custom Upstreams is limited to verification that the externally hosted upstream repository is connected to the platform correctly. For details, see Get Support.

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.

Follow the steps for your preferred Git host below to create your repository.

  1. Sign up for a GitHub account if you do not have one already.

  2. Log in to GitHub.

  3. Create an SSH Key if you don't already have one associated with your GitHub account and add your SSH Key to GitHub.

  4. Click Start Project if this is your first time logging in to GitHub. Otherwise click New in the Repositories sidebar on the left.

  5. Name the repository.

  6. Select whether the repository will be private or if it can be publicly accessible from outside your organization.

    Do not select the options to create a README, .gitignore, or license file:

    GitHub Initialization options

    Note

    As of October 1st, 2020, all new repositories on GitHub are initialized with the default branch name main.

    As a company, Pantheon is trying to use more inclusive language in our repositories. While our team works to make Custom Upstreams less reliant on older naming conventions, new Custom Upstreams currently default to using the master branch name.

  7. Click Create Repository.

  8. Copy the repository URI (SSH) found in the Quick setup section:

    GitHub Repo URI

  9. Clone the repository to your local from the command line (replace the URI):

    git clone [email protected]:pantheon-systems/custom-upstream.git

  10. Navigate to the repository's root directory:

    cd custom-upstream

Pull in Core from Pantheon's Upstream

You must track Pantheon's corresponding upstream repository within the Custom Upstream to avoid incompatibilities.

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

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

  2. Run the appropriate command below now that the Custom Upstream repository is tracking the corresponding Pantheon core upstream.

    git checkout -b master
git fetch pantheon-wordpress
git merge pantheon-wordpress/master
git push origin master

Connect Repository to Pantheon

  1. Go to the workspace where you want to add the upstream.

  2. Select the Upstreams tab.

  3. Click the Add New Upstream button. You must be an Organization Administrator to add a new upstream.

  4. Enter the following information about the Custom Upstream:

    • Name

    • Upstream Repository URL:

      GitHub HTTPS Repo URL

      • Authenticate (private repositories only): If you provided the URL to a private repository, a new field will appear:

        GitHub Upstream Authentication

        For privately hosted repositories, create a dedicated user with repository access. If your repository is publicly accessible, you can skip this step.

      1. Click 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.

  5. Return to the workspace where you are creating the Custom Upstream.

  6. Paste your new GitHub access token.

    • Framework: Drupal 7, Drupal (Latest), or WordPress

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

  7. Click Create.

Initial Connection Mode

The default connection mode for new sites created from a Custom Upstream is Git for WordPress and Drupal. The latest version of Drupal defaults to 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.

    • Enter a username and a password or token if prompted to authenticate your repository (this only applies to privately hosted repositories). Access tokens must be alpha-numeric and cannot contain symbols.

  4. Select if Git or SFTP mode should be enabled by default and then click Update. New sites created from this Custom Upstream will use this connection mode by default going forward.

    Modify initial connection mode

More Resources