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.
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:
You can use Pipelines environment variables and Pipelines commands in your build steps.
You can also use the 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 |
|---|---|
| Enables PHP 7.4, 8.0, and 8.1. For more information about using PHP 7 or 8 in your build definition file, see services: php. |
| Adds support for the cde-databases key in your YAML file. |
| Adds memcached and Composer 2 support. For more information, see services: memcached and services: composer. |
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.
For information about the default environment variables provided by Pipelines, see Default environment variables in Pipelines.
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, 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
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.
services:
With the services key you can enable one or more services to be available
during the execution of your Pipelines job, including:
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 and include the services: php key in your build
definition file. For a services: php example, see the following:
services:
- php:
version: 8.1
services: memcached
If your build process requires memcached, ensure you set your version key
to at least 1.3.0 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, allows you to choose between Composer
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 |
|---|---|---|
Yes | Describes how the workspace will be built | |
No | Executes if the build fails | |
No | The post-deploy event is triggered after the build event | |
No | Steps taken if a pull request is merged to its base branch | |
No | Steps taken if a pull request is closed without being merged to its base branch |
Each of these keys can contain a 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:, 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:, 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:, with a value describing the actual process.
For an example of copying files to an on-demand environment as part of a Pipelines job, see Copying files to an on-demand environment.
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:, 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: 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 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.
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.
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 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 [email protected]: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 [email protected]: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.