Information for: DEVELOPERS   PARTNERS

Commands available in pipelines

The pipelines feature provides the following custom commands for your use in your YAML file:

Command Description
pipelines-artifact Build and upload Node.js artifacts
pipelines-deploy Create, deploy, or delete an Cloud Platform CD environment
pipelines_metadata Store metadata related to an Acquia Pipelines job
pipelines-sync-dbs Syncs the databases provided as parameters

Example build definition files are available at Example pipelines build definition files.

pipelines-artifact

Use with Node.js applications to build and upload the Node.js artifacts. For more information on how to create custom artifact names, see About build artifacts.

Alias Arguments
(None)
  • fail: Cancel the upload attempt
  • start: Begin the process of uploading a build artifact
  • upload [$SOURCE_DIR]: Specify the artifact to upload

Example

version: 1.0.0
variables:
        global:

events:
    build:
    steps:
        - build:
        script:
            - nvm install v6.11.2
            - nvm use 6.11.2
            - npm install --production
        - upload-artifact:
        script:
            - pipelines-artifact start
            - pipelines-artifact upload $SOURCE_DIR
    fail-on-build:
    steps:
        - fail:
        script:
            - pipelines-artifact fail

pipelines-deploy

Important

You can’t run the pipelines-deploy command inside the build event.

Create, deploy, or delete an Cloud Platform CD environment, depending on the event it is executed within. The pipelines-deploy command creates an Cloud Platform CD environment and deploys the build artifact if executed in the post-deploy event. The pipelines-deploy command deletes the corresponding Cloud Platform CD environment when used in pr-merged or pr-closed events. While this command can be executed in any event of the build definition file, Acquia recommends using it in the post-deploy event.

Note

If you remove a source branch from your external repository and then run pipelines, the underlying Cloud Platform CD environment won’t be destroyed. You will only experience failed pipelines build jobs as the service can’t find the source branch.

Alias Arguments
(None) (None)

Example

build:
  steps:
    - build_site:
          script:
            - echo "Build instructions here"
post-deploy:
  steps:
    - deploy:
            script:
            - pipelines-deploy

For more information, see Creating a CD environment with CD pipelines.

pipelines_metadata

Provide information from the container or the build execution for your use in other steps—for example, one item from a specific execution step whose value will influence a future direction in your build process. You can run this command from any section of your build definition file.

To view the contents of any metadata created using this key, run the status command with the --format=json option.

Usage

pipelines_metadata KEY VALUE [options]

where

  • [key] is the variable name you want to create for reporting
  • [value] is the value you want to set for your created variable
  • [options] are any additional options you need to specify

Do not use the = operator. Use the format -u [value] or --url [value].

Alias Arguments
-a --app – Pipelines application id. Default value is set using $PIPELINES_APPLICATION_ID
-d --debug – Debug the network connection.
-h --help – This help text
-j --job-id – Pipelines job id. Default value is set using $PIPELINES_JOB_ID
-t
--token – Temporary Pipelines auth token. Default value is set using
$PIPELINES_JOB_AUTH_TOKEN
-u --url – Pipelines URL. Default value is set using $PIPELINES_API_ENDPOINT
-v --verbose – Print the output. Disabled by default to prevent leaking sensitive information.

pipelines-sync-dbs

Syncs the databases provided as parameters, provided they are also listed as parameters in the cde-databases key. Requires the pipelines-deploy command.

If the pipelines-sync-dbs command is written after the pipelines-deploy event, the pipelines logs will display the following error:

The pipelines-sync-dbs command cannot be defined in pipelines-deploy event.
It is available only in post-deploy, pr-merged and pr-closed events.

When the pipelines-sync-dbs command is written in post-deploy, pr-merged and pr-closed events, but is written before pipelines-deploy, the pipelines logs display the following error message:

The pipelines-sync-dbs command cannot be used before pipelines-deploy.

For more information about syncing databases, see Copying a database into a Cloud Platform CD environment.

Alias Arguments
(None) [db1] [db2]: The source and target databases for copying

Example

version: 1.2.0
cde-databases:
- db1
- db2

events:

post-deploy:
    steps:
    # Deploy the build artifact to an on-demand environment,
    # and sync the specified databases.
    - deploy:
        script:
            - pipelines-deploy
            - pipelines-sync-dbs db1 db2