pipeline-operations

使用 Acquia Pipelines CLI 执行流水线操作

适用于：

• 触发流水线构建
• 检查流水线作业状态或流式查看日志
• 终止正在运行的作业
• 加密流水线变量或连接 GitHub

使用 Pipelines CLI 在 Acquia Cloud 上触发、监控和管理 CI/CD 流水线作业。

请参阅 入门指南，了解安装、身份验证以及查找应用 ID 的方法。

---

启动流水线作业

重要： pipelines start 会立即启动作业，不会显示确认提示。运行前请核实应用 ID 和目标分支。

启动前核实

# Confirm the application ID
pipelines list-applications

# Check whether a job is already running on the branch
pipelines status --application-id=1g2i3b4b5o6u7s --job-id=latest

确认应用和分支无误后，再执行 start。

为当前分支启动

在 Git 仓库内运行：

pipelines start --application-id=1g2i3b4b5o6u7s

CLI 会自动检测当前分支。

为指定分支启动

pipelines start \
  --application-id=1g2i3b4b5o6u7s \
  --vcs-path=feature/my-branch

启动并将构建产物写入部署分支

pipelines start \
  --application-id=1g2i3b4b5o6u7s \
  --vcs-path=feature/my-branch \
  --deploy-vcs-path=deploy/my-branch

成功后，构建产物会推送到 deploy/my-branch。

使用环境变量启动

pipelines start \
  --application-id=1g2i3b4b5o6u7s \
  --vcs-path=main \
  -D MY_VAR=foo \
  -D ANOTHER_VAR=bar

启动并立即流式查看日志

pipelines start --application-id=1g2i3b4b5o6u7s --tail

启动并设置日志流延迟

适用于构建需要一些时间才会产生输出的情况：

pipelines start --application-id=1g2i3b4b5o6u7s --tail --delay=5

启动并设置重试选项

设置日志流在失败时的重试次数：

pipelines start \
  --application-id=1g2i3b4b5o6u7s \
  --retries=3 \
  --delay=5

从外部（非 Acquia）仓库启动

使用 --source-vcs-uri 从 GitHub 或其他外部仓库拉取源代码，并使用 --source-key-path 指定用于访问的 SSH 私钥：

pipelines start \
  --application-id=1g2i3b4b5o6u7s \
  [email protected]:myorg/myrepo.git \
  --source-key-path=~/.ssh/id_rsa \
  --vcs-path=main

注意：请传入私钥路径，而不是 .pub 文件路径。

启动并保持容器运行以便调试

作业完成后继续运行构建容器，以便通过 SSH 登录并进行调试：

pipelines start --application-id=1g2i3b4b5o6u7s --keep-process-alive

构建开始前，系统会提示你确认。

使用代码库 ID 而非应用 ID 启动

pipelines start \
  --codebase-id=abcd1234-5678-90ab-cdef-000000000000 \
  --vcs-path=main

成功时的输出：

Successfully started a build:
VCS path: main
Target deployment branch: pipelines-build-main
Job ID: job-abc12345

---

检查作业状态

检查最新作业的状态

pipelines status --application-id=1g2i3b4b5o6u7s --job-id=latest

检查指定作业的状态

pipelines status \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=job-abc12345

检查指定分支上最新作业的状态

pipelines status \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=latest:main

输出：

Job ID: job-abc12345
Status: succeeded
Summary:
Site: my-site
VCS path: main
Submitted: 2024-02-20 10:15:00 (UTC)
Started: 2024-02-20 10:15:05 (UTC)
Finished: 2024-02-20 10:18:34 (UTC)

可能的状态值：succeeded、aborted、system failure、build error、queued、running、paused。

输出机器可读的 JSON

pipelines status \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=latest \
  --format=json

---

查看日志

查看最新作业的日志

pipelines logs \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=latest

查看指定作业的日志

pipelines logs \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=job-abc12345

实时流式查看日志（tail）

pipelines logs \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=latest \
  --tail

将日志保存到文件

pipelines logs \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=latest > pipeline.log 2>&1

---

列出作业

pipelines list-jobs 1g2i3b4b5o6u7s

输出会列出近期作业及其 ID、状态和分支。

---

终止作业

取消正在运行的作业：

pipelines terminate-job \
  --application-id=1g2i3b4b5o6u7s \
  --job-id=job-abc12345

---

加密流水线变量

加密敏感值，以便在 acquia-pipelines.yml 中使用：

pipelines encrypt

系统会提示你输入机密数据。将加密后的输出粘贴到 acquia-pipelines.yml 文件中。

---

容器配置

Acquia Pipelines 的容器配置定义在仓库根目录下的 acquia-pipelines.yml 文件中。pipelines start 命令会自动读取此文件，CLI 没有用于配置容器设置的标志。

---

最简配置结构

version: 1.1.0

events:
  build:
    steps:
      - build:
          type: script
          script:
            - composer install

---

配置 PHP 版本

使用 services 键为构建容器指定 PHP 版本：

version: 1.1.0

services:
  - php:
      version: 8.2

events:
  build:
    steps:
      - composer:
          type: script
          script:
            - composer install --no-progress

支持的版本取决于你的 Acquia Cloud 订阅。常见值：8.1、8.2、8.3。

---

添加 MySQL 服务

构建需要数据库时，在 services 下添加 mysql：

version: 1.0.0

services:
  - mysql

