Quickstart

Goal: run the Cloud Platform deploy loop end to end once: local change, git push, verified on a dev environment.

What you’ll have when you’re done

• Your application’s codebase cloned locally from its Acquia repository.
• One deliberately boring change (a static text file in the webroot) live on the dev environment.
• The mental model that everything else builds on: environments deploy the branch they track, and pushing to that branch deploys it.

The change is a static file, not application code, so the deploy loop stays visible without any module or theme work. For Drupal development itself, see drupal.org/docs.

Prerequisites

• Access to at least one Cloud Platform application (which path am I on?), with a codebase in its repository. No application? A self-serve Cloud Platform free trial provisions one with its codebase already in place; an application whose repository is empty needs set up a codebase first
• acli installed and authenticated (the CLI quickstart gets you there in under 10 minutes)
• git, and an SSH key registered with Acquia. If you haven’t registered one: acli ssh-key:create-upload generates a key if needed and registers it, walking you through both.
• Optional: jq, the standard JSON filter. Step 1 uses it to pull one field out of an API response; every such command also states how to read the field without it.

Steps

1. Find your application’s repository URL

   Already have the code checked out from setting up local development? That is this same repository: cd into it and start at step 3.

   Every Cloud Platform application has a git repository managed by Acquia. Ask any of the application’s environments for it:

   acli api:environments:find myapp.dev | jq -r '.vcs.url'

   The URL looks like:

   [email protected]:myapp.git

   jq is the standard JSON filter; without it, run the command without the pipe and read the vcs.url field out of the JSON. The application’s overview page at cloud.acquia.com shows the same URL.

   myapp.dev above is an application alias plus an environment name. To confirm which applications you have access to:

   acli api:applications:list

2. Clone it and look around

   git clone [email protected]:myapp.git
   cd myapp

   The one directory that matters right now is docroot/: Cloud Platform serves the site from it. The code-workflow guide covers the full expected layout.

3. Check which branch the dev environment tracks

   Each environment deploys one branch (or tag), and one command prints the lot:

   acli app:vcs:info myapp --deployed

   The output is a table with one row per deployed branch or tag: the name, whether it is deployed, and the environment it is deployed to. Take the name from the row whose environment is Dev (commonly something like dev or master). The Dev environment card in the Cloud Platform user interface shows the same branch. The steps below use dev; if your row named something else, put that name wherever dev appears.

   Check out the branch:

   git checkout dev

   If DDEV is running the site from this checkout, it serves whichever branch is checked out; nothing needs restarting for the file in the next step, which the web server reads straight from disk.

4. Make a change you can verify from a browser

   A static file in the webroot is served directly by the environment (no Drupal code involved, no cache in the way). That is the point of it here: this run tests the path from your machine to the environment, so the change is one Drupal cannot get in front of. Your own work then travels the same way.

   echo "deployed from my machine $(whoami)" \
     > docroot/hello-acquia.txt
   git add docroot/hello-acquia.txt
   git commit -m "Test the deploy loop"

   Running the site locally? docroot/ is the webroot DDEV serves as well, so https://myapp.ddev.site/hello-acquia.txt shows the file before you push it, and the same path on the environment shows it after.

5. Push, and let the environment deploy it

   git push origin dev

   Pushing to the branch an environment tracks deploys it; that push is the deploy. Watch the task appear in the Cloud UI’s task log for the environment.

6. Verify it on the environment

   Ask the environment for its hostname:

   acli api:environments:find myapp.dev | jq -r '.default_domain'

   myappdev.prod.acquia-sites.com

   Without jq, read the default_domain field out of the JSON. The environment card shows the same URL. Fetch your file from it:

   curl \
   https://myappdev.prod.acquia-sites.com/hello-acquia.txt

   deployed from my machine lauri

   That’s the whole loop. Real work replaces the text file with code changes; the push-deploy mechanics never change. Clean up with git revert HEAD && git push origin dev (revert, not reset: the branch is deployed, so history must move forward).

When something goes wrong

Permission denied (publickey) on clone or push

your SSH key isn’t registered with Acquia, or the wrong key is offered. Run acli ssh-key:create-upload to generate and register one. To see which keys were offered, run ssh -vT [email protected] (the user@host part of your git URL) and look for the Offering public key lines.

The push succeeds but nothing deploys

you pushed a branch no environment tracks. Compare your branch name against acli app:vcs:info myapp --deployed (or the environment card in the Cloud UI); either push to the tracked branch or switch the environment onto yours with acli api:environments:code-switch myapp.dev my-branch --task-wait, the command behind Switch code on the environment card. A tag goes in prefixed, "tags/my-tag"; a branch name goes in bare.

The file 404s after the task completes

check the file landed under docroot/ (not the repo root); only the webroot is served.

Next steps

• Your first Pipelines run: make pushes build, test, and deploy themselves.
• Code-workflow guide: repo layout, environments, moving databases and files, remote drush.
• Set up local development: run the site on your machine with pulled data.