Set up a codebase

Goal: your Cloud Platform application’s Git repository contains a Drupal codebase, so the deploy loop has something to deploy.

What you’ll have when you’re done

• A Drupal codebase in the application’s Acquia-managed repository, laid out the way the platform expects.
• The right next page for your situation: the quickstart for daily work, or the migration guide if data still lives elsewhere.

Prerequisites

• acli installed and authenticated (CLI quickstart), and an SSH key registered (acli ssh-key:create-upload handles both generation and registration)
• Composer, and a PHP whose extensions include what Drupal core requires (gd among them; Drupal’s system requirements has the full list): the scaffold in step 2 shells out to composer create-project, which stops partway through without them
• For the With an AI agent tabs: an agentic CLI (Claude Code, Cursor, OpenCode, Codex) running in the project, using the acli credentials above. Acquia Skills sharpens how agents map intent onto acli, but the prompts below carry enough detail to work without it.

Steps

1. Pick your starting point

   • Your team already has code in the application. There is nothing to set up: go straight to the quickstart.
   • You have a Drupal site running somewhere else. That is a full move of code, database, and files rather than a fresh codebase: follow Migrate an existing site.
   • You’re starting a new project. Continue below.

2. Scaffold the project

   Yourself

   acli app:new:local myapp --template=acquia_drupal_recommended

   With an AI agent

   > Scaffold a new Drupal project named myapp with acli,
   > using the acquia_drupal_recommended template.

   The agent runs the same acli app:new:local command shown on the Yourself tab; approve it when prompted.

   This generates a Drupal project already laid out for Acquia hosting: docroot/ as the webroot, Composer-managed dependencies (--template=acquia_drupal_cms scaffolds Drupal CMS instead). The code-workflow guide explains why that layout is the platform’s fixed contract.

3. Connect the application and push a built artifact

   Link the project to your Cloud Platform application, then build and push a deploy artifact:

   Yourself

   acli app:link myapp
   acli push:artifact myapp.dev

   With an AI agent

   > Link this project to my Cloud Platform application, then
   > build a code artifact with acli and push it to the dev
   > environment.

   The agent runs the same acli app:link and acli push:artifact commands shown on the Yourself tab; approve them when prompted.

   A plain git push cannot be the first deploy here: environments run built code, and the scaffold’s .gitignore keeps the built parts out of the repository (/vendor/, /docroot/core, the contrib directories, even the scaffolded docroot/index.php). A bare push would deploy a webroot with no Drupal in it. push:artifact closes that gap: it runs composer install, commits the built result (vendor directories and scaffold files included, even though the source ignores them), and pushes it to the application’s repository.

   Pointed at myapp.dev, push:artifact pushes the artifact to the branch the dev environment has deployed, and pushing to a deployed branch deploys it. acli app:vcs:info myapp --deployed prints which branch or tag each environment has deployed, as does the environment card in the Cloud Platform user interface.

4. Verify the environment picked it up

   Watch the deploy task appear in the environment’s task log, then open the dev environment’s URL from its environment card. A freshly deployed artifact serves Drupal’s installer, because the codebase (dependencies included) is there but the site isn’t installed yet; seeing the installer means code is flowing.

5. Install locally, then push the database up

   Install the site on your machine, not on the environment. A remote site:install would generate a site whose configuration has a fresh UUID unconnected to your repository, and the first drush config:import after that fails on the mismatch. Installing locally keeps the site’s configuration and the codebase the same lineage from the start.

   Bring the scaffold up locally first (the local development quickstart installs DDEV in step 1 and configures the project in step 3), install Drupal, and export its configuration into the repository:

   ddev start
   ddev drush site:install --yes \
     --account-name=admin --account-pass=CHOOSE_A_PASSWORD
   ddev drush config:export --yes
   git add config && git commit -m "Add initial configuration"
   acli push:artifact myapp.dev

   Then copy the installed database to the environment:

   Yourself

   acli push:database myapp.dev

   With an AI agent

   > Push my local database to the dev environment with acli.

   The agent runs the same acli push:database command shown on the Yourself tab; approve it when prompted.

   push:database overwrites the target environment’s database, so it is safe here (the environment has no site yet) and needs care later. Reload the environment URL and the site answers instead of the installer.

When something goes wrong

Permission denied (publickey) on push

your SSH key isn’t registered with Acquia, or the wrong key is offered. acli ssh-key:create-upload generates and registers one; the quickstart’s troubleshooting entry shows how to see which keys were tried.

The push succeeds but nothing deploys

the artifact went to a branch no environment tracks. acli push:artifact myapp.dev targets the branch the dev environment has deployed, so this usually follows a push with --destination-git-branch to a new branch name. Compare that branch name against acli app:vcs:info myapp --deployed (or the environment card), and point the environment at it with acli api:environments:code-switch myapp.dev my-branch --task-wait, the command behind Switch code on the card.

No installer, and nothing Drupal answers, after deploying with plain git push

a plain push deploys only what git tracks, and the scaffold’s .gitignore excludes /vendor/, /docroot/core, and the scaffolded docroot/index.php, so the environment received a webroot with no Drupal entry point. Deploy with acli push:artifact myapp.dev (step 3) and reload.

remote:drush fails with pcntl_exec(): ... Permission denied

the environment restricts PHP process execution, so the Drush launcher can’t hand off. Run drush.php through PHP over SSH instead, as running Drush remotely shows.

Next steps

• Quickstart: ship a change: run the full deploy loop once, end to end.
• Code-workflow guide: the layout contract, branches and tags, moving data, remote drush.
• Manage configuration: where the config:export from step 5 belongs in the repository, and how it gets imported on every later deploy.
• Set up local development: run the new site on your machine.