events:
  build:
    steps:
      - build:
          type: script
          script:
            - mysql -u root -proot -e "CREATE DATABASE mydb"
            - composer install --no-interaction

MySQL 可通过 127.0.0.1:3306 访问，凭据为 root:root。

---

设置环境变量

在 variables.global 部分声明明文变量：

version: 1.1.0

variables:
  global:
    APP_ENV: ci
    PHP_MEMORY_LIMIT: 512M

events:
  build:
    steps:
      - build:
          type: script
          script:
            - composer install

对于敏感值，请先使用 CLI 加密，再粘贴加密结果：

pipelines encrypt
# Paste your secret value when prompted
# Copy the output — a long encoded string

然后在 YAML 中引用该值：

variables:
  global:
    MY_SECRET:
      secure: <paste encrypted output here>

解密后的值可在构建步骤中通过 $MY_SECRET 使用。

---

为私有依赖项添加 SSH 密钥

如果构建需要从私有仓库拉取内容，请添加加密的 SSH 密钥：

# Encrypt your private key
cat ~/.ssh/id_rsa | pipelines encrypt

在 YAML 的 ssh-keys 下引用它：

version: 1.1.0

ssh-keys:
  my-deploy-key:
    secure: <encrypted private key>

events:
  build:
    steps:
      - build:
          type: script
          script:
            - composer install

在运行步骤之前，密钥会自动加载到构建容器中。

---

多服务示例（PHP + MySQL + Node）

version: 1.1.0

services:
  - php:
      version: 8.2
  - mysql

variables:
  global:
    APP_ENV: ci
    DB_URL: mysql://root:[email protected]:3306/mydb
    NPM_TOKEN:
      secure: <encrypted token>

events:
  build:
    steps:
      - setup-db:
          type: script
          script:
            - mysql -u root -proot -e "CREATE DATABASE mydb"
      - backend:
          type: script
          script:
            - composer install --no-interaction
      - frontend:
          type: script
          script:
            - nvm install node
            - npm install
            - npm run build

---

触发前验证配置

没有 pipelines validate 命令。请手动检查常见问题：

# Confirm the file is valid YAML
python3 -c "import yaml,sys; yaml.safe_load(open('acquia-pipelines.yml'))" \
  && echo "Valid YAML" || echo "Parse error"

# Confirm it is committed and pushed — pipelines reads from the remote branch
git status acquia-pipelines.yml
git push

然后触发构建并实时输出日志，以便立即发现运行时错误：

pipelines start --application-id=<app-id> --tail

---

GitHub 集成

连接 GitHub 仓库

pipelines github:connect

断开 GitHub 仓库

pipelines github:disconnect

---

CI/CD 集成

GitHub Actions — 触发并等待

# .github/workflows/pipeline.yml
name: Trigger Acquia Pipeline

on:
  push:
    branches: [main]

jobs:
  pipeline:
    runs-on: ubuntu-latest
    steps:
      - name: Install Pipelines CLI
        run: |
          wget https://cloud.acquia.com/pipelines-client/download -O pipelines
          chmod +x pipelines
          sudo mv pipelines /usr/local/bin/pipelines

      - name: Configure credentials
        run: |
          echo "${{ secrets.PIPELINES_CONFIG }}" > ~/.pipelines-config

      - name: Start pipeline
        run: |
          pipelines start \
            --application-id=${{ vars.ACQUIA_APP_ID }} \
            --vcs-path=main \
            --tail

在脚本中轮询状态

#!/bin/bash
set -e

APP_ID="1g2i3b4b5o6u7s"
BRANCH="main"

echo "Starting pipeline..."
pipelines start --application-id=$APP_ID --vcs-path=$BRANCH

echo "Waiting for job to complete..."
while true; do
  STATUS=$(pipelines status \
    --application-id=$APP_ID \
    --job-id=latest:$BRANCH \
    --format=json | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")

  echo "Status: $STATUS"

  case "$STATUS" in
    succeeded)
      echo "Pipeline succeeded!"
      exit 0
      ;;
    "build error"|aborted|"system failure")
      echo "Pipeline failed: $STATUS"
      pipelines logs --application-id=$APP_ID --job-id=latest:$BRANCH
      exit 1
      ;;
  esac

  sleep 15
done

---

最佳实践

1. 启动前先确认 — 始终运行 pipelines list-applications，确认应用 ID 后再运行 pipelines start。
2. 开发期间使用 --tail — 立即实时输出日志，这样无需单独调用 logs，就能发现失败。
3. 安全存储凭据 — 使用 pipelines configure 存储凭据；切勿将其硬编码在环境变量或脚本中。
4. 避免重复运行 — 重新触发前检查 pipelines status --job-id=latest，避免重复构建。
5. 加密敏感值 — 对 acquia-pipelines.yml 中引用的所有机密使用 pipelines encrypt。

---

故障排除

错误	原因	解决方案
Unable to authenticate	未配置凭据或凭据已过期	再次运行 pipelines configure
No pipeline configuration found	仓库中缺少 acquia-pipelines.yml	添加构建定义文件并推送
The vcs branch does not exist in remote	分支尚未推送到 Acquia 远程仓库	先推送分支：git push acquia feature/my-branch
The build file has local uncommitted changes	acquia-pipelines.yml 有未保存的更改	提交并推送构建文件
Badly formed job	作业 ID 无效或已过期	使用 pipelines list-jobs 查找有效的作业 ID