Cloud Platform

About build artifacts

After the build is complete, Pipelines creates a “build artifact” consisting of the contents of the SOURCE_DIR and commits the artifact to your Cloud Platform repository in a build branch named pipelines-build-[BRANCHNAME] by default.

Pipelines commits build artifacts automatically and does not log the results of the commit. However, the pipelines start command does display the path of the build branch in the repository.

Why is the build artifact created in the repository?

Storing the build artifact in your Cloud Platform repository provides the following advantages over alternatives such as creating a tarball:

  • You can easily deploy the build artifact to your Cloud Platform environments, using the Cloud Platform interface or the Cloud API.

  • You can easily view the build artifact using Git.

  • You can more easily debug your build process, comparing the build artifact against what you may have expected, and compare build artifacts over time, using a tool like git diff.

  • You can control how long your build artifacts are retained, since you control the contents of your own repository. You may, for example, have compliance requirements that mandate keeping them for a specified time, or security concerns that require you to be able to delete them promptly.

  • You can easily copy a build artifact to other systems for such purposes as static code analysis or license compliance.

Deploying the build artifact

After you complete a build, you can deploy the resulting build artifact in any Cloud Platform environment. You can do this by selecting the build branch for deployment by using the Cloud Platform user interface or Cloud API.

After you set the deployed branch of an environment to a build branch, each build artifact committed to that branch is deployed immediately, without requiring any intervention. For example, if you build the master branch, and your Cloud Platform development environment is set to the pipelines-build-master branch, the build artifact is deployed immediately to that development environment when the pipeline job completes successfully.

Note

  • You cannot control the branch name or tag name committed by Pipelines. These values are always based on your source branch or tag. For example, pipelines-build-[branch_name] or pipelines-build-[tag_name].

  • Automatic deployment does not work with Node.js environments. To create your own shell script file for deploying artifacts, see Creating a shell script for deploying artifacts.

Creating a shell script for deploying artifacts

To write a shell script for deploying artifacts, create a file named deploy-artifact.sh, and place it in the root directory of the repository. Ensure that the file contains the following:

 #!/bin/bash
 set -e
 # This is a script to deploy NodeJs artifacts.
 # Note: The script doesn't handle the token expiry or any API exceptions/errors.

 # A function to end script with failed state.
err() {
  echo "Failed to deploy the artifact, check the task log for more details at $PIPELINE_JOB_URL"
  exit 1
}

if [[ -z "${TARGET_ENV_NAME}" ]]
then
  echo "Target environment name is not defined, make sure that TARGET_ENV_NAME environment variable is set"
  err
fi

if [[ -z "${PIPELINE_ARTIFACT_START_LOG}" ]]
then
  echo "Pipeline artifact start log is not defined, make sure that PIPELINE_ARTIFACT_START_LOG environment variable is set"
  err
fi

# Get Cloud Authentication token. For more details: https://docs.acquia.com/acquia-cloud/develop/api/auth/

TOKEN=$(curl -sS -X POST -u "${CLOUD_API_KEY}:${CLOUD_API_SECRET}" -d "grant_type=client_credentials" https://accounts.acquia.com/api/auth/oauth/token | python -c "import sys, json; print json.load(sys.stdin)['access_token']")

# Get target environment Id.

TARGET_ENV_ID=$(curl -sS -X GET "https://cloud.acquia.com/api/applications/$PIPELINE_APPLICATION_ID/environments" -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" | python -c "import sys, json; envs=json.load(sys.stdin)['_embedded']['items']; print [x for x in envs if x['name'] == '$TARGET_ENV_NAME'][0]['id']")

echo TARGET_ENV_ID is $TARGET_ENV_ID

 # Get artifact id from pipeline-artifact start log.

 ARTIFACT_ID=$(grep artifactId $PIPELINE_ARTIFACT_START_LOG | cut -d ' ' -f3)

 echo ARTIFACT_ID is $ARTIFACT_ID

 # Put artifact id into pipeline metadata, so you can get it later if necessary.

 pipelines_metadata artifact_id $ARTIFACT_ID

 # Deploy artifact to target environment. Use the notification URL returned to get the task's status.
 # For more details: http://cloudapi-docs.acquia.com/#/Environments/postDeployArtifact

 NOTIFICATION_LINK=$(curl -sS -X POST -d "{\"artifact_id\":\"$ARTIFACT_ID\"}" "https://cloud.acquia.com/api/environments/$TARGET_ENV_ID/artifacts/actions/switch" -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" | python -c "import sys, json; print json.load(sys.stdin)['_links']['notification']['href']")

 # Poll NOTIFICATION_LINK to know the task status, the status will be 'in-progress' until the task is finished. For more details: https://cloudapi-docs.acquia.com/#/Notifications/getNotificationByUuid

 DEPLOY_STATUS=$(curl -sS -X GET "$NOTIFICATION_LINK" -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" | python -c "import sys, json; print json.load(sys.stdin)['status']");

 echo "Waiting for the deployment to be finished, current status: $DEPLOY_STATUS."

 while [ $DEPLOY_STATUS == 'in-progress' ]; do
    sleep 60
    TOKEN=$(curl -sS -X POST -u "${CLOUD_API_KEY}:${CLOUD_API_SECRET}" -d "grant_type=client_credentials" https://accounts.acquia.com/api/auth/oauth/token | python -c "import sys, json; print json.load(sys.stdin)['access_token']");

    echo "New TOKEN generated";

    DEPLOY_STATUS=$(curl -sS -X GET "$NOTIFICATION_LINK" -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" | python -c "import sys, json; print json.load(sys.stdin)['status']");

    echo "Waiting for the deployment to be finished, current status: $DEPLOY_STATUS.";
 done

 echo $DEPLOY_STATUS

 # Exit with 1 if the final status is 'failed'. Do nothing if the final status is 'completed' which means the deployment was successful.

 if [ "$DEPLOY_STATUS" == 'failed' ]
 then
   err
 fi

Node.js build artifacts

Node.js application support in Cloud Platform uses the Cloud Platform pipelines functionality to build an artifact that you can then deploy to your environment.

Each artifact has a name, which enables you to select a specific artifact by that name in the deployment phase. When you deploy, the most recently built artifact will be at the top of the list. The default naming convention for node artifacts is as follows:

[git branch]@[commit hash]

This can cause issues, as commits can be amended. This can result in two artifacts with the same name but with different comments.

It is possible to set a default name for your artifact by adding configurations to your yaml file using the pipelines-artifact command and pipelines variables. To do this, complete the following steps:

  1. Edit your build definition file. For examples, see Example Pipelines build definition files.

  2. Find the following line in the file:

    - pipelines-artifact start
    
  3. Edit the line by adding the PIPELINE_VCS_PATH and PIPELINE_GIT_HEAD_REF options to your start command, similar to the following:

    - PIPELINE_VCS_PATH=artifact PIPELINE_GIT_HEAD_REF=example pipelines-artifact start
    
  4. Save the build definition file.

Using this example, your artifact name will become artifact@example rather than branch@commit.