Skip to main content
Log inGet free account
Last Reviewed: October 15, 2024

Custom Upstream Usage

Learn how to use an Upstream with Integrated Composer.

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

This section provides usage and maintanenance information for composer-managed Custom Upstreams on Pantheon, including steps to add upstream dependencies.

Custom Upstreams

An Upstream refers to the source code in Git that shares a Git history with "downstream" individual sites made from it. Upstreams includes the core code for Drupal, WordPress, and some customizations for the Pantheon platform.

Create Your Integrated Composer Custom Upstream

Follow the steps to Create a Custom Upstream to create and connect a new integrated composer custom upstream.

Custom Upstream and Site Structure

The upstream has the following directory structure:

code/
code/
├─ .gitignore
├─ composer.json
└─ pantheon.upstream.yml
├─ README.md
└─ upstream-configuration/
   └─ composer.json
└─ web/
   └─ sites/ for Drupal
   └─ app/ for WordPress (Composer Managed) (plugins, themes, and uploads)
   └─ wp/ for WordPress (Composer Managed) (core files)
  • .gitignore: Prevents build artifacts generated by Composer from being committed to the upstream or site code repositories. Note that changing the tracking status of Composer-managed files and directories can result in build failures or lead to unexpected errors.
  • composer.json: The two different composer.json files allows you to customize individual sites without inherent merge conflicts and enables one-click updates.
    • Root-level: Site-level customizations.
    • upstream-configuration/: Composer automatically updates composer.json with customizations for the upstream. Avoid manually modifying this file.
  • pantheon.upstream.yml: The build_step: true directive in pantheon.upstream.yml enables the build step.

When a site is created, Pantheon runs composer install, generates a composer.lock file, and commits it back to the site’s code repository. To avoid potential merge conflicts after applying an upstream update, do not commit the composer.lock file from your upstream root to the upstream repository.

The composer.lock file should not be listed in your .gitignore file because it must be committed for individual sites created from your custom upstream. Use the command below to avoid accidentally committing a composer.lock file when working directly with your custom upstream.

   echo /composer.lock >> .git/info/exclude

The command has the same effect as ignoring the file in the top-level .gitignore file, except that the exclude file is not saved in the repository when you push changes back to the remote origin. You must re-run this command every time you make a new local clone of your upstream if you would like to protect against inadvertently committing a composer.lock file.

Build artifacts are stored in a Git tag like pantheon_build_artifacts_$BRANCHNAME, where $BRANCHNAME is the name of the environment or Multidev feature branch.

It is a requirement that all build artifacts should be ignored in the .gitignore file. Ensure you add entries to the .gitignore any time you modify the build to move installation files to a new locations.

Add Dependencies to Your Upstream

  1. Clone the Git repository for your Custom Upstream.

  2. Require the Custom Upstream management package if you have not already:

    composer require pantheon-systems/upstream-management

  3. Run the composer upstream:require command for each dependency:

    composer upstream-require drupal/pkg-name [--no-update]

  4. Commit and push your changes to your composer.json file. Remember to not commit the composer.lock file.

Update Dependencies in Your Upstream

You may need to pin specific versions of your dependencies in your Custom Upstream. This is normally done with the composer.lock file. However, including the composer.lock file in the root of the Custom Upstream causes merge conflicts with your downstream sites. You can use the upstream:update-dependencies composer command to solve this problem.

  1. Run composer update-upstream-dependencies in your custom upstream repository. The upstream:update-dependencies command will:

    • Create or update a upstream-configuration/composer.lock file.

    • Create or update a upstream-configuration/locked/composer.json file with all packages from composer.lock and their pinned versions.

    • Update the top-level composer.json repositories section for upstream-configuration to use upstream-configuration/locked instead of just upstream-configuration (if not done previously).

  2. Commit the changes and begin using the pinned versions in your downstream sites. This allows you to make sure that you use specific versions for the packages in your Custom Upstream.

Maintain Your Integrated Composer Custom Upstream

There are some special considerations to keep in mind if you intend to make modifications to your upstream based on this repository.

  1. Increase the version number listed in the upstream-configuration/composer.json file each time you make edits.

    • Composer checks the contents of the root /composer.json file for changes that should be pushed to your upstream configuration.

  2. Verify your changes to the upstream-configuration/composer.json file by running composer install or composer update in the upstream-configuration directory.

More Resources