Integrated Composer

Learn how to deploy a site with Integrated Composer

Contributors: Ari Gold, Edward Angert.

Discuss in our Forum Discuss in Slack

Integrated Composer lets you deploy your site on Pantheon with one-click updates for both upstream commits and Composer dependencies, while still receiving upstream updates.

Create a new site with Integrated Composer as part of Pantheon's Limited Availability release. New sites created through Pantheon's Limited Availability program are production-ready.

Create a New Site With Integrated Composer

Drupal 9 with Integrated Composer

Please note the Limited Availability program does not include a path to upgrade from previous Drupal versions to Drupal 9. Upgrade instructions for existing Drupal 8 Composer-enabled sites will be available when Integrated Composer moves into General Availability.

  1. Use this link to create a new Drupal 9 Integrated Composer site from the Upstream: On the Create Your Pantheon Site page:

    • Enter a name for the site.

    • Choose an Organization if applicable.

    • Choose a region for the site. Click Continue.

    After you click Continue, it will take several minutes for the platform to set everything up.

  2. In the Dev tab on the Dashboard, set the site's Development Mode to SFTP.

  3. Still in the Dev tab, click Visit Development Site and follow the prompts to complete the CMS installation.

  4. Return to the Dev tab, set the site's Development Mode to Git, and clone the site locally.

  5. In your local terminal, from the project root directory, run composer install.

WordPress with Integrated Composer

  1. Fork the Pantheon-maintained repository from

  2. Add a new Custom Upstream on the Pantheon dashboard.

  3. Create a new WordPress site from the Upstream.

    • Do not customize the upstream yet.
  4. In the Dev environment, click Visit Development Site and follow the prompts to complete the CMS installation.

  5. Clone the site locally and run composer install.

Upstream and Site Structure

The upstream has the following directory structure:

├─ .gitignore
├─ composer.json
└─ pantheon.upstream.yml
└─ upstream-configuration/
   └─ composer.json
  • .gitignore: Prevents build artifacts generated by Composer from being committed to the upstream or site code repositories.
  • composer.json: The two different composer.json files allow customization of individual sites without inherent merge conflicts and enable one-click updates.
    • Root-level: Site-level customizations.
    • upstream-config/composer.json: 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. This name is temporary and will change.

When a site is created, Pantheon runs composer install, generates a composer.lock file and commits it back to the site’s code repository.

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

How to Add Dependencies to Your Upstream

  1. Start with the local clone of the Upstream repository you created above.

  2. Change into the upstream-config directory:

    cd upstream-config
  3. Run:

    composer require drupal/pkg-name --no-update

    --no-update tells Composer to disable automatic updates of the dependency. This makes Composer faster when adding dependencies to the Upstream as shown here. --no-update should not be included when adding dependencies to a site.

  4. Set or increment the current configuration version:

    • If this is your first time setting the config version:

      Confirm the version:

      composer config version
    • Increment the config version number when you update dependencies. If you don't increment the version number, Composer will ignore updated dependencies. Replace 1.0.1 in this example with another number:

      composer config version 1.0.1
  5. Commit and push.

Apply One-click Updates

Navigate to Code in the Dev tab of the site's Dashboard.

Click Check Now. If updates are available, click Apply Updates.

Add a Dependency to an Individual Site

  1. Clone the Git repository from the Pantheon site's dashboard.

  2. Run composer install:

    composer install
  3. Add a new dependency locally:

    composer require drupal/pkg-name
  4. Commit composer.json and composer.lock and push.

    • Pantheon will run Composer, generate build artifacts, and deploy it to your Dev or Multidev environment.
  5. Remove dependencies:

    composer remove drupal/pkg-name

Pantheon's Scope of Support for Composer

Pantheon supports the version of Composer integrated into the Pantheon platform and available for use with all Drupal 8+ and WordPress sites. Pantheon’s support for Composer is limited to the application level, and any Composer scripts or modifications made with a Composer script are outside the Pantheon Scope of Support.

Troubleshooting / FAQ

What Composer commands does Pantheon run?

All Composer commands are available through the Commit Log in the Site Dashboard's development environment.

Can I view live logs?

Composer build logs are only available after the task or action completes (or fails).

How do I view Composer's changes?

Use git diff to view changes, excluding composer.lock

git diff d94d1a1179 -- . ':(exclude)composer.lock'

Try composer-lock-diff to see what packages have changed after composer update.

Can I use a Composer GUI?

Pantheon does not offer support for Composer GUIs or any conflicts that might be cause by one.

What features are planned for Integrated Composer on Pantheon?

Pantheon's devs are working hard to make the Integrated Composer experience on Pantheon better.

Features that are still in development:

  • Integrated Composer and Build Tools
  • Upgrade an existing site to use Integrated Composer