Use an Upstream with Integrated Composer
Learn how to use an Upstream with Integrated Composer.
This section provides information on how to use an Upstream with Integrated Composer, including steps to add dependencies to your Upstream.
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.
Upstream and Site Structure
The upstream has the following directory structure:
code/
├─ .gitignore
├─ composer.json
└─ pantheon.upstream.yml
├─ README.md
└─ upstream-configuration/ or upstream-config/ for WordPress
└─ composer.json
└─ web/
└─ sites/ for Drupal
└─ wp-content/ for WordPress
.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 differentcomposer.json
files allows you to customize individual sites without inherent merge conflicts and enables one-click updates.- Root-level: Site-level customizations.
- Drupal:
upstream-configuration/
or WordPress:upstream-config/
:composer.json
: Composer automatically updatescomposer.json
with customizations for the upstream. Avoid manually modifying this file.
pantheon.upstream.yml
: Thebuild_step: true
directive inpantheon.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
Clone the Git repository for your Custom Upstream.
Require the Custom Upstream management package if you have not already:
composer require pantheon-systems/upstream-management
Run the
composer upstream:require
command for each dependency:composer upstream-require drupal/pkg-name [--no-update]
Commit and push your changes to your
composer.json
file. Remember to not commit thecomposer.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.
Run
composer update-upstream-dependencies
in your custom upstream repository. Theupstream: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 fromcomposer.lock
and their pinned versions.Update the top-level
composer.json
repositories section forupstream-configuration
to useupstream-configuration/locked
instead of justupstream-configuration
(if not done previously).
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.