Custom Upstream Usage

The upstream has the following directory structure:

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

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:

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

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

   The composer.lock file should not be added to your .gitignore file, since it must still be committed for individual sites created from your Custom Upstream. Instead, run the following command to prevent yourself from accidentally committing it while working directly in the Custom Upstream repository:

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.