Information for:

# Creating and managing your build definition file¶

An important element of the pipelines feature is the build definition file. This is a YAML format file (named acquia-pipelines.yaml) that you create in your workspace. The build definition file contains all of the information that is required to perform the build, including any variables that are required and the instructions used to perform the build. The components of the build process can be broken into individual steps in the build definition file, and each step will be executed in order. Each step corresponds to the keys at the top level in the steps section of the build definition file.

Note for pipelines feature usage with Node.js applications

An example of build definition file syntax suitable for use with Node.js is available at Getting started with Node.js applications and environments.

Pipeline builds will time out after 60 minutes. Unless all steps and processes used during the build are closed before the timeout, the build job will fail.

## Build definition file structure¶

The build definition file must be named acquia-pipelines.yaml and must exist in the root directory in the branch you wish to build.

The file will have the following approximate key/value structure. Click a key for additional information.

You can also use the pipelines_metadata key in any of the previously mentioned sections of your build definition file to send build or container information back for your use. Learn more.

### version key¶

This required key must have a value of at least 1.0.0 for use with the pipelines feature.

To use PHP 7, you must use a version key value of 1.1.0 or greater. For more information about using PHP 7 in your build definition file, see the services: php section on this page.

Using a version key value of 1.2.0 or greater adds support for the cde-databases: key of your YAML file.

### variables key¶

The variables key of the build definition file provides a means of setting environment variables that are needed for your build. The environment variables are defined for all commands run during the job.

Here is a simple example of the variables key:

variables:
global:
secure: 2aciWcRBNXrG/KcWG1bb0uSRTOVoiDl+h+QRi$. . .  For details about including secure (encrypted) variables in the variables key, see Encrypting keys and variables. #### Default environment variables¶ The following environment variables are set by the system: Variable name Description CI, CONTINUOUS_INTEGRATION With a value of true, indicates that this job is being run in a continuous integration context, rather than initiated directly by a human. PIPELINE_APPLICATION_ID The application ID for this job’s pipeline. PIPELINE_CLOUD_REALM The realm in which the application is running. For configuration information, see Developing with Acquia Cloud. PIPELINE_CLOUD_SITE The Acquia Cloud application name or site name that corresponds to the application ID. PIPELINE_DEPLOY_VCS_PATH The branch or tag that will hold the output of the job. PIPELINE_ENV With a value of true, indicates that this job is being run in a pipeline context. PIPELINE_GIT_HEAD_REF A reference to the last commit in the Git repository. PIPELINE_JOB_ID The job ID for this job. PIPELINE_STATUS With a value of running, indicates that this job is running in a pipeline context. PIPELINE_VCS_PATH The path of the branch specified in the --vcs-path argument of the start command. ### cde-databases¶ This key, available to version 1.2.0 and higher, enables you to specify which database schemas in a multisite configuration will be used to build this application. You can select a maximum of three databases. cde-databases: - my-first-database - my-second-database  This definition has one of the following results, depending on its settings: Definition value Result Undefined/empty All of the databases that are available for the application will be deployed to environment null (~) All of the databases that are available for the application will be deployed to environment array Only the specified databases will be included in the environment created by the job database name not defined on the application The job will fail any other value The job will display an error For information about copying databases, see Copying a database into an Acquia Cloud CD environment. ### services key¶ The services key allows you to enable one or more services to be available during the execution of your pipelines job. #### services: mysql¶ If your build process requires the use of MySQL, be sure to include the services: mysql key in your build definition file. The mysql service starts a MySQL database server on 127.0.0.1 port 3306 for the duration of the job. This database is configured with only one user configured, which has the username root and the password root. Note You must use the services: mysql key to start MySQL in your build definition file. The Acquia Cloud pipelines feature does not support sudo mysql commands. #### services: php¶ If your build process requires PHP 7, be sure to both set your version key to 1.1.0 and include the services: php key in your build definition file. For a services: php example, see the following: services: - php: version: 7.1  ### events key¶ The required events key is the parent of the following keys: Key Required Description build Yes Describes how the workspace will be built fail-on-build No Executes only if the build fails post-deploy No The post-deploy event is triggered after the build event pr-merged No Steps taken if a pull request is merged to its base branch pr-closed No Steps taken if a pull request is closed without being merged to its base branch ### build key¶ The build key is required in the events top-level key. The build event is triggered by the pipelines start command. The contents of the build key describe how the workspace is to be built. It must contain a single steps key, with values describing the actual process of the build. ### fail-on-build key¶ The fail-on-build key is optional in the events top-level key, and will execute only if the build event fails. The fail-on-build must contain a single steps key, which may have multiple values. For example: fail-on-build: steps: - runonfailure: type: script script: - "echo 'This is simple echo from fail-on-build event'"  ### post-deploy key¶ The post-deploy key is optional in the events top-level key, and executes after the build event. This key must contain a single steps key, with a value describing the actual process. ### pr-merged key¶ The pr-merged key is triggered when a GitHub pull request is merged to its base branch. This key must contain a single steps key, with a value describing the actual process. ### pr-closed key¶ The pr-closed key is triggered when a GitHub pull request is closed without being merged to its base branch. This key must contain a single steps key, with values describing the actual process. ### steps key¶ The steps key describes the steps to accomplish the build. Each step will be executed in the order it appears in the steps key of the build definition file. Each steps key has a type property that indicates how the step will be executed. Note When creating your build definition file, the final action in the steps key should move the directory to the docroot. If you do not do this, your build cannot be used on Acquia Cloud. #### type: script¶ Steps of type: script let you specify arbitrary shell commands to be executed by Bash. Each type: script step must include a script key whose value is a list of shell commands, each listed on a separate line starting with a dash (-). When the script step runs, the lines are all combined into a single Bash script and executed. By default, the pipelines feature prepends scripts with set -e, which causes the script to exit immediately if any command has a non-zero exit code. You can override this behavior by including set +e in your build script. Be aware that if you use set +e, the script does not fail when a command fails, and so it is the responsibility of the script to manage its own exit strategy and exit codes. If a script step runs a program in the background (such as an HTTP server), the backgrounded program is terminated at the end of the step that it was started in. This means that a backgrounded program that started in one script step will not be present and available in a subsequent steps. ### ssh-keys key¶ The ssh-keys key enables you to add SSH keys that may be required to access private resources. These keys are encrypted and can be generated using the pipelines encrypt command. Here is an example ssh-keys key: ssh-keys: mykey: secure: 2aciWcRBNXrG/KcABCOvoIDTDG1bboUsVjDl+h+QRi$


