Download the PHP package lullabot/drainpipe without Composer

Drainpipe

Drainpipe is a composer package which provides build tool and testing helpers for a Drupal site, including:

• Site and database updates
• Artifact packaging for deployment to a hosting provider
• Automated testing setup
• Integration with DDEV
• CI integration

Installation

and if using DDEV, restart to enable the added features:

Taskfile

Drainpipe will scaffold out various files, most importantly a Taskfile.yml in the root of your repository. Task is a task runner / build tool that aims to be simpler and easier to use than, for example, GNU Make. Since it's written in Go, Task is just a single binary and has no other dependencies. It's also cross-platform with everything running through the same shell interpreter.

Drainpipe installs the Task binary for you, no matter if you are using DDEV or not. If you already have Task installed system-wide and are not using DDEV, your installed binary will be linked from the vendor/bin directory.

You can see which tasks are available after installation by running ./vendor/bin/task --list or ddev task --list if you're running DDEV. To get more information on a specific task e.g. what parameters it takes, you can run task [task name] --summary.

Your Taskfile.yml can be validated with JSON Schema:

See .github/workflows/ValidateTaskfile.yml for an example of this in use.

Overriding files provided by drainpipe

Drupal scaffolds are core files automatically placed and updated in the project root by drupal/core-composer-scaffold (documentation).

Scaffold files provided by Drainpipe are located in the main scaffold directory.

To determine where a file is placed, edit the extra.drupal-scaffold section in composer.json. Check how each scaffolded file is defined in /src/ScaffoldInstallerPlugin.php.

A specific file scaffolding can be disabled by mapping it to false under the extra.drupal-scaffold.file-mapping in the project composer.json file. This prevents it from being created or overriden when running composer install or composer update. Note Drainpipe workflows cannot be overridden.

Binaries

If you receive an error such as exec format error: ./vendor/bin/task, then you may have the wrong binary for your architecture. If your architecture wasn't detected correctly, please open an issue with the output of php -r "echo php_uname('m');", along with information on your hardware and operating system.

You can override the platform and processor with environment variables DRAINPIPE_PLATFORM and DRAINPIPE_PROCESSOR. Valid platform values are linux, darwin, or windows, and processors are 386, amd64, or arm64. These correspond to builds of upstream dependencies e.g. https://github.com/go-task/task/releases

Tugboat

The Tugboat configuration file is not a static file; it is dynamically generated based on your .ddev/config.yaml file. To see the implementation details, check /src/TugboatConfigPlugin.php.

Node JS

All Drainpipe components (DDEV, Github Actions, Tugboat) are configured to use the same Node JS major version. This is set in the .nvmrc file, which is scaffolded from the Drainpipe's root directory, but can be overriden to use a different Node version.

Renovate Presets

If you are using Renovate (for automated dependency updates) you can use/extend our Drupal presets by doing the following:

This preset provides safe automation with flexibility and control for teams maintaining Drupal applications, minimizing risk by requiring approval for major changes while accelerating security patches through the automerging of minor updates.

Database Updates

The drupal:update command runs drush deploy directly, per the Lullabot ADR on Drupal build steps.

Sites that need to customize the deploy steps (e.g. running config:import twice, or running drush cron after deploy) should replace the drush deploy command using a site-level Drush command file. See the ADR for a full example.

.env support

Drainpipe will add .env file support for managing environment variables.

This is only used for locals - other environments such as CI and production should use their native environment variable mechanisms.

This consists of:

• Creation of a .env and .env.defaults file
• Default Taskfile.yml contains dotenv support note: real environment variables will override these

• Drupal integration via vlucas/phpdotenv To enable this, add the following to your composer.json:

  You will need to restart DDEV if you make any changes to .env or.env.defaults

SASS Compilation

This compiles CSS assets using Sass. It also supports the following:

• Globbing

• Modern Normalizer
• Autoprefixer configured through a .browserslistrc file in the project root

Setup

• Add @lullabot/drainpipe-sass to your project yarn add @lullabot/drainpipe-sass or npm install @lullabot/drainpipe-sass

• Edit Taskfile.yml and add DRAINPIPE_SASS in the vars section

• Run task sass:compile to check it works as expected
• Run task sass:watch to check file watching works as expected
• Add the task to a task that compiles all your assets e.g.

JavaScript Compilation

JavaScript bundling support is via esbuild.

Setup

• Add @lullabot/drainpipe-javascript to your project yarn add @lullabot/drainpipe-javascript or npm install @lullabot/drainpipe-javascript

• Edit Taskfile.yml and add DRAINPIPE_JAVASCRIPT in the vars section

  Source and target need to have the same basedir (web or docroot) due to being unable to provide separate entryNames. See https://github.com/evanw/esbuild/issues/224

