Pantheon YAML Configuration Files
Learn how to manage advanced site configuration
Hook into platform workflows and manage advanced site configuration via the
pantheon.yml file. Add it to the root of your site's codebase, and deploy it along with the rest of your code.
Set up existing scripts and write your own with help from our experts. Pantheon delivers custom workshops to help development teams master our platform and improve their internal DevOps.
Advanced Site Configuration
api_version property in order for
pantheon.yml to be valid:
Protected Web Paths
Protect files and directories inside of your docroot from public web access with
protected_web_paths. For example, the following ensures that a visitor to
https://example.com/example_directory/any_nested_file receives Access Denied (403):
protected_web_paths: - /example.txt - /example_directory
- Specify the exact path; no regex or wildcards allowed
- Paths begin with a leading
/and are relative to your docroot
- Limited to 24 protected paths
- You may not be able to protect files or paths with special characters
- Wait a few seconds for changes to take effect
Nest your docroot one level beneath your code repository in a directory named
The name of the nested directory is not configurable.
For more information, see Serving Sites from the Web Subdirectory.
Override the upstreams default PHP version with the
php_version property. PHP version is managed in version control and deployed along with the rest of your site's code to encourages a good best practice of testing before making a change on your Live site.
For example, to override the upstream default value at the site level to PHP 7:
- Upgrading PHP Versions may require you to resolve compatibility issues with your site's codebase.
- Drupal and PHP 7 require Drush 7 or greater.
- From time to time, we will roll out a new default version of PHP, which will be available to apply as One-click update in the Dashboard. If you are overriding the default, make sure to remove
pantheon.ymlas soon as possible to ensure you don't miss the latest recommended PHP version.
- You'll always be able to test new default PHP version in Dev and Test before deploying Live.
drush_version to the top level of the
pantheon.yml file to configure the Drush version used when making calls remotely on Pantheon:
For more information, see Managing Drush Versions on Pantheon.
Pantheon provides a cloud-based filesystem to store user-generated content and other website files. By default, we create a symlink to this filesystem at
/sites/default/files (Drupal) or
/wp-content/uploads (WordPress), but you can change the location with the
This creates a new symlink to the filesystem at the specified location. Note that this setting is only recommended when creating a custom upstream. Instead, consider using a symlink as described in Non-Standard Files Locations.
Complete the following before deploying
- Reconfigure Drupal 8, Drupal 7, or WordPress to use the new path
- Add path to the
- Configure a
privatesubdirectory of the new path within
- Recommended usage limited to Custom Upstream Configurations in
- Path must be relative to the site's docroot
- Specify the exact path; limited selection of valid paths:
Quicksilver Platform Integration Hooks
pantheon.yml file to define scripts you want executed automatically when a particular workflow is triggered on Pantheon by you or a teammate. For example, you can write a script to post a message to Slack whenever code is pushed to the Site Dashboard.
For more information, see Automate your Workflow with Quicksilver Platform Integration Hooks and check our growing set of Platform Integration guides demonstrating Quicksilver hooks.
Custom Upstream Configurations
pantheon.upstream.yml file to your organization's Custom Upstream to set default configurations for all downstream sites. The same properties described above can be used in this file. In addition, it is also possible to define a
deploy_product Quicksilver hook here; however other Quicksilver workflows are not supported.
This file should only be edited in the Custom Upstream repository where it is defined. Similarly, the Custom Upstream repository should not define a
pantheon.yml file; it should place all configuration settings in the upstream file instead.
When the same configuration value is defined in both files, the value from
pantheon.yml will override the value from
pantheon.upstream.yml at the site-level.
We will reject a commit that includes a
pantheon.yml error, with a message like:
remote: PANTHEON ERROR: remote: remote: Changes to `pantheon.yml` detected, but there was an error while processing it: remote: remote: remote: Version '2' is not a valid pantheon.yml version! remote: Valid versions are: 1
While our parser will reject a
pantheon.yml that is invalid, it won't necessarily give you the exact reason the file is invalid. Please refer to the examples above for exact syntax.
Deploying Configuration Changes to Multidev
Changes made to
pantheon.yml file on a branch are not detected when creating the Multidev environment for that branch. As a workaround, make some modification to
pantheon.yml file and re-commit to the Multidev environment. You will then receive a notice indicating configuration changes have been detected and applied to the Multidev environment:
remote: remote: PANTHEON NOTICE: remote: remote: Changes to `pantheon.yml` detected. remote: remote: Successfully applied `pantheon.yml` to the 'new-feature' environment. remote: remote:
Changes made to
pantheon.yml are not detected when deployed as a hotfix. As a workaround, make a modification to your
pantheon.yml file in a development environment (e.g, add a code comment), then deploy up to production using the standard Pantheon workflow.