Any number of keys can be added in the ssh-keys key. The value of the ssh-keys key (mykey in this example) is the name of the key. When the pipelines feature reads the build definition file, it attempts to decrypt the SSH keys. If the decryption is successful for one or more keys, Acquia Cloud writes those keys into the ~/.ssh directory, making them automatically available for use when accessing private resources from the build script.

Important

Acquia recommends that you generate a unique SSH key for each application, as the contents of your key are available during runtime. Any access that you allow to this key should be based on the principle of least privilege.

#### Linking to specific SSH keys with a variable¶

To specify which SSH key will be used in a script, set the PIPELINE_SSH_KEY variable with the correct key, as in the following example:

version: 1.1.0
events:
build:
steps:
- welcome:
script:
- echo 'STARTED'
- export PIPELINE_SSH_KEY=~/.ssh/ssh-key-1
- echo 'Steps (git operations) will be successful which are dependent on ssh-key-1'
- unset PIPELINE_SSH_KEY
- echo 'Step executed with default ssh keys'
- export PIPELINE_SSH_KEY=~/.ssh/ssh-key-2
- - echo 'Steps (git operations) will be successful which are dependent on ssh-key-2'
- unset PIPELINE_SSH_KEY
- echo 'FINISHED'
ssh-keys:
ssh-key-1:
secure: REDACTED
ssh-key-2:
secure: REDACTED


When a specified SSH key is no longer required in a step, use unset PIPELINES_SSH_KEY to switch back to the default key.

There are times when it can be useful to provide information from the container or the build execution back for your use — for example, one item from a specific execution step that could influence a future direction for your desired execution process. To allow for this, Acquia Cloud includes the pipelines_metadata key, which can be run from any section of the build definition file.

The key’s usage is based on the following structure:

pipelines_metadata [key] [value]


where

• [key] is the variable name you want to create for reporting
• [value] is the value you want to set for your created variable

You can view the contents of any metadata created using this key by running the status command with the --format=json option.

## Validating your build definition file¶

To determine if your build definition file uses valid YAML syntax, you can use an online validator, such as one of the following:

## Examples¶

Use this section as you develop your own, custom build definition files.

Important

Before you run the composer install command in a YAML file, to reduce memory consumption in the container, Acquia recommends that you commit the composer.lock file to your code repository.

For more information, see Pipelines build fails because of memory limitations on pipelines container.

### General example¶

Here is an example of a complete build definition file:

version: 1.1.0

variables:
global:
SLACK_HOSTNAME: "yourslack.slack.com"
SLACK_TOKEN:
secure: U48EOVjDl+h+QRi$x3kpGwBIc27rKqCblXqkv2MxMBDyV+Pas3x... SLACK_CHANNEL: "#pipelines" events: build: steps: - build: type: script script: - composer install - compass compile docroot/themes/custom/MY_THEME - unit_tests: type: script script: - ./vendor/bin/phpunit - notify: type: script script: - curl -X POST --data "payload={"channel": "${SLACK_CHANNEL}", "username": "${SLACK_USERNAME}", "text": "success"}" https://${SLACK_HOSTNAME}/services/hooks/incoming-webhook?token=\${SLACK_TOKEN}

ssh-keys:
my_module:
secure: SCxLERS9GcOrgz72zZwqBiCIx7GsWpP2Nxyx3kpGwBIc27rKqCblXqkv2MxM...


### Empty MySQL database¶

The following build definition file example creates an empty MySQL database:

version: 1.0.0
services:
- mysql

events:
build:
steps:
- setup:
type: script
script:
- mysql -u root -proot -e "CREATE DATABASE drupal"