Next steps with BLT | BLT | Acquia Product Documentation

Note

Acquia will end support for BLT on December 31, 2024. For more information on how to replace your BLT implementation with updated functionality, see You don’t need BLT on Acquia Cloud.

After your new project works locally, review the 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).

If you use Code Studio, BLT requires no additional configuration or initialization unless you plan to build a custom build process.

You can initialize Acquia Pipelines as follows:
```
blt recipes:ci:pipelines: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:
```
git:
  remotes:
      - [email protected]:bolt8.git
```
Create and deploy an artifact.
```
blt artifact:deploy
```

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 BLT.
`composer require drupal/ctools:^9.8.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 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. 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.

Important

When using 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 BLT’s settings management is the blt.settings.php file. When websites are created, BLT adds a require line to the standard settings.php file, which includes the blt.settings.php file from 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 BLT appears similar to the following:

sites/{site-name}/settings.php
 |
 ---- 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

Important

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, 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, BLT initially deploys a default.global.settings.php 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, 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, 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.