Pantheon YAML Configuration Files
Learn how to manage advanced site configuration
Discuss in our Forum Discuss in SlackHook 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.
Quicksilver Cloud Hooks Training
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 WebOps.
For reference implementations see example.pantheon.yml and Quicksilver Example Scripts.
Advanced Site Configuration
Include api_version
Define the api_version
property in order for pantheon.yml
to be valid:
api_version: 1
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.txt
or https://example.com/example_directory/any_nested_file
receives Access Denied (403):
protected_web_paths:
- /example.txt
- /example_directory
The pantheon.upstream.yml
file provided by your upstream might define protected web paths. If it does, all of the paths listed in the upstream and all of the paths listed in your pantheon.yml
file will be protected. If you wish to remove protection from any path listed in the upstream, set the protected_web_paths_override property.
Considerations
- Specify the exact path; path is case-sensitive
- 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
Protected Web Paths Override
To disable all of the protected web paths defined by your site's upstream and all protected paths defined by the Pantheon platform, set the protected_web_paths_override
property to true
:
protected_web_paths_override: true
Considerations
The standard protected web paths can be important to the security of your site. If you override protection with this property, be sure to copy all of the standard protected web paths into your pantheon.yml
file, and only remove those that you are certain are safe to expose.
For a list of standard protected paths, see the pantheon.upstream.yml
for:
Enforce HTTPS + HSTS
HTTPS adds a layer of encryption that prevents others from snooping on or tampering with traffic to your site. HTTP Strict Transport Security (HSTS) instructs browsers to only connect via HTTPS and helps protect websites against protocol downgrade attacks and cookie hijacking.
Pantheon sites (using the default Pantheon upstreams) created or updated on or after September 30 2019 default to enforcing HTTPS via a redirect and a short, 5-minute duration, HSTS header. You can override the default with the enforce_https
directive in a site-specific pantheon.yml
file.
Note
Before adjusting enforce_https
, review and understand the configuration options and all considerations to avoid unintended consequences.
If you use a plugin or module to set your HSTS header, it will create a duplicate header. Disable enforce_https
in pantheon.yml
to avoid an invalid policy.
Use of the HSTS header is defined by the enforce_https
directive, and takes five possible values which are handled by Pantheon as shown below:
enforce_https: | Redirect | HSTS | Strict-Transport-Security | includeSubdomains | preload |
---|---|---|---|---|---|
off | ❌ | Disabled | Not set by Pantheon | ❌ | ❌ |
transitional (default) | ✔ | Enforced | max-age=300 | ❌ | ❌ |
transitional+subdomains | ✔ | Enforced | max-age=300 | ✔ | ❌ |
full | ✔ | Enforced | max-age=31622400 | ❌ | ❌ |
full+subdomains | ✔ | Enforced | max-age=31622400 | ✔ | ✔ |
For example, to set enforce_https
as off
:
enforce_https: off
Considerations
- Use of
full
orfull+subdomains
should be treated as a commitment. HSTS headers are cached by browsers for the duration of the max-age period. If your site is unable to serve HTTPS (e.g. by moving to a host that doesn't support HTTPS), visitors will be unable to access your site. - Any option with
+subdomains
should only be used if you want to enforce HTTPS for all subdomains, even those not connected to Pantheon. - To prepare your site to serve all content via HTTPS, follow the Switching Sites from HTTP to HTTPS doc.
Test Your Site's HSTS Configuration for an A+ Rating
SSL Labs provides a free, online service that you can use to test your Site's configuration. In order to obtain an A+ rating, a long-duration HSTS header using the full
or full+subdomains
value is required.
To test your configuration, select a short-duration HSTS header (
transitional
ortransitional+subdomains
), before committing to the long-duration HSTS header.When you're comfortable that HSTS works as expected in the Live environment, send the long-duration HSTS header by moving to
full
orfull+subdomains
.
Nested Docroot
Nest your docroot one level beneath your code repository in a directory named web
:
web_docroot: true
The name of the nested directory is not configurable.
For more information, see Serving Sites from the Web Subdirectory.
PHP Version
Override the upstream's 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 encourage testing before making a change on your Live site.
For example, to override the upstream default value at the site level to PHP 7:
php_version: 7.0
Considerations
- 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
php_version
frompantheon.yml
as 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
Add drush_version
to the top level of the pantheon.yml
file to configure the Drush version used when making calls remotely on Pantheon:
drush_version: 8
For more information and compatibility requirements, see Managing Drush Versions on Pantheon.
Filemount Path
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 filemount
variable.
Warning
We recommend only changing this setting when needed for Custom Upstream Configurations in pantheon.upstream.yml
. For most cases, you can create an additional symlink in your code base.
The only valid filemount path other than the default path for each CMS is /files
relative to your docroot:
filemount: /files
Complete the following before deploying filemount
(required):
Reconfigure Drupal 8, Drupal 7, or WordPress to use the new path
Add path to the
.gitignore
fileConfigure a
private
subdirectory of the new path withinprotected_web_paths
Quicksilver Platform Integration Hooks
Use the 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
Add a 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.
Troubleshooting
"Changes to pantheon.yml detected, but there was an error while processing it"
The Platform will automatically reject a commit that includes a pantheon.yml
error. The error message will resemble:
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, or try running the contents of your pantheon.yml
file through a YAML linter.
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:
Deploying Hotfixes
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.