# CI/CD on Acquia

**Goal:** pick the right CI/CD surface for each workload and run it well: [Pipelines](/start-here/glossary/#pipelines) for Cloud Platform work, your own CI for [Front End Hosting](/start-here/glossary/#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](/start-here/glossary/#build-artifact) 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](/start-here/glossary/#application-cloud-platform) ([code-workflow quickstart](/cloud-platform/code-workflow/quickstart/)) or a Front End Hosting frontend ([deploy from your own CI/CD](/source-cms/deploy/external-ci/))
- Somewhere your source lives: the Cloud Platform repository or an external git host (GitHub)

## Steps

<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](/source-cms/deploy/external-ci/#deploying-a-drupal-application-this-way) instead |
   | Front End Hosting frontend | **Your own CI** ([guide](/source-cms/deploy/external-ci/)) or **[Code Studio](/start-here/glossary/#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](/start-here/glossary/#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](https://docs.acquia.com/acquia-cloud-platform/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](/start-here/glossary/#environment) at that branch (`Switch code`), exactly as in the [code-workflow guide](/cloud-platform/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](https://docs.acquia.com/acquia-cloud-platform/connecting-pipelines-your-github-repo) on docs.acquia.com. Cloud Platform installs the webhooks.
   - **The `pipelines start` CLI** (a separate client from [acli](/start-here/glossary/#acli); see [which CLI?](/cloud-platform/cli/#which-cli-do-i-use)).
   - **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](/cloud-platform/ci-cd/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](/source-cms/authenticate/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:

   ```bash
   pipelines encrypt 'the-secret-value'
   ```

   ```yaml
   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](https://docs.acquia.com/acquia-cloud-platform/creating-and-managing-your-build-definition-file#section-ssh-keys) 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](/source-cms/deploy/external-ci/) has the full workflow, including multiple environments and a gated production deploy.

</Steps>

## Promote through environments

The promotion pattern is CI-independent, and it's the same one the [code-workflow guide](/cloud-platform/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:

```bash
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](/source-cms/deploy/external-ci/#multiple-environments-and-a-production-gate)).
- With **Code Studio**, `ACQUIA_JOBS_DEPLOY_TAG_ARTIFACT` deploys tag artifacts.

Whichever surface, keeping distinct per-tag artifacts is what makes [rollback](/cloud-platform/code-workflow/guide/#roll-back-a-release) 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](/source-cms/deploy/external-ci/#multiple-environments-and-a-production-gate)).

## 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](/source-cms/deploy/external-ci/#multiple-environments-and-a-production-gate). 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](/cloud-platform/ci-cd/quickstart/): your first green run.
- [Creating and managing your build definition file](https://docs.acquia.com/acquia-cloud-platform/creating-and-managing-your-build-definition-file) on docs.acquia.com: every key of the build definition file.
- [Deploy from your own CI/CD](/source-cms/deploy/external-ci/): the Front End Hosting artifact flow from your own CI, end to end.