--- title: "Creating and managing your build definition file" date: "2024-02-14T06:18:38+00:00" summary: "Create and manage your Pipelines build definition file with ease. Learn how to structure your YAML file, define build steps, configure services, and set environment variables. Optimize your CI/CD workflow for Acquia Cloud Platform applications." image: type: "page" url: "/acquia-cloud-platform/creating-and-managing-your-build-definition-file" id: "3678617e-3c48-4c3c-a8ec-5eb88e238c14" --- An important element of Pipelines is the build definition file. The build definition file is a YAML format file (named `acquia-pipelines.yaml`) you create in your workspace. The build definition file contains all of the required information 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. 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. Note For examples of build definition files you can customize for your application’s needs, see [Example Pipelines build definition files](/acquia-cloud-platform/features/pipelines/yaml/examples). You must name the build definition file `acquia-pipelines.yaml` or `acquia-pipelines.yml,` and the file must exist in the root directory in the branch you want to build. For the sake of consistency, documentation will refer to the file as `acquia-pipelines.yaml`, though both `.yml` and `.yaml` are valid extensions. The file will have the following key/value structure. Click a key for more information: * [version:](#pipelines-version-key) * [variables:](#variables) * [cde-databases:](#id3) * [services:](#services) * [services: mysql](#services-mysql) * [services: php](#services-php) * [services: memcached](#services-memcached) * [services: composer](#services-composer) * [events:](#events) * [build:](#build) * [fail-on-build:](#fail-on-build) * [post-deploy:](#post-deploy) * [pr-merged:](#pr-merged) * [pr-closed:](#pr-closed) * [steps:](#steps) * [type: script](#type-script) * [ssh-keys:](#ssh-keys) * [Linking to specific SSH keys with a variable](#linking-to-specific-ssh-keys-with-a-variable) You can use [Pipelines environment variables](/acquia-cloud-platform/features/pipelines/variables) and [Pipelines commands](commands.html) in your build steps. You can also use the [pipelines\_metadata](/acquia-cloud-platform/features/pipelines/commands#pipelines-metadata) command in any of sections mentioned earlier of your build definition file to send build or container information back for use in other steps. version: -------- The `version` key is a _required_ key which must have a value of at least `1.0.0` for use with Pipelines. The following version keys enable more features: Version key Features `1.1.0` or later Enables PHP versions. For more information about using PHP 7 or 8 in your build definition file, see [services: php](#php7). `1.2.0` or later Adds support for the [cde-databases](#cde-databases) key in your YAML file. `1.3.0` or later Adds [memcached](/acquia-cloud-platform/performance/memcached) and Composer 2 support. For more information, see [services: memcached](#memcache-key) and [services: composer](#composer-key). variables: ---------- The `variables` key of the build definition file provides a means of setting environment variables you need for your build. The environment variables are defined for all commands run during the job. Here is an example of the `variables` key: variables: global: ADMIN_USERNAME: admin ADMIN_PASSWORD: secure: 2aciWcRBNXrG/KcWG1bb0uSRTOVoiDl+h+QRi$. . . For details about including secure (encrypted) variables in the variables key, see [Encrypting keys and variables](/acquia-cloud-platform/features/pipelines/encrypt). For information about the default environment variables provided by Pipelines, see [Default environment variables in Pipelines](/acquia-cloud-platform/features/pipelines/variables). cde-databases: -------------- Cloud Platform CD environments support at most three databases. If your multisite application has more than three databases, you must use the `cde-databases` key, available to [version 1.2.0 and higher](#pipelines-version-key), to specify which databases the Cloud Platform CD environment will support. Single-site installations must also define `cde-databases` to [copy content from another environment](databases.html) into the Cloud Platform CD environment. cde-databases: - my-first-database - my-second-database The `cde-databases` key has one of the following results, depending on its presence and value: Value Result Undefined, empty, or null (`~`) If your application has three or fewer databases, all databases will be created in the Cloud Platform CD environment. If your application has more than three databases, the job will fail. 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 Note The databases specified by the `cde-databases` key will be empty when created. For information about copying content into the databases after they have been created, see [Copying a database into a Cloud Platform CD environment](/acquia-cloud-platform/features/pipelines/databases). services: --------- With the `services` key you can enable one or more services to be available during the execution of your Pipelines job, including: * [MySQL](#mysql-key) * [PHP 7 and 8](#php7-key) * [Memcached](#memcache-key) * [Composer](#composer-key) ### 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 infrastructure on `127.0.0.1``with port: ``3306` during the job. The database is configured with 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. Pipelines doesn’t support `sudo mysql` commands. ### services: php If your build process requires PHP 7 or 8, [set your version key to 1.1.0](#version) and include the `services: php` key in your build definition file. For a `services: php` example, see the following: services: - php: version: 8.2 ### services: memcached If your build process requires [memcached](/acquia-cloud-platform/performance/memcached), ensure you [set your version key to at least 1.3.0](#version) and include the `services: memcached` key in your build definition file, as in the following example: version: 1.3.0 services: - memcached It will start the Memcached service on `127.0.0.1` port `11211` for the duration of the job, but doesn’t support `sudo memcached` commands. ### services: composer The `services: composer` key, which is available in [version 1.3.0](#version), allows you to choose between [Composer](https://getcomposer.org) 1 and 2. Note that the container has both the versions. You can use the `services: composer` key to specify the default version. version: 1.3.0 services: - composer: version: 2 events: ------- The _required_ `events` key is the parent of the following keys: Key Required Description [build](#build) Yes Describes how the workspace will be built [fail-on-build](#fail-on-build) No Executes if the build fails [post-deploy](#post-deploy) No The post-deploy event is triggered after the build event [pr-merged](#pr-merged) No Steps taken if a pull request is merged to its base branch [pr-closed](#pr-closed) No Steps taken if a pull request is closed without being merged to its base branch Note A base branch is the branch into which you merge changes from another branch. For example: * If you create a branch from the main branch and merge the changes of the new branch into the main branch, then the main branch is considered as the base branch. * If you create a branch from an existing branch of the main branch and merge the changes of the new branch into that existing branch, then that existing branch is considered as the base branch. Each of these keys can contain a [steps:](#steps). ### build: 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. The `build` key must have a single [steps:](#steps), with values describing the actual process of the build. ### fail-on-build: The `fail-on-build` key is optional in the `events` top-level key, and will execute if the build event fails. The `fail-on-build` must have a single [steps:](#steps), which may have several values. For example: fail-on-build: steps: - runonfailure: type: script script: - "echo 'This is simple echo from fail-on-build event'" ### post-deploy: The `post-deploy` key is optional in the `events` top-level key, and executes after the build event. The `post-deploy` key must contain a single [steps:](#steps), with a value describing the actual process. For an example of copying files to an [on-demand environment](/acquia-cloud-platform/features/cd) as part of a Pipelines job, see [Copying files to an on-demand environment](/acquia-cloud-platform/features/pipelines/yaml/examples#pipelines-yaml-copy-files). Note The `post-deploy` event is triggered only if the build artifact changes during a build. The `post-deploy` event does not run if you do not commit changes at the end of the build event, such as when you run a job again. ### pr-merged: The `pr-merged` key is triggered when a GitHub pull request is merged to its base branch. The `pr-merged` key must contain a single [steps:](#steps), with a value describing the actual process. Note Pipelines start jobs when pull requests are merged or closed even if the `pr-merged` or `pr-closed` events are not defined in the `acquia-pipelines.yml` file. However, such jobs exit with the **Event pr-merged failed, could not find the specified event.** message, which you can ignore. ### pr-closed: The `pr-closed` key is triggered when a GitHub pull request is closed without being merged to its base branch. The `pr-closed` key must contain a single [steps:](#steps) key, with values describing the actual process. steps: ------ The `steps` key describes the steps to carry out the build. Each step will be executed in the order the step 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 don’t do this, your build can’t be used on Cloud Platform. ### 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, Pipelines prepends scripts with `set -e`, which causes the script to exit immediately if any command has a non-zero exit code. You can override the behavior by including `set +e` in your build script. Be aware that if you use `set +e`, the script doesn’t fail when a command fails, and so it’s 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 infrastructure), the background program is terminated at the end of the step the program began running in. A background program which started in one `script` step won’t be present and available in later steps. ssh-keys: --------- 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 Pipelines reads the build definition file, Pipelines attempts to decrypt the SSH keys. If the decryption is successful for one or more keys, Cloud Platform writes those keys into the `~/.ssh` directory, making them available for use when accessing private resources from the build script. Important * Acquia recommends you [generate a unique SSH key](/acquia-cloud-platform/manage-apps/command-line/ssh/getting-started/generate) for each application, as the contents of your key are available during runtime. Any access you allow to the key should be based on the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). * The default format of SSH keys generated by OpenSSH version 7.8 or later is incompatible with Pipelines. For more information, see [this known issue](/acquia-cloud-platform/features/pipelines/known-issues#known-pipelines-openssh). ### Linking to specific SSH keys with a variable To specify which SSH key will be used in a script, set the `PIPELINE_SSH_KEY` [environment variable](/acquia-cloud-platform/features/pipelines/variables) 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 - git ls-remote git@bitbucket.org:username/repo-dependent-on-ssh-key-1.git - 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 - git ls-remote git@bitbucket.org:username/repo-dependent-on-ssh-key-2.git - - 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.