• Run task javascript:compile to check it works as expected
• Run task javascript:watch to check file watching works as expected
• Add the task to a task that compiles all your assets e.g.

Testing

This is provided by the separate drainpipe-dev package (so the development/testing dependencies aren't installed in production builds).

Static Tests

All the below static code analysis tests can be run with task test:static

PHPStan Baseline for Existing Codebases

Projects with pre-existing violations can generate a baseline file to suppress them, so CI only fails on new code:

This creates phpstan-baseline.neon (the suppressed violations) and phpstan.neon (which includes both phpstan.neon.dist and the baseline). Commit both files. The baseline can be regenerated at any time as legacy violations are resolved.

Altering PHP_CodeSniffer Configuration

• Create phpcs.xml to override the phpcs.xml.dist file with overrides being done in:

• Edit phpcs.xml in the root of your project, e.g. to add an exclude pattern:

Ignoring Files in the Untracked Files Check

task test:static includes a check for untracked or modified files in the working tree. If your project intentionally leaves certain files uncommitted (e.g. a local config file that must not be in version control), you can exclude them from this check via composer.json:

The .ddev directory is always excluded automatically.

Functional Tests

Functional tests require some mechanism of creating a functing Drupal site to test against. All the below tests can be run with task test:functional

PHPUnit

task test:phpunit:functional

Runs PHPUnit tests in:

• web/modules/custom/**/tests/src/Kernel
• test/phpunit/**/Kernel
• web/modules/custom/**/tests/src/Functional
• test/phpunit/**/Functional
• web/modules/custom/**/tests/src/FunctionalJavaScript
• test/phpunit/**/FunctionalJavaScript

You will need to make sure you have a working Drupal site before you're able to run these.

Autofix

task test:autofix attempts to autofix any issues discovered by tests. Currently, this is just fixing PHPCS errors with PHPCBF.

Hosting Provider Integration

Generic

Generic helpers for deployments can be found in tasks/snapshot.yml, tasks/drupal.yml

Importing/Exporting Databases

Databases are by default fetched to /var/www/html/files/db/db.sql.gz, this can be overridden with a variable in Task:

Snapshots

When creating a snapshot of the current working directly files can be excluded using a .drainpipeignore file in the root of the repository that uses the same format as .gitignore, e.g.

This folder can then be deployed to a remote service either as an archive, or pushed to a git remote with task deploy:git.

Pantheon

Pantheon specific tasks are contained in tasks/pantheon.yml. When any Pantheon CI configuration is present in composer.json, Drainpipe automatically adds the following to your Taskfile.yml's includes section. You can also add it manually:

See below for CI specific integrations for hosting providers.

When using Pantheon with Drainpipe, the Pantheon site should be configured to override some of Pantheon's default behaviors. Because Drainpipe installs composer dependencies, Pantheon's Integrated Composer should be disabled. Add build_step: false to your pantheon.yml file:

Additionally, Pantheon sites start with "Autopilot", which provides updates from the Drupal upstream. Usually this feature conflicts with an external Git repository such as GitHub or GitLab. It is recommended to disable this by setting an empty upstream with terminus.

Pantheon Systems: Drupal Integrations

pantheon-systems/drupal-integrations is a package that provides essential Pantheon functionality. It is strongly recommended to install it.

Acquia

Acquia specific tasks are contained in tasks/acquia.yml. Add the following to your Taskfile.yml's includes section to use them:

⚠️ Beta Notice: The Acquia integration is currently in beta. While we strive to maintain stability, you may encounter unexpected issues. Please report any problems you encounter through our issue tracker.

To enable auto configuration of Acquia Cloud settings:

GitHub Actions Integration

Add the following to composer.json for generic GitHub Actions that will be copied to .github/actions/drainpipe in your project:

They are composite actions which can be used in any of your workflows e.g.

Tests can be run locally with act:

Tests

Workflows for running static and functional tests can be added with the following configuration:

The build process for the functional tests will use task build:ci:functional, falling back to task build:dev, and then task build. The static tests should not require a build step.

These workflow files will continue to be managed by Drainpipe and cannot be overridden. If you wish to do so then it's recommended you maintain your own workflows for testing.

Security

Runs security checks for composer packages and Drupal contrib, as well as posting a diff of composer.lock as a review comment.

Security checks rely on composer audit. This means test:security task will exit with error if your dependencies have known vulnerabilities. Sometimes, this is not desirable: think of a component which is required by Drupal core - you can not upgrade it directly, because it is pinned to a specific version by Drupal in the first place. To prevent these kind of situations from failing the security check, you can configure composer audit to ignore specific vulnerabilities when scanning your dependencies. To do so, the simplest way is to modify your composer.json file to add a list of vulnerabilities that should not trigger an error when running test:security:

For more details about how to configure the ignore feature for composer audit, check the Composer docs.

The Security workflow also includes a Zizmor static analysis job (ZizmorAnalysis) that scans your GitHub Actions workflow files for security issues. Zizmor results are uploaded to GitHub's code scanning dashboard, which requires Code Security to be enabled for your repository. If it is not enabled, the ZizmorAnalysis job will fail with: "Code Security must be enabled for this repository to use code scanning."

The Security workflow also includes a Gitleaks job (Gitleaks) that scans every PR and push to the default branch for accidentally committed secrets — API keys, tokens, credentials, and similar sensitive values. Findings are uploaded to GitHub's code scanning dashboard under the Gitleaks category.

Suppressing false positives: Drainpipe scaffolds a .gitleaks.toml at the project root that pre-configures allowlists for patterns common in Drupal projects (contributed modules, Drupal core, GitHub Actions template expressions, and placeholder values). Add [[allowlists]] blocks to that file to suppress additional false positives specific to your project. Use [extend] with useDefault = true to inherit all default rules and layer your allowlists on top:

Recommended: one-time full history scan: When first adopting Gitleaks, run a scan of your full git history to check for secrets that may already be committed:

Review gitleaks-history.json and for each finding: rotate any credentials that are still valid; for false positives, add the pattern to .gitleaks.toml. Note that rewriting git history to remove secrets is disruptive — rotating the credential is the most effective remediation.

NPM & Yarn Lockfile Diff

Post a sticky comment in the Pull Request with a markdown table of any changes detected in yarn.lock or package-lock.json files.

Pantheon

To scaffold Pantheon composite actions for use in your own workflows (without a managed review app workflow), add "Actions":

This scaffolds .github/actions/drainpipe/pantheon/ (setup-terminus, push, clone-env, update, review) along with pantheon.yml and .drainpipeignore, without installing any workflow file. Use this when you manage your own deployment workflow and want Drainpipe's composite actions as building blocks.

To enable deployment of Pantheon Review Apps (Multidev environments per pull request):

• Add the following to composer.json:

  ReviewApps implicitly includes Actions — you do not need to list both.

• Run composer install to install the workflow to .github/workflows
• Create a build multidev label in your GitHub repository. The workflow triggers when this label is added to a pull request, and re-runs on subsequent commits while the label is present.
  • If you want the multidev build to run on every pull request automatically, add the build multidev label to your pull request template.
• Add the following variables to your GitHub repository:
  • PANTHEON_SITE_NAME The canonical site name in Pantheon
  • TERMINUS_PLUGINS (optional) Comma-separated list of Terminus plugins to be available
  • TERMINUS_TIMEOUT_LIMIT (optional) Number of seconds that terminus will wait until timeout. Defaults to 600
  • PANTHEON_CLONE_FROM (optional) The environment to clone from when creating multidev sites. Defaults to 'live'
  • PANTHEON_SKIP_WIPE_MULTIDEV (optional) Set to 'true' to skip wiping and re-cloning the multidev's database and files on each push. When the multidev does not yet exist it is still created with a full content clone from the source environment; only subsequent pushes skip the clone. Defaults to 'false' (always wipe and re-clone). See Multidev content cloning performance.
• Add the following secrets to your GitHub repository:
  • TERMINUS_MACHINE_TOKEN See https://pantheon.io/docs/terminus/install#machine-token
  • SSH_PRIVATE_KEY A private key of a user which can push to Pantheon
  • SSH_KNOWN_HOSTS The result of running ssh-keyscan -H -p 2222 codeserver.dev.$PANTHEON_SITE_ID.drush.in
  • PANTHEON_REVIEW_USERNAME (optional) A username for HTTP basic auth
  • PANTHEON_REVIEW_PASSWORD (optional) The password to lock the site with
  • PANTHEON_REVIEW_RUN_INSTALLER (optional) Set to "true" to run site:install --existing-config instead of drupal:update when deploying

The deploy steps delegate to task pantheon:prepare-multidev, task pantheon:drupal-update, and task pantheon:lock-env in tasks/pantheon.yml — customize behavior there.

Async deploy with Quicksilver

By default, the review app job blocks the CI runner for up to 10 minutes while it waits for Pantheon to finish syncing code (terminus workflow:wait). The AsyncDeploy option eliminates this wait by splitting the job in two:

• Job 1 (Push): builds the project, creates the multidev, pushes code to Pantheon, then exits immediately. The CI runner is released within a few minutes. The GitHub Deployment remains in_progress.
• Pantheon syncs code internally and fires the sync_code Quicksilver hook.
• Quicksilver script (PHP running on Pantheon): detects the pr-NNN multidev pattern, reads secrets from Pantheon Secrets, and fires a repository_dispatch event to GitHub.
• Job 2 (Post-deploy): triggered by the webhook — runs terminus aliases, drush update (or task update), and marks the GitHub Deployment as success.

Enabling async deploy

Add "AsyncDeploy" alongside "ReviewApps" in your composer.json:

Then run composer install. The following files are scaffolded or replaced:

• .github/workflows/PantheonReviewApps.yml — replaced with the async variant (exits after git push)
• .github/workflows/PantheonReviewAppsPostDeploy.yml — new post-deploy workflow triggered by Quicksilver
• web/private/scripts/drainpipe_notify_github.php — Quicksilver script that fires the webhook

DDEV vs. bare runner: Drainpipe automatically selects the right workflow variant. If .ddev/config.yaml is present in your project, the DDEV-based workflow is scaffolded and the build runs inside DDEV as usual. If DDEV is not configured, the bare-runner variant is used instead — in this case your task build target must be executable on a standard ubuntu-24.04 runner without any system dependencies provided by DDEV (e.g. specific PHP extensions, Node versions, or services).

Manual step: add the Quicksilver hook to pantheon.yml

Drainpipe does not auto-edit pantheon.yml because it is version-controlled and site-specific. Add the following to your site's pantheon.yml:

Important: the path is private/scripts/ — not web/private/scripts/. Pantheon resolves this path relative to the web root when web_docroot: true is set. Using the web/ prefix is a common misconfiguration that silently prevents the hook from running.

Set Pantheon secrets (once per site)

The Quicksilver script reads credentials from Pantheon Secrets at runtime using pantheon_get_secret(). Set them with Terminus before the first deployment:

Note: GITHUB_TOKEN (the automatic Actions token) cannot be used here because Quicksilver runs outside GitHub's infrastructure. You must create a personal access token with repo scope.

Note: terminus secret:set requires the terminus-secrets-manager-plugin to be installed wherever Terminus runs (CI runner or local workstation). You can make it available in CI by adding it to the TERMINUS_PLUGINS repository variable.

GitHub checks behaviour

This is an important difference from the default blocking mode:

In async mode, a failure in Job 2 (e.g. drush update fails) will not block a merge even if the review app check is set as required in branch protection. Monitor the Deployments panel on the PR to confirm Job 2 succeeds before merging.

Monitoring and troubleshooting

The async pipeline has six observable states. The table below explains each and where to find logs.

log_url on every status: each deployment status update now carries a log_url pointing directly to the CI run that created it. The "View deployment" link in the PR Deployments panel always takes you to the relevant logs.

Job 1 step summary: when Job 1 exits in async mode it writes a summary to the Actions job page with a direct link to the Pantheon dashboard workflow logs and the terminus workflow:list command for local diagnosis.

Watchdog

The scaffolded PantheonReviewAppsWatchdog.yml workflow runs every 30 minutes and automatically resolves deployments stuck in in_progress. When a deployment has been in_progress longer than the threshold, the watchdog:

1. Queries Terminus for the most recent Pantheon workflow status on that multidev
2. If the sync failed → marks the deployment error and describes the failure
3. If the sync succeeded but Job 2 never ran → marks error and points to the Quicksilver/dispatch path as the likely failure point
4. If the sync is still running → leaves the deployment alone (not stale yet)

The threshold defaults to 20 minutes and can be overridden with a repository variable:

You can also trigger the watchdog manually via workflow_dispatch with a custom threshold_minutes input.

Concurrency

If a developer pushes twice in quick succession, a second Quicksilver event fires while Job 2 is still running. The cancel-in-progress: true concurrency group on the post-deploy workflow cancels the older Job 2 automatically — only the latest sync triggers a Drush update.

Acquia

To add Acquia specific GitHub actions, add the following to composer.json:

Then run composer install. A Deploy to Acquia workflow at .github/workflows/AcquiaDeploy.yml will be added (with its dependent actions).

After the Github Actions Integration is merged, you can deploy to Acquia using the UI or the Github CLI (gh).

Github repository settings

In your Github repository settings you need to create the following:

• Repository Variables
  • To identify the project we are deploying (same value of the AH_SITE_GROUP environment value)
  • ACQUIA_SITE_GROUP
• Repository Secrets
  • To use Acquia CLI (acli) to interact with Acquia's Cloud Platform
  • ACQUIA_API_KEY
  • ACQUIA_API_SECRET
  • To push code to your Acquia repository
  • ACQUIA_SSH_PRIVATE_KEY

Task settings

When a deployment is made, you must run your own code before and after the deployment. To do so, define your in your /Taskfile.yml the following:

• acquia:deploy:before

• acquia:deploy:after

  Runs after the code is switched on the Acquia environment and before drupal:update is called automatically by Drainpipe. Use this for any steps that must happen between the code switch and the Drupal update, such as enabling maintenance mode or syncing files from another environment.

GitLab CI Integration

Add the following to composer.json for GitLab helpers:

This will import scaffold/gitlab/Common.gitlab-ci.yml, which provides helpers that can be used in GitLab CI with includes and references, or scaffold/gitlab/DDEV.gitlab-ci.yml if you are using DDEV.

Available variables are:

Security

Runs composer audit and posts a composer lock diff as a merge request comment. Requires GITLAB_ACCESS_TOKEN variable to be set with api scope.

Pantheon

To enable deployment of Pantheon Review Apps (Multidev environments per merge request):

• Add the following to composer.json:

  Use "Deploy" alone if you only want the Terminus setup helpers without the full review app pipeline. Use both "Deploy" and "ReviewApps" for full Multidev support.

• Run composer install to install the CI files to .drainpipe/gitlab/. If no .gitlab-ci.yml exists, an example one will be created for you.
• Add the following variables to your GitLab repository:
  • PANTHEON_SITE_NAME The canonical site name in Pantheon
  • PANTHEON_SITE_ID The Pantheon site UUID, used to construct the SSH remote URL
  • PANTHEON_GIT_REMOTE The Pantheon git remote URL e.g. ssh://[email protected].$PANTHEON_SITE_ID.drush.in:2222/~/repository.git
  • TERMINUS_MACHINE_TOKEN See https://pantheon.io/docs/terminus/install#machine-token (enable the Mask variable checkbox)
  • SSH_PRIVATE_KEY A private key of a user which can push to Pantheon (enable the Mask variable checkbox)
  • SSH_KNOWN_HOSTS The result of running ssh-keyscan -H -p 2222 codeserver.dev.$PANTHEON_SITE_ID.drush.in (enable the Mask variable checkbox)
  • GIT_EMAIL Email address to use for git commits
  • GIT_USERNAME Username to use for git commits
  • GITLAB_ACCESS_TOKEN A GitLab access token with api scope, used by the scheduled multidev cleanup job
  • TERMINUS_PLUGINS (optional) Comma-separated list of Terminus plugins to be available
  • TERMINUS_TIMEOUT_LIMIT (optional) Number of seconds that terminus will wait until timeout. Defaults to 600
  • PANTHEON_CLONE_FROM (optional) The environment to clone from when creating multidev sites. Defaults to dev
  • REVIEW_APP_BASIC_AUTH (optional) Basic auth credentials prepended to the review app URL e.g. user:password@
  • PANTHEON_REVIEW_USERNAME (optional) A username for HTTP basic auth. When set alongside PANTHEON_REVIEW_PASSWORD, the multidev is locked with terminus lock:enable after deployment
  • PANTHEON_REVIEW_PASSWORD (optional) The password to lock the site with
  • PANTHEON_MULTIDEV_RUN_INSTALLER (optional) Set to "true" to run site:install --existing-config instead of drupal:update when deploying
  • PANTHEON_SKIP_WIPE_MULTIDEV (optional) Set to "true" to skip wiping the multidev's database and files on each push, preserving its state. When the multidev does not yet exist it is still created with a full content clone from the source environment; only subsequent pushes skip the clone. Defaults to "false" (always wipe and re-clone). See Multidev content cloning performance.

This will setup Merge Request deployment to Pantheon Multidev environments. See [scaffold/gitlab/gitlab-ci.example.yml] for an example. You can also just include "Deploy" which will give you helpers that you can include and reference for tasks such as setting up Terminus. See scaffold/gitlab/Pantheon.gitlab-ci.yml.

The deploy steps delegate to task pantheon:prepare-multidev, task pantheon:drupal-update, and task pantheon:lock-env in tasks/pantheon.yml — customize behavior there.

Bitbucket Pipelines Integration

Add the following to composer.json to enable Bitbucket Pipelines support:

PHP extensions

The pipeline image (php:8.5-cli) includes only a minimal set of PHP extensions. Before running composer install, setup-php.sh automatically detects missing extensions by running composer check-platform-reqs against composer.lock and installs them via mlocati/docker-php-extension-installer.

To ensure an extension is installed, declare it in the require block of your project's composer.json:

To identify which extensions your project needs, run:

For extensions that cannot be declared in composer.json (e.g. proprietary agents such as New Relic or Tideways), set the DRAINPIPE_PHP_EXTENSIONS Bitbucket repository variable to a space-separated list of extension names:

Acquia Deploy

Acquia Deploy triggers a deployment to the Acquia dev environment whenever a PR is merged to main, equivalent to the GitHub Actions AcquiaDeploy workflow.

To enable Acquia Deploy on Bitbucket:

• Add the following to composer.json:

  If your main branch is named master (or anything other than main), set bitbucketDeployBranch:

  If you are using both Acquia Review Apps and Acquia Deploy, list them together:

• Run composer install to scaffold the following files into your project:
  • bitbucket-pipelines.yml — generated at the repository root and kept up to date on every composer install. Do not edit this file manually — changes will be overwritten.
  • Taskfile.yml — a bitbucket include pointing to vendor/lullabot/drainpipe/tasks/bitbucket.yml is auto-injected

How it works

When a PR is merged to main the branches.main pipeline:

1. Installs system dependencies and configures SSH
2. Runs composer install
3. Installs Acquia CLI and authenticates (task bitbucket:acquia:setup)
4. Runs the pre-deploy build hook if defined (task bitbucket:acquia:build → task acquia:deploy:before)
5. Resolves the VCS branch and remote that the Acquia dev environment tracks, pushes code via task deploy:git, and waits for the code switch to complete (task bitbucket:acquia:push-dev)
6. Downloads Drush aliases, runs task acquia:deploy:after (if defined), then task update or task drupal:update, clears caches on all domains, and posts a commit status (task bitbucket:acquia:update-dev)

User-defined hooks

Add these tasks to your project's Taskfile.yml as needed:

Bitbucket repository variables

Add these in your Bitbucket repository settings under Repository variables:

Note: BITBUCKET_COMMIT is injected automatically by Bitbucket Pipelines and does not need to be set manually.

Note: When both AcquiaReviewApps and AcquiaDeploy are configured, composer install generates a single merged bitbucket-pipelines.yml containing all pipeline sections. Do not edit this file manually — changes will be overwritten on the next composer install.

Acquia Review Apps

Acquia Review Apps create an Acquia Cloud Development Environment (CDE) for every pull request, equivalent to Pantheon Multidev environments.

To enable Acquia Review Apps on Bitbucket:

• Add the following to composer.json:

• Run composer install to scaffold the following files into your project:
  • bitbucket-pipelines.yml — generated at the repository root and kept up to date on every composer install. Do not edit this file manually — changes will be overwritten.
  • Taskfile.yml — a bitbucket include pointing to vendor/lullabot/drainpipe/tasks/bitbucket.yml is auto-injected

How it works

When a pull request is opened or updated, the pull-requests pipeline:

1. Installs system dependencies and configures SSH
2. Runs composer install
3. Installs Acquia CLI and authenticates (task bitbucket:acquia:setup)
4. Runs the pre-deploy build hook if defined (task bitbucket:acquia:build → task acquia:deploy:before)
5. Pushes code to a PR-specific branch on Acquia, creates the CDE (PR-{N}) if it doesn't exist, copies the database from the source environment (default: dev) unless ACQUIA_REVIEW_RUN_INSTALLER is set, and waits for the code switch to complete (task bitbucket:acquia:push-cde)
6. Downloads Drush aliases, runs task acquia:deploy:after (if defined) and task update or task drupal:update, then posts the environment URL as a commit status (task bitbucket:acquia:update-cde)

Stale CDEs are not deleted automatically on PR close. See Scheduling the cleanup pipeline below.

Bitbucket repository variables

Add these in your Bitbucket repository settings under Repository variables:

Note: BITBUCKET_WORKSPACE, BITBUCKET_REPO_SLUG, BITBUCKET_COMMIT, and BITBUCKET_PR_ID are injected automatically by Bitbucket Pipelines and do not need to be set manually.

Scheduling the cleanup pipeline

Bitbucket does not trigger pipelines on PR close. To avoid accumulating stale CDEs, schedule the acquia-review-apps-cleanup custom pipeline:

1. In your Bitbucket repository, go to Repository settings → Pipelines → Schedules
2. Add a new schedule for the acquia-review-apps-cleanup custom pipeline (e.g., daily at midnight)

Known limitations

• No automatic cancel-in-progress — multiple commits to the same PR will queue rather than cancel prior runs.
• Extra credentials required — BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD must be set manually, unlike GitHub where GITHUB_TOKEN is injected automatically.

Async deploy with Quicksilver (GitLab)

The AsyncDeploy option is also available for GitLab. Add it alongside "ReviewApps":

Then run composer install. The following files are scaffolded or replaced:

• .drainpipe/gitlab/PantheonReviewApps.gitlab-ci.yml — replaced with the async variant (exits after git push)
• .drainpipe/gitlab/PantheonReviewAppsPostDeploy.gitlab-ci.yml — new post-deploy job triggered by Quicksilver
• web/private/scripts/drainpipe_notify_gitlab.php — Quicksilver script that fires the pipeline trigger

Manual step: add the Quicksilver hook to pantheon.yml

Drainpipe does not auto-edit pantheon.yml because it is version-controlled and site-specific. Add the following to your site's pantheon.yml:

Important: the path is private/scripts/ — not web/private/scripts/. Pantheon resolves this path relative to the web root when web_docroot: true is set. Using the web/ prefix is a common misconfiguration that silently prevents the hook from running.

Set Pantheon secrets (once per site)

Note: Job 2 (post-deploy) is triggered via a pipeline trigger and runs on the main branch, not the MR branch. This is intentional — Job 2 only needs composer install to obtain the drush/task binaries; it does not rebuild the project. Do not expect Job 2 to run on the MR branch.

Note: terminus secret:set requires the terminus-secrets-manager-plugin. Add it to the TERMINUS_PLUGINS CI variable to make it available in CI.

Multidev content cloning performance

By default, every push to an open pull request / merge request wipes the multidev's database and files and re-clones them from the source environment (e.g. live). This guarantees that reviewers always see content that mirrors production, but it is the slowest part of the deployment: cloning a large database can add several minutes to every CI run.

Set PANTHEON_SKIP_WIPE_MULTIDEV to 'true' (GitHub) or "true" (GitLab) to change this behaviour:

• First push (multidev does not exist yet): content is still cloned from the source environment so the environment starts with realistic data.
• Subsequent pushes (multidev already exists): the wipe step is skipped. Only code is updated. The database and files remain as they were after the previous deployment, which may include data entered or modified by reviewers.

When to use it: PANTHEON_SKIP_WIPE_MULTIDEV=true is a good default for projects where reviewers do not depend on a fresh production database for each review, or where the live database is large enough to make cloning noticeably slow. Keep it at the default false when it is important that each push reflects the current production content (e.g. for content-heavy sites where QA involves checking migrations or editor workflows).

Tugboat

Add the following to composer.json to add Tugboat configuration:

Then, run ddev composer install to generate:

• .tugboat/config.yml - Complete Tugboat configuration
• .tugboat/scripts/ - Helper scripts (if needed)
• web/sites/default/settings.tugboat.php - Drupal settings for Tugboat

The following will be autodetected based on your .ddev/config.yml:

• Web server (nginx or apache)
• PHP version
• Database type and version
• Nodejs version
• Redis (Obtained with ddev get ddev/ddev-redis)
• Solr (Obtained with ddev get ddev/ddev-solr)

Additionally, Pantheon integration can be added:

This will install Terminus in the Tugboat environment. Add TERMINUS_MACHINE_TOKEN as a Tugboat environment variable and set PANTHEON_SITE_ID in your Taskfile.yml vars. Then add a sync:tugboat task to fetch the database during Tugboat preview builds:

Similarly, Acquia integration can be added:

This will install Acquia CLI (acli) in the Tugboat environment. Add ACQUIA_API_KEY and ACQUIA_API_SECRET as Tugboat environment variables and set ACQUIA_ENVIRONMENT_ID in your Taskfile.yml vars. Then add a sync:tugboat task:

When using MySQL as the database engine in DDEV, Tugboat can be configured to use the percona Docker image instead of mysql:

Custom Templates

For the main php service, you can override any build phase template by copying it to .tugboat/drainpipe-templates/. Example:

Edit .tugboat/drainpipe-templates/php-init.yml.twig to add, remove, or modify commands, then regenerate the Tugboat configuration file with ddev composer install.

Available Templates:

• php-init.yml.twig - Init phase commands
• php-update.yml.twig - Update phase commands
• php-build.yml.twig - Build phase commands
• php-online.yml.twig - Online phase commands
• config.yml.twig - Complete Tugboat configuration (advanced)

Tasks

Tugboat specific tasks are contained in tasks/tugboat.yml. Add the following to your Taskfile.yml's includes section to use them:

It is assumed the following tasks exist:

• sync
• build
• update
• online

The build, sync, and update tasks can be overridden with sync:tugboat, build:tugboat, and update:tugboat tasks if required (you will need to re-run composer install to regenerate the Tugboat scripts if you are adding this task to your Taskfile.yml for the first time).

💡 composer install should be re-run if any changes are made to the DDEV configuration.

Custom init commands

You can hook into the init step of any service by adding them to your Taskfile.yml. These additional commands will be run at the end of the init phase for the specific Tugboat service.

Supported services:

• Webserver: tugboat:php:init
• Database: tugboat:mysql:init / tugboat:mariadb:init / tugboat:postgres:init
• Memory cache: tugboat:redis:init / tugboat:memcached:init

Example:

Custom online commands

You can also add an online step to the php service by adding a task named online:tugboat and re-running composer install.

Additional Tugboat keys

Drainpipe will fully manage your .tugboat/config.yml file, you should not edit it. The following keys can be added to your config.yml via a .tugboat/config.drainpipe-override.yml file:

Mail Configuration

By default, Drainpipe configures Tugboat environments to capture email using Tugboat's built-in mail capture service. This automatically configures:

• The core mail system to use php_mail
• The Mail System module (if installed) to use php_mail as the sender
• Symfony Mailer (if installed) to send mail through Tugboat's SMTP service

If you need to use a different mail configuration (e.g., for testing with a specific mail service or module), you can override these settings in your custom settings file (typically web/sites/default/settings.tugboat.php or web/sites/default/settings.php).

For example, to use a different mail backend:

Contributor Docs

This repo is public.

Please be careful to remove sensitive customer specifics when posting Issues or comments.

First time contributors need a maintainers approval for automated tests to run. (This is so we aren't at risk of getting a big CI bill accidentally, or maliciously.)

Peer Reviewing by looking at PR code changes is nice.

Testing PR code changes on real sites is extra beneficial.

Local Development

In order to test local changes follow the instructions for the test script.

Peer Review Guidelines for Automated Updates

These are guidelines for conducting peer reviews on automated dependency update pull requests created by Renovate.

All automated updates submitted by Renovate undergo a series of automated tests via GitHub Actions. These tests are designed to ensure compatibility and stability with the new versions of dependencies.

All Renovate peer reviews regardless if they're a minor or patch release require:

1. Reading the change logs carefully to understand the new features and fixes.
   • Assess if the changes necessitate additional test coverage or could potentially impact existing functionality.
   • Consider the implications of new features on the project's future development and maintenance.
2. All tests and checks must pass

Handling Version Ranges

Some dependencies allow multiple versions, like "drush/drush": "^10|^11|^12".

• Renovate will create pull requests when any of these versions get patch or minor releases.
• We DO NOT want to merge these, because it would pin these packages to a specific version.
• We DO want to allow these pull requests to run checks. This will confirm that the latest version within the range Drainpipe supports is unlikely break builds.
• After all GitHub Action checks pass, leave a comment on the pull request stating such, close the pull request, and delete the branch.

Handling Test Failures

Occasionally, tests may fail due to transient issues or flakiness in the test suite. In such cases:

1. Verify the nature of the test failure to ensure it's not related to the dependency update.
2. If the failure seems unrelated to the update, re-run the GitHub Actions job to confirm if the issue persists.
3. Document any recurring flakiness or issues on the pull request then create a new issue linked to the pull request for further investigation.

Conducting the Peer Review

1. Review the Automated Update Pull Request (PR):

   • Ensure the PR title and description clearly describe the update and its scope.
   • Check the list of changed files to understand the extent of the update.

2. Assess Test Results:

   • Ensure all GitHub Actions tests have passed. Pay close attention to tests that touch on updated dependencies.
   • For failed tests, follow the "Handling Test Failures" guidelines above.

3. Read the Dependency Change Logs:

   • For minor point releases, review the dependency's change logs to identify any significant changes or additions.
   • Evaluate how these changes might affect the Drainpipe project.
4. Final Decision:
   • For patch releases with all tests passing, proceed to merge the update.
   • For minor point releases, after thorough review and consideration, decide whether to merge the update or request manual testing before merging.

Releases

drainpipe and drainpipe-dev release process

When making a release, increase the version based on https://semver.org/

MAJOR version when you make incompatible API changes MINOR version when you add functionality in a backward compatible manner PATCH version when you make backward compatible bug fixes

Specifically for drainpipe, when a new "check" is added, that might break builds in projects, that would usually be a MINOR release, with a release note about the change.

Before making a new release, post in the lullabot internal #devops slack channel to coordinate with other maintainers.

1. Generate a GitHub release for drainpipe
   1. Supply the correct tag based on the changes and semantic versioning standards.
   2. Use the Generate release notes button and review the changes to confirm the new version is correct based on semantic versioning.
   3. Set this release as latest and publish.
2. The release when published will automatically kick off a release of drainpipe-dev using the DrainpipeDev GitHub workflow.
3. Visit the project board and archive the Ready to Release column.

NPM package release process

To generate new NPM package releases:

1. Have the latest main branch checked out locally
2. Run yarn install && yarn lerna publish
3. Create a pull request with the changes
4. Once merged, locally switch to the main branch and run yarn lerna exec -- npm publish