CI/CD on Acquia

Goal: pick the right CI/CD surface for each workload and run it well: Pipelines for Cloud Platform work, your own CI for Front End Hosting frontends, with promotion and governance patterns that hold regardless of tool.

What you’ll have when you’re done

• The per-workload recommendation and why it splits that way.
• A working model of Pipelines: the build definition file, what triggers runs, where artifacts land, and how secrets stay secret.
• Your frontend deploys routed to the right guide.
• A promotion model (branches to Dev/Stage, tags to Prod) and the three governance controls, independent of CI tool.

Prerequisites

• A Cloud Platform application (code-workflow quickstart) or a Front End Hosting frontend (deploy from your own CI/CD)
• Somewhere your source lives: the Cloud Platform repository or an external git host (GitHub)

Steps

1. Pick the surface for the workload, not the other way around

   Workload	Recommendation	Why
   Cloud Platform (Drupal) CI	Pipelines	Acquia’s own CI for Cloud Platform applications: builds run against your application, artifacts land in its git repository, no third-party CI account needed. If you already run your own CI, it can build and push a Drupal artifact instead
   Front End Hosting frontend	Your own CI (guide) or Code Studio, equal alternatives	A Front End Hosting deploy is a prebuilt artifact plus one API call; any CI you already run does it directly, and Code Studio’s Node.js jobs do the same. Pipelines does not build Front End Hosting artifacts today
   Teams already on Code Studio	Stay on Code Studio	Auto DevOps keeps working; no need to migrate, but don’t start new projects on it

2. Know how a Pipelines run works

   Pipelines reads one file, acquia-pipelines.yaml, at the root of the branch being built (full schema: Creating and managing your build definition file on docs.acquia.com). The required build event holds script steps; a run executes them in a managed container and, on success, commits the result to a build branch named pipelines-build-[BRANCHNAME] in your application’s Cloud Platform repository. Deploying is then the standard code move: point an environment at that branch (Switch code), exactly as in the code-workflow guide.

   Three things trigger a run:

   • Git events on a connected repository: creating or reopening a pull request, pushing a commit, or pushing a tag. Connecting your GitHub repository is an OAuth authorization, done in the Cloud UI; for that flow, see Connecting Pipelines to your GitHub repo on docs.acquia.com. Cloud Platform installs the webhooks.
   • The pipelines start CLI (a separate client from acli; see which CLI?).
   • The Cloud UI, manually, from the application’s Pipelines section.

   There is no public trigger URL: runs start from git events, the CLI, or the UI. The quickstart walks the first green run end to end.

3. Keep secrets out of the build definition file

   The same storage rule as the auth guide: no credentials in committed files. Pipelines’ mechanism is encryption at rest in the YAML. Run a value through pipelines encrypt and commit only the ciphertext under a secure key:

   pipelines encrypt 'the-secret-value'

   variables:
     global:
       ADMIN_PASSWORD:
         secure: 2aciWcRBNXrG/KcWG1bb0uSRTOVoiDl...

   The job decrypts it at runtime; the repository never holds the plaintext. Private-repo SSH keys use the same pattern under the ssh-keys key (Creating and managing your build definition file on docs.acquia.com).

4. Route frontend deploys to your own CI

   Front End Hosting frontends deploy with the prebuilt-artifact flow from whatever CI you already run: build, push the artifact to the Acquia git remote, trigger the switch via the Cloud Platform API. The bring-your-own (BYO) CI/CD guide has the full workflow, including multiple environments and a gated production deploy.

Promote through environments

The promotion pattern is CI-independent, and it’s the same one the code-workflow guide uses: branch builds feed the disposable environments, tags feed production, and no automatic path exists from “commit merged” to “production changed.” A push to main may deploy dev on its own; production waits for a deliberate act:

git tag v1.4.0
git push origin v1.4.0

Per surface, the mechanics:

• With Pipelines, a tag push on the connected repository builds a tag artifact you switch production to.
• With your own CI, the tag-triggered job gated by approval runs the switch call (BYO guide).
• With Code Studio, ACQUIA_JOBS_DEPLOY_TAG_ARTIFACT deploys tag artifacts.

Whichever surface, keeping distinct per-tag artifacts is what makes rollback a switch instead of a rebuild.

The BYO flow supports the strongest form of the pattern: build once, then promote the same stored artifact through Dev, Stage, and Prod approvals, so production receives exactly the bytes Stage verified (BYO guide).

Govern whatever surface you chose

Three controls keep a shared pipeline from letting one mistake reach production, whatever runs it:

• Protect the refs that deploy. Only designated people push the production branch or create release tags. (GitHub: protected branches + tag rulesets; Code Studio/GitLab: protected branches and tags.)
• Review before merge on anything that changes pipeline behavior: acquia-pipelines.yaml, acquia_config.yaml, and workflow files deserve the same review as application code.
• Restrict credential access. Deploy keys, API clients, and encrypted variables are readable by as few people as possible, and only injected into builds of protected refs. (GitHub: environment secrets with required reviewers; Code Studio: Protected variables.)

Tool-specific mechanics live on the page for that surface: BYO guide. For Pipelines, the refs live on your connected git host, so its host-side controls (GitHub’s) are the ones to set.

When something goes wrong

Event pr-merged failed, could not find the specified event. in a Pipelines job log after merging or closing a PR

harmless. Jobs start on PR merge/close even when your acquia-pipelines.yaml defines no pr-merged/pr-closed events, and exit with this message. Define the events only if you want work to happen then.

A Pipelines run fails after exactly 60 minutes

builds time out at 60 minutes, full stop. Trim the steps, cache dependencies inside the repository, or split work across events; there is no way to raise the ceiling.

The build branch (pipelines-build-*) doesn’t appear on the application

the run didn’t succeed (check the job log via pipelines logs or the UI), or the final build step never moved the built code into the docroot. The artifact must be deployable as-is.

Next steps

• Pipelines quickstart: your first green run.
• Creating and managing your build definition file on docs.acquia.com: every key of the build definition file.
• Deploy from your own CI/CD: the Front End Hosting artifact flow from your own CI, end to end.