--- title: "Configuring external CI/CD" date: "2025-08-25T16:03:14+00:00" summary: "Learn how to set up continuous integration and deployment for Node.js apps on Acquia Cloud. Step-by-step guide for seamless CI/CD integration." image: type: "page" url: "/acquia-cloud-platform/add-ons/node-js/configuring-external-cicd" id: "c753f3f0-1a70-4305-93ae-7138112bd42e" --- Table of contents will be added Configuring external CI for Front End Hosting - Advanced applications --------------------------------------------------------------------- This guide describes how to integrate external continuous integration (CI) with Front End Hosting - Advanced applications. These platform-agnostic instructions adapt to any CI system. ### Prerequisites Before you configure your CI pipeline, ensure the following requirements are met: * Install Node.js version 20 or higher in the CI environment. * Install the npm package manager in the CI environment. * Configure git in the CI environment. * Set up an SSH key and SVN URL for the Acquia SVN repository in the CI environment. * Configure required environment variables and secrets in the CI platform. * Create a file named `acquia_config.yaml` in the branch root directory. ### Required environment variables Configure these required secrets in your CI platform: Variable Description `DEPLOY_SSH_KEY` Private SSH key for authentication to the Acquia SVN repository `DEPLOY_BRANCH` Name of the branch to push to Acquia SVN ### CI pipeline configuration 1. In the root directory of the deployment branch, add an `acquia_config.yaml` file with the following content: enable-prebuilt-artifact: true If `acquia_config.yaml` is missing or this setting is unspecified, the default is false. 2. Configure the CI/CD pipeline to use Ubuntu or an equivalent Linux distribution. Use a Node.js version supported by Acquia. To learn more about Acquia supported Node.js versions, [click here](/acquia-cloud-platform/add-ons/node-js/help/68551-which-nodejs-versions-are-supported-front-end-hosting-advanced-offering "Which Node.js versions are supported by the Front End Hosting - Advanced offering?"). Execute all build processes in a `Linux amd64` environment for compatibility. Example Node.js installation: # Install Node.js # This step varies by CI/CD platform # Example for generic Linux environment: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs 3. Check out source code of the branch from your repository. 4. Install all required Node.js dependencies: npm install 5. Build your application: npm run build Note * To start script in `package.json`, refer to [Framework-based custom configuration](/node/66366#framework-based-custom-configuration). * To implement autoscaling, refer to [Implementing autoscaling](/node/66366#implementing-autoscaling). 6. Ensure `acquia_config.yaml` and [`acquia-autoscaling.js`](/node/66366#implementing-autoscaling) are included with all build artifacts. Prepare a clean build directory that contains only necessary deployment files: # Remove any existing build output directory rm -rf build-output # Create new build output directory mkdir build-output # Copy required files and directories, acquia_config.yaml, node_modules and acquia-autoscaling.js # Add any framework specific files/folders required for deployment here. The following example demonstrates the configuration for the Next.js framework.. cp -R _static public package.json next.config.js node_modules acquia_config.yaml acquia-autoscaling.js build-output/ # Note: Add any additional files your application requires for deployment 7. Configure git inside the build output directory: cd build-output # Initialize Git repository git init # Configure Git user (replace with your details) git config user.name "your-username" git config user.email "your-email@domain.com" # Add remote repository git remote add target 8. Set up SSH for secure deployment: # Create SSH directory mkdir -p ~/.ssh # Add SSH private key (using your CI/CD platform's secret management) echo "$DEPLOY_SSH_KEY" > ~/.ssh/id_rsa chmod 600 ~/.ssh/id_rsa # Add host to known hosts ssh-keyscan -H >> ~/.ssh/known_hosts 9. Commit build artifacts and push to the deployment repository: cd build-output # Create and checkout deployment branch git checkout -b $DEPLOY_BRANCH # Stage all files git add . # Commit changes git commit -m "Build output from CI/CD pipeline" # Force push to deployment branch git push target $DEPLOY_BRANCH 10. After deployment, verify that the Cloud Platform UI lists and completes a commit-based deployment task for your environment. Confirm that the intended branch has been successfully deployed to your environment. ![nodejs-continuous_integration](https://acquia.widen.net/content/e1ac5c17-36e8-44ee-955e-37c055150745/web/4bfe1_nodejs-continuous_integration.jpg?w=1090&itok=leIU9Cs_) Configuring external CD for Front End Hosting - Advanced applications --------------------------------------------------------------------- This guide describes how to integrate external continuous deployment (CD) with Front End Hosting - Advanced applications. These platform-agnostic instructions adapt to any CD system. ### Prerequisites Before setting up the CD pipeline, ensure the following items are available: * Bash shell in the deployment environment. * `curl` command-line utility configured. * `jq` command-line JSON processor available. * Required environment variables and secrets set up in the CD platform. * `deploy.sh` script created in the branch root directory. ### Required environment variables Configure these required secrets in your CI platform: Variable Description `CLIENT_ID` Cloud API client ID `CLIENT_SECRET` Cloud API client Secret `ENVIRONMENT_ID` Cloud environment ID `DEPLOY_BRANCH` Name of the Acquia SVN branch to deploy ### CD pipeline configuration 1. Obtain the Cloud API Client ID, Cloud API Client Secret, environment ID, and the branch name for deployment. These are required to call the `deploy.sh` script. Set all these values as environment secrets in your CD platform. * Generate Cloud API credentials as described on the [Cloud Platform API v2 authentication](/acquia-cloud-platform/cloud-platform-api-v2-authentication "Cloud Platform API v2 authentication") page. * The environment ID is visible in the URL when an environment is open in Cloud UI. ![nodejs-continuous_deployment_environmentid](https://acquia.widen.net/content/fbbf6b99-335a-4db7-90f5-73b44e640892/web/7b50c_nodejs-continuous_deployment_environmentid.jpg?w=1090&itok=x2e3Y7ze) * The branch name is the branch you choose for deployment on the environment. 2. Add a `deploy.sh` script to the project root. #!/bin/bash # Usage: ./deploy.sh --environment-id --branch --client-id --client-secret # OR # Usage: ./deploy.sh --environment-id= --branch= --client-id= --client-secret= set -e # Initialize variables environmentId="" branch="" CLIENT_ID="" CLIENT_SECRET="" # Function to display usage usage() { echo "Usage: $0 --environment-id --branch --client-id --client-secret " echo " or: $0 --environment-id= --branch= --client-id= --client-secret=" echo "" echo "Options:" echo " --environment-id Environment ID for deployment" echo " --branch Git branch to deploy" echo " --client-id OAuth client ID" echo " --client-secret OAuth client secret" echo " -h, --help Show this help message" echo "" echo "Note: You can use either --flag value or --flag=value format" exit 1 } # Parse command line arguments while [[ $# -gt 0 ]]; do case $1 in --environment-id=*) environmentId="${1#*=}" shift ;; --environment-id) environmentId="$2" shift 2 ;; --branch=*) branch="${1#*=}" shift ;; --branch) branch="$2" shift 2 ;; --client-id=*) CLIENT_ID="${1#*=}" shift ;; --client-id) CLIENT_ID="$2" shift 2 ;; --client-secret=*) CLIENT_SECRET="${1#*=}" shift ;; --client-secret) CLIENT_SECRET="$2" shift 2 ;; -h|--help) usage ;; *) echo "Unknown option: $1" usage ;; esac done # Check for missing parameters if [[ -z "$environmentId" || -z "$branch" || -z "$CLIENT_ID" || -z "$CLIENT_SECRET" ]]; then echo "Error: All parameters are required." echo "" usage fi AUTH_SERVER_URL="https://accounts.acquia.com/api/auth/oauth/token" CODE_DEPLOYMENT_URL="https://cloud.acquia.com/api/environments/${environmentId}/code/actions/switch" # Obtain access token response=$(curl --silent -L --request POST \ --url "${AUTH_SERVER_URL}" \ --header "content-type: application/x-www-form-urlencoded" \ --data grant_type=client_credentials \ --data client_id="${CLIENT_ID}" \ --data-urlencode client_secret="${CLIENT_SECRET}") # Check if there was an error in the response if [[ "$response" == *"error"* ]]; then echo "Error in obtaining token:" echo "$response" exit 1 fi # Extract the access token from the JSON response access_token=$(echo "$response" | jq -r .access_token) echo "Access token obtained." echo "Deployment URL: $CODE_DEPLOYMENT_URL" # Trigger code deployment response=$(curl --silent -X POST "${CODE_DEPLOYMENT_URL}" \ -H "Authorization: Bearer $access_token" \ -H "Content-Type: application/json" \ -H "Accept: application/hal+json" \ -d "{ \"branch\": \"$branch\" }") echo "Deployment response:" echo "$response" 3. Run the deployment script with all parameters: # Run deployment script with required parameters ./deploy.sh --client-id=$CLIENT_ID --client-secret=$CLIENT_SECRET --environment-id=$ENVIRONMENT_ID --branch=$DEPLOY_BRANCH _Example:_ ![nodejs-continuous_deployment_trigger_deployment](https://acquia.widen.net/content/a85ae59b-bfa3-4ca2-8d80-e405cf3ecad2/web/d558b_nodejs-continuous_deployment_trigger_deployment.jpg?w=1090&itok=nfiwGHGH) 4. After successful execution, verify the deployment task for your environment in the Cloud UI. ![nodejs-continuous_deployment_verify_deployment](https://acquia.widen.net/content/171af6a5-26d0-41ac-a6bb-a41d85beb508/web/fcb73_nodejs-continuous_deployment_verify_deployment.jpg?w=1090&itok=qBfhGBUv) Note You can use Code Studio for CI/CD. For more details, visit [Node.js Auto DevOps](/acquia-cloud-platform/add-ons/code-studio/nodejs-auto-devops "Node.js Auto DevOps").