You don't need BLT on Acquia Cloud

  • Last updated
  • 1 minute read


Learn how to remove BLT from a Drupal 10 site hosted on Acquia Cloud


Acquia BLT was created almost a decade ago as a veritable Swiss Army Knife to fill feature gaps in the Drupal ecosystem. Since then, tools such as Composer, Drush, and Drupal itself have evolved to provide similar or even better features, and for many sites BLT may be overkill.

This tutorial will help you remove BLT from a Drupal 10 application and show you how to adapt your workflow to fulfill the same use cases with other open-source tools.

    Remove core BLT packages

    1. Ensure your site is ready for the migration

      • Ensure your site is running the latest versions of all Composer packages. Especially, ensure you are using the latest release of BLT (currently 13.7.4).
      • Ensure your default.local.settings.php (in docroot/sites/default/settings) is up to date and mode 755.
      • Ensure your site is running normally in your local and cloud environments.
    2. Replace BLT settings with Drupal Recommended Settings

      Remove the blt.settings.php include from your settings.php. You can replace this with the Drupal Recommended Settings plugin.

      composer require acquia/drupal-recommended-settings:dev-develop

      Update default.local.settings.php and local.settings.php to use the Environment Detector provided by Drupal Recommended Settings instead of BLT:

      use Acquia\Drupal\RecommendedSettings\Helpers\EnvironmentDetector

    3. Remove BLT files

      Remove the BLT directory in your repo root: rm -rf blt

      Note that this does not purge all traces of BLT from your codebase. You may find references to BLT in the following files:

      • .gitignore
      • composer.json (autoload and scripts sections)

      However, we recommend you ensure your site is stable before doing any final cleanup. 

    4. Set up GrumPHP

      BLT validates any changed code when you commit changes to your project. Third-party tools such as GrumPHP can do the same thing with more features and flexibility than BLT. Run the following command and review suggested plugins for safety and trust them when prompted.

      composer require --dev phpro/grumphp php-parallel-lint/php-parallel-lint

      To mimic the existing BLT pre-commit validation, do not accept the offer to create a grumphp.yml file. Instead, use this one:

          tasks: { composer: null, phplint: null, yamllint: null }


    5. Remove BLT, add Drush

      composer remove acquia/blt
      composer require drush/drush


    6. Replace BLT commands with Composer scripts

      Replace BLT commands such as setup and validate with Composer equivalents by adding the following to the composer.json scripts section:

        "drupal:install": "drush si minimal --existing-config",
        "drupal:test": "phpunit",
        "drupal:validate": "grumphp run"

      Now instead of running blt setup, blt validate, and blt test, you can run composer drupal:install, composer drupal:validate, and composer drupal:test, respectively.

      You may need to make changes to these scripts based on your site configuration and test structure. For instance, tests may be run using Behat instead of PHPUnit, or you may need to install Drupal and import config as separate steps:

      drush si <your profile>
      drush config:set uuid <uuid>
      drush cim

      Instead of explicitly setting UUID, you could also use a Drush hook or the Config Sync without Site UUID module.

    Congratulations! You’ve removed the core of BLT from your site. Ensure that it’s still running normally locally and that you can run the new Composer commands you just defined. If so, commit your changes.

    If you run into trouble, Acquia provides the Drupal Canary Project as a reference implementation of Drupal 10 without BLT, which you can refer to for help with your own application.

    Continue reading to migrate specific additional features.

    Remove BLT from Pipelines

    BLT provides out-of-the-box Acquia Pipelines integration via acquia-pipelines.yml. Modify this file to remove references to BLT.

    1. Update acquia-pipelines.yaml

      1. Remove the BLT_DIR environment variable.
      2. Replace call to setup_env script with: mysql -u root -proot -e "CREATE DATABASE IF NOT EXISTS drupal"
      3. Replace call to validate script with: composer drupal:validate
      4. Replace call to setup-app with: composer drupal:install
      5. Replace call to tests with: composer drupal:test
      6. Replace artifact build step with the following:
      - mkdir /tmp/acli-push-artifact
      - acli push:artifact --dry-run --no-clone --no-commit
      - mv .git /tmp/acli-push-artifact/
      - shopt -s dotglob && rm -rf ./* && mv /tmp/acli-push-artifact/* ./


    2. Verify changes

      Commit and push these changes to your repository. Verify that Pipelines builds, tests, and deploys your site as expected.

    Remove BLT from Code Studio

    No specific work is required to support Code Studio. If Code Studio AutoDevops builds were passing prior to the migration, they should continue working as before.

    Remove/replace Cloud Hooks

    If your application is hosted on Acquia Cloud Next, consider using Cloud Actions on Acquia Cloud Next as an out-of-the-box replacement for Cloud Hooks. In this case, simply enable Cloud Actions and remove Cloud Hooks from your application:

    rm -rf hooks

    Applications still on Acquia Cloud Classic will need to replace BLT's Cloud Hooks with individual Drush commands to replicate the functionality of BLT. To do this, remove all of the shell scripts from the hooks directory in your application. Instead, create a script such as the following at hooks/common/

    set -ev
    drush updb
    drush config:set uuid 7139fc96-2b92-48c5-8e8a-cb79472aa19f
    drush cim
    drush cr
    set +v

    Then run the following commands to link this common script into each hook event directory:

    ln -s ../ hooks/common/post-code-deploy/
    ln -s ../ hooks/common/post-code-update/
    ln -s ../ hooks/common/post-db-copy/


    Remove/replace other BLT integrations

    The following features have their own migration path:

    • ACSF and Multisite – The Drupal Recommended Settings plugin facilitates the settings capabilities of BLT for multisite.
    • SAML – Acquia largely recommends utilizing the SAML Auth module today. Most of our prior work around the “dedicated” SAML capabilities in BLT (and later the BLT SAML Plugin) were related to the complexities surrounding the SimpleSAMLPHPAuth module and PHP library. SAML Auth is much simpler to setup and configure (entirely via Drupal configuration).
    • BLT plugins (such as Behat tests) – We recommend exploring composer-based automation for commands contained in BLT plugins (e.g. composer test that will execute the necessary commands for tasks such as automated testing).
    • Twig linting – GrumPHP Can also be configured to lint Twig