Despite having a big warning at the bottom of the docroot/sites/default/settings.php file telling you not to add additional settings to that file. The BLT documentation does little do say what the recommended way of conditionally including *.settings.php files depending on environment variables or some other decider.

Normally, you would do it by adding code to the effect of the below to docroot/sites/default/settings.php but since there is such a direct warning not to in the BLT version, I needed to find a better way:

if (getenv('RUNNING_IN_DOCKSAL') == 'yes') {
  include $app_root . '/' . $site_path . '/settings.docksal.php';
}

if (getenv('RUNNING_IN_QA') == 'yes') {
  include $app_root . '/' . $site_path . '/settings.qa.php';
}

There is a file called docroot/sites/default/settings/includes.settings.php which looks like it could be hopeful, however it’s clearly not initially setup or intended for this purpose. It has a list of settings files to include:

$additionalSettingsFiles = [
  // e.g,( DRUPAL_ROOT . "/sites/$site_dir/settings/foo.settings.php" )
];

and then a loop to include any in the array:

foreach ($additionalSettingsFiles as $settingsFile) {
  if (file_exists($settingsFile)) {
    require $settingsFile;
  }
}

In order to include custom settings files per environment, I ended up adding a few lines between those blocks of code to dynamically add entries to that array depending on the environment.

// Load local docksal settings to override database connection details.
if (getenv('RUNNING_IN_DOCKSAL') == 'yes') {
  $additionalSettingsFiles[] = DRUPAL_ROOT . "/sites/$site_dir/settings/settings.docksal.php";
}

// Load QA specific settings.
if (getenv('RUNNING_IN_QA') == 'yes') {
  $additionalSettingsFiles[] = DRUPAL_ROOT . "/sites/$site_dir/settings/settings.qa.php";
}

However, I wasn’t entirely sure whether this was the best way or not, so I asked someone at Acquia what they thought. He said:

You could extend the logic as described to include an environment specific configuration file if you had lots of settings for each environment and wanted to store them in separate files - as long as the files aren’t picked up by BLT scan for settings.

Which pretty much confirms this is the most-correct way of including environment-specific settings files with BLT. The comment “as long as the files aren’t picked up by BLT scan for settings” is worth bearing in mind. This is referring to a piece of text in the Acquia Documentation “Acquia BLT globs the docroot/sites/settings directory to find all files matching a *.settings.php format”. This, of course, means that if you’re not careful with the naming of the files you may end up with them being included at all times, which isn’t what you want.

For this reason, I have made sure to name my files settings.<environment>.php which keeps them safe from that blob. You could also place the settings files in docroot/sites/default instead of docroot/sites/default/settings which would keep them out of harms way too.