Next steps with Acquia BLT

After your new project works locally, review the Acquia BLT documentation by role to learn how to perform common project tasks and integrate with third party tools.

Here are tasks that are typically performed at this stage:

  • Initialize continuous integration (CI). You can use one of the following commands, based on your CI tooling:

    • blt recipes:ci:pipelines:init
    • blt recipes:ci:travis:init
  • Push to your upstream repository using the following Git commands:

    git add -A
    git commit -m 'My new project is great.'
    git remote add origin [something]
    git push origin
  • Ensure that you have entered a value for git.remotes in the blt/blt.yml file:

          - [email protected]:bolt8.git
  • Create and deploy an artifact.

    blt artifact:deploy

Acquia BLT includes additional commonly used commands, as follows:

Command Description
blt List targets.
blt validate Validate code using commands that include phpcs, php lint, and composer validate.
blt tests:phpunit:run Run phpunit tests.
blt tests:behat:run SSH into a virtual machine and run Behat tests.
blt doctor Diagnose issues with Acquia BLT.
composer require drupal/ctools:^8.3.0 Download and require a new project.
blt artifact:build Build a deployment artifact.
blt artifact:deploy Build an artifact and deploy it to git.remotes.
composer update acquia/blt --with-dependencies Update Acquia BLT.

Adding settings to settings.php

A common practice in Drupal is to add settings to the settings.php file to control things like cache backends, set site variables, or other tasks which do need a specific module. Acquia BLT provides two mechanisms to add settings to your settings.php file:

  • Settings files can be added to the docroot/sites directory for inclusion in all websites in the codebase.
  • Settings can be added using an includes.settings.php in the settings directory of an individual website (such as docroot/sites/{site-name}/settings/includes.settings.php).

Both mechanisms allow settings to be overridden by local.settings.php, to support local development.


When using Acquia BLT, do not add settings directly to settings.php. This is also the case with Site Factory, which will ignore settings directly added to settings.php.

The first level of Acquia BLT’s settings management is the blt.settings.php file. When websites are created, Acquia BLT adds a require line to the standard settings.php file, which includes the blt.settings.php file from Acquia BLT’s location in the vendor directory. This file then controls the inclusion of other settings files in a hierarchy. The full hierarchy of settings files used by Acquia BLT appears similar to the following:

 ---- blt.settings.php
        ---- sites/settings/*.settings.php
        ---- sites/{site-name}/settings/includes.settings.php
        |       |
        |       ---- foo.settings.php
        |       ---- bar.settings.php
        |       ---- ....
        ---- sites/{site-name}/settings/local.settings.php


Do not edit the blt.settings.php file in the vendor directory. If you do, the next time composer update or install runs, your changes may be lost. Instead, use one of the following mechanisms:

  • Global settings for the codebase

    To allow settings to be made once and applied to all sites in a codebase, Acquia BLT globs the docroot/sites/settings directory to find all files matching a *.settings.php format, and then adds them using PHP require statements.

    As not all projects will need additional global settings, Acquia BLT initially deploys a file into the docroot/sites/settings directory. To make use of this file, rename the file to global.settings.php, and then add settings or required files as needed.

  • Per website

    On a per-website basis, Acquia BLT uses an includes.settings.php file in the settings directory of each individual website. Any settings made in that file, or other files required into it, will be added to the settings for that particular website only.

    As not all projects require additional includes, Acquia BLT initially deploys a default.includes.settings.php file into the website’s docroot/sites/{site_name}/settings directory. To make use of this file, rename it to includes.settings.php, and then add the path to the file or files to be added.