This document outlines the workflow to build a complete Drupal application (plus supporting features, such as Cloud Hooks) which can be deployed directly to Cloud Platform. Collectively, this bundle of code is referred to as the build artifact.
The most important thing to remember about this workflow is that the GitHub and Cloud Platform repositories are not clones of one another. GitHub only stores the source code, and Cloud Platform only stores the production code (for example, the build artifacts).
Currently, this workflow can either be followed manually, or integrated into a continuous integration (CI) solution such as Pipelines, Travis CI, or Jenkins.
You should have your GitHub repository checked out locally. Your Cloud Platform repository should be empty, or nearly empty.
Check out a new branch to match whatever branch you are working on in GitHub
Ensure your Cloud Platform remote is listed in
git:remotes. For example:
git: default_branch: master remotes: cloud: '[email protected]:project.git'
In order to create the build artifact in
/deploy, run the following
This task is analogous to
source:build but with a few critical
The docroot is created at
Only production required to the docroot
(planned) Sensitive files, such as
CHANGELOG.txt, are removed.
After the artifact is created, you can inspect it or even run it as a website locally. You may also manually commit and push it to Cloud Platform.
To both create and deploy the build artifact in a single command, run the following command:
blt artifact:deploy --commit-msg "BLT-000: Example deploy to branch" --branch "develop-build" --no-interaction
This command will commit the artifact to the
develop-build branch with
the specified commit message and push it to the remotes defined in
To create a new Git tag for the artifact (rather than committing to a branch) run the following command:
blt artifact:deploy --commit-msg "Creating release 1.0.0." --tag "1.0.0"
This will generate the artifact, tag it with
1.0.0, and push it to the
remotes defined in
When deploying a tag to the artifact repository, if the config option
deploy.tag_source is set to
TRUE, BLT will also create the
supplied tag on the source repository. This makes it easier to verify the
source commit upon which an artifact tag is based.
BLT does not push the tag created on the source repository to its remote.
The artifact is built by running the
artifact:build target, which does the
Rsyncs files from the repository root.
Re-builds dependencies directly in the deploy directory (for example,
The rsync and re-build processes can be configured by modifying the values of
variables under the top-level
deploy key in your
For more information about overriding default configuration, see Extending and overriding BLT.
If you want to create, commit, but not push the artifact, you can create a test run with the following command:
blt artifact:deploy --dry-run
This is helpful for debugging deployment artifacts.
Instead of performing these deployments manually, you can enlist the help of a CI tool, such as Pipelines, Travis CI, or Jenkins. This will allow you to generate deployment artifacts whenever code is merged into a given branch. For information about configuring a CI tool, see Continuous integration.
On Cloud Platform, Cloud Hooks are the preferred method to run database updates and configuration imports on each deploy. BLT provides a post-code-deploy hook that will run these updates and fail the deployment task if anything goes wrong.
To install Cloud Platform hooks for your BLT project, complete the following steps:
Initialize Cloud Platform hooks by running the following command:
This will add a hooks directory in your project root based on Acquia BLT’s default Cloud Platform hooks.
Commit the new directory and push it to your Acquia Git remote. Refer to the following example commands:
git add hooks git commit -m 'Initializing Cloud Platform hooks.' git push origin
For consistency and reliability, you should run the same updates on deployment
as you would run locally or in CI testing. BLT provides aliases for the
drupal:update task to support this in a local environment and
artifact:update:drupal to execute against an artifact.
For more information, see the Cloud Platform Hooks Slack example.