Setup Drupal
Configure a Drupal GitHub repository for Pantheon's GitHub integration with the required file structure and platform settings.
This page describes how to configure a Drupal 11 repository for Pantheon's GitHub integration. Unlike WordPress, Drupal on Pantheon uses Integrated Composer — most Pantheon-specific configuration is handled automatically by the pantheon-systems/drupal-integrations Composer package.
Summary of Differences
| Item | Standard Drupal 11 | Pantheon Drupal 11 |
|---|---|---|
composer.json | Drupal core dependencies | Adds pantheon-systems/drupal-integrations, scaffold config, Quicksilver installer path |
pantheon.upstream.yml | Does not exist | Required — platform infrastructure config with build_step: true |
settings.php | Generated during install | Pre-configured to include settings.pantheon.php |
settings.pantheon.php | Does not exist | Auto-generated by the drupal-integrations package |
.gitignore | Standard Drupal | Modified — excludes Composer-managed dependencies |
web/core/, vendor/, contrib | Committed or varies | NOT committed — built by Integrated Composer on deploy |
How Drupal Integration Works
Add pantheon-systems/drupal-integrations as a Composer dependency.
This package uses Drupal's scaffold system to automatically generate settings.pantheon.php and related files during composer install.
Pantheon's build system runs composer install on deploy (enabled by build_step: true in pantheon.upstream.yml).
Drupal core, contrib modules, and vendor/ are NOT committed to Git — they are built on deploy.
Directory Structure
Items marked (Pantheon) are additions or modifications. Items marked (Built) are generated at build time and should NOT be committed.
Modified Files
composer.json
This is the most important file. It configures Pantheon-specific dependencies, installer paths, and build hooks.
Key differences from a standard drupal/recommended-project:
| Component | Standard Drupal | Pantheon Drupal |
|---|---|---|
pantheon-systems/drupal-integrations | Not present | Required — scaffolds settings.pantheon.php |
drupal-scaffold.allowed-packages | Only drupal/core | Also allows pantheon-systems/drupal-integrations |
drupal-scaffold.file-mapping | Default | Disables scaffolding of .editorconfig, pantheon.upstream.yml, .gitattributes |
| Quicksilver installer path | Not present | Maps type:quicksilver-script to web/private/scripts/quicksilver/ |
config.platform.php | Not set or varies | Must match php_version in pantheon.upstream.yml |
cweagans/composer-patches | Not present | Included for patching support |
It is expected that you will update this file from the original and Pantheon does not maintain it for you.
Source: composer.json
The config.platform.php value in composer.json must match the php_version in your pantheon.upstream.yml. If they differ, dependency resolution may install packages incompatible with your runtime PHP version.
pantheon.upstream.yml
| Setting | Purpose |
|---|---|
api_version | Pantheon config API version (always 1) |
web_docroot | Tells Pantheon the web root is web/ (not repository root). Required for Drupal. |
enforce_https | HTTPS enforcement mode |
php_version | PHP runtime version (Drupal 11 requires 8.3+) |
database.version | MariaDB version |
drush_version | Drush version for Pantheon's cron/CLI operations |
build_step | Enables Integrated Composer — Pantheon runs composer install on deploy. Required. |
protected_web_paths | Paths blocked from public web access |
build_step: true and web_docroot: true are essential. Without build_step, Pantheon will not run Composer and your dependencies (including Drupal core) will be missing. Without web_docroot, Pantheon will serve from the repository root instead of web/.
Source: pantheon.upstream.yml
settings.php
The Pantheon version of settings.php is pre-configured to load Pantheon-specific settings and support local development overrides.
This file is generated by the drupal-integrations package automatically during composer install. It includes logic to load settings.pantheon.php when on Pantheon, and allows for local overrides when developing locally.
Source: web/sites/default/settings.php
.gitignore
The .gitignore is configured for the Integrated Composer workflow. Since Pantheon runs composer install on deploy, dependencies must NOT be committed.
Key rules:
/web/core/,/web/modules/contrib/,/vendor/— all built by Composer on deploy/web/sites/*/files— user uploads managed by Pantheon's filesystem!/web/sites/*/services.pantheon.*.yml— exception to allow Pantheon services YAML files
Source: example .gitignore
The drupal-integrations Package
The pantheon-systems/drupal-integrations package is the key bridge between Drupal and Pantheon. It uses Drupal's scaffold system to automatically deploy configuration files.
What it scaffolds on composer install:
| File | Target | Overwrite? |
|---|---|---|
settings.pantheon.php | web/sites/default/settings.pantheon.php | Yes (on every composer install) |
default.services.pantheon.preproduction.yml | web/sites/default/default.services.pantheon.preproduction.yml | Yes |
settings.php | web/sites/default/settings.php | No (only if missing) |
What settings.pantheon.php does (you don't write this — it's auto-generated):
- Reads database credentials from
$_SERVER['PRESSFLOW_SETTINGS'](Pantheon-injected JSON) - Sets
hash_saltfrom$_ENV['DRUPAL_HASH_SALT'] - Configures file paths (private files, temp, config sync)
- Places Twig cache in Pantheon's rolling temp directory (refreshed on each deploy)
- Registers
PantheonServiceProvider11to clear Pantheon's edge cache on Drupal cache rebuilds - Sets trusted host patterns to
.*(Pantheon handles domain routing) - Loads environment-specific services YAML (preproduction vs. production)
Version compatibility: Use ^11 for Drupal 11. The package conflicts with Drupal versions outside the 11.x range.
upstream-configuration Directory (Optional)
The upstream-configuration/ directory is used for Pantheon's custom upstream feature. It contains:
- An empty
composer.jsonwhere you can add shared dependencies - A
ComposerScripts.phpthat automatically alignsconfig.platform.phpwith your Pantheon PHP version
This is optional unless you are using a custom upstream. Use the pantheon-systems/upstream-management package to manage upstream dependencies separately from your site-specific dependencies.
The ComposerScripts.php ensures that the PHP version used for dependency resolution always matches the runtime PHP version defined in pantheon.upstream.yml, preventing incompatible packages from being installed.
Checklist
Use this checklist to verify your Drupal 11 repository is ready for Pantheon's GitHub integration:
-
composer.jsonincludespantheon-systems/drupal-integrations: ^11as a dependency -
composer.jsonhasdrupal-scaffold.allowed-packagesincludingpantheon-systems/drupal-integrations -
composer.jsonhasconfig.platform.phpmatching the PHP version inpantheon.upstream.yml -
pantheon.upstream.yml(orpantheon.yml) exists withapi_version: 1,web_docroot: true,build_step: true,php_version, anddatabase.version -
web/sites/default/settings.phpincludessettings.pantheon.phpand optionallysettings.local.php -
.gitignoreexcludesvendor/,web/core/,web/modules/contrib/,web/themes/contrib/, andweb/sites/*/files -
config/directory exists with an.htaccessdenying web access -
composer.lockis committed - Drupal core and contrib modules are NOT committed
-
web/sites/*/files/is NOT committed
More Resources
- Drupal on Pantheon - Comprehensive guide to running Drupal on Pantheon
- Using Git with Drupal - Learn Git workflows specifically for Drupal development
- Integrated Composer - Managing Drupal dependencies with Composer
- Drush on Pantheon - Command-line tools for managing Drupal sites
- pantheon.yml - Platform configuration file reference
- GitHub Application Usage - Working with pull requests and deployments