Create a Custom Upstream

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

Discuss in our Forum Discuss in Slack

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

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

    Git's default naming convention differs from GitHub's. If you don't initialize the repository on GitHub, Git will assign the default branch name as master when you clone the repository locally.

  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 git@github.com:pantheon-systems/custom-upstream.git
  10. Navigate to the repository's root directory:

    cd 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. Select No from the dropdown menu for Include a README?.

  7. Select No from the dropdown menu for Include .gitignore?.

  8. Set the Default branch name to master

     Note

    As of January 27th, 2021, all new repositories on Bitbucket are initialized with main as the default branch name.

    Pantheon intends to remove harmful language from our code and documentation. Please refer to our documentation on more inclusive language in our
    repositories
    for more information.

    As we strive to make Custom Upstreams less reliant on older naming conventions, new Custom Upstreams currently default to using the master branch name.

    Please note that Git's default naming convention differs from GitHub's. If you do not initialize the repository on Bitbucket, Git will assign the default branch name as master when you clone the repository locally.

  9. Click Create Repository.

  10. Copy the repository URL (HTTPS), found on the top right of the page:

    Bitbucket Repo URL

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

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

    cd agency-custom-upstream

You can sign up for a GitLab.com account, or use a self-managed GitLab installation.

  1. Navigate to your GitLab dashboard and click New project.

  2. Provide a Project name, Project description (optional), and Visibility Level > click Create project.

  3. Copy the repository URL (HTTPS), and clone the site locally:

    git clone https://gitlab.com/pantheondocs/agency-custom-upstream.git
  4. cd into the project directory:

    cd agency-custom-upstream

Other Git hosting providers (like Azure DevOps or a self-hosted Bitbucket server) can be used, but we cannot detail specific instructions for every provider. You will need to create a new project in that system.

As detailed below, Pantheon Support will need to add this Custom Upstream for you from a support ticket.

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 > add the appropriate Pantheon Upstream as a remote:

    git remote add pantheon-wordpress https://github.com/pantheon-systems/WordPress.git
    git remote add pantheon-drupal-9 https://github.com/pantheon-upstreams/drupal-composer-managed.git
    git remote add pantheon-drops-7 https://github.com/pantheon-systems/drops-7.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
    1. Pull and commit the core files:

      git checkout -b master
      git fetch pantheon-drupal-9 main
      git merge pantheon-drupal-9/main
      git push origin master
    • Drupal 9 on Pantheon includes Integrated Composer to manage dependencies. This adds a separate composer.json file in the upstream-configuration directory.
    1. Change to the composer.json file in the upstream-configuration directory and use composer require to add packages to the Upstream > set the config version to a number that makes sense for you:

      cd upstream-configuration
      composer require drupal/pkg-name --no-update
      • Note that the optional --no-update flag in this command should only be used in Upstreams (as we do here) to instruct Composer not to check for updates now. See How to Add Dependencies to Your Upstream for more information about adding dependencies.
    2. Commit and push the changes:

      git commit -am "added composer dependencies"
      git push origin master
    git checkout -b 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 Dashboard

  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 Pantheon Organization Dashboard where you are creating the Custom Upstream.

  6. Paste your new GitHub access token.

    • Framework: Drupal 7, Drupal 9, or WordPress

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

  7. Click Create.

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

    Organization Dashboard

  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:

      Bitbucket HTTPS Repo URL

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

      BitBucket 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. 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. Paste your new Bitbucket app password. The username field should already be populated based on the repository URL.

    • Framework: Drupal 7, Drupal 9, or WordPress

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

  5. Click Create.

A Custom Upstream from a GitLab repository must be set up for you by Pantheon Support.

  1. Navigate to the repository > click Settings > select Repository.

  2. Click Expand next to Deploy Tokens and fill out the fields:

    • Name: Used to identify the token in GitLab.
    • Expires at: We recommend leaving this blank. If the token expires, you will need to create a new one and contact Pantheon Support again to update it.
    • Username: We suggest setting a custom username to provide to Pantheon Support.
    • Select the read_repository scope for the token.

    Adding a deploy token to a GitLab repository

  3. Click Create deploy token > save the token immediately to provide to Pantheon Support. GitLab will not show it again.

  4. Contact support to add the Custom Upstream to your org. You must provide:

    • A name for the Custom Upstream,
    • The https clone URL (ending in .git),
    • The Username and Access Token for the deploy token.

Custom Upstreams from other repository hosts must be created for you by Pantheon Support.

Common steps needed for most Git Providers are provided below.

  1. Prepare a new user specifically for Pantheon access.

    • This new account will need to be accessible via API for Pantheon, it must also have access to the repository created in the earlier step.
  2. Contact support to add the Custom Upstream to your org. You must provide:

    • A name for the Custom Upstream

    • The CMS within (WordPress, Drupal 7/9)

    • The https clone URL (ending in .git)

    • The username and Access Token for the new user

    • The name of the branch to be used by Pantheon (usually master)

Initial Connection Mode

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

  4. Select the desired connection mode > click Update:

    Modify initial connection mode

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

More Resources