pipeline-operations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pipeline Operations with Acquia Pipelines CLI

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

Use when:

Triggering a pipeline build
Checking pipeline job status or streaming logs
Terminating a running job
Encrypting pipeline variables or connecting GitHub

Use the Pipelines CLI to trigger, monitor, and manage CI/CD pipeline jobs on Acquia Cloud.

See Getting Started for installation, authentication, and finding your application ID.

适用场景：

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

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

有关安装、身份验证和查找应用ID的信息，请查看**入门指南**。

Starting a Pipeline Job

启动流水线作业

Important:
pipelines start
fires immediately — there is no confirmation prompt. Verify your application ID and target branch before running.

重要提示：
pipelines start
命令会立即执行——没有确认提示。请在运行前验证你的应用ID和目标分支。

Verify before starting

启动前验证

bash

undefined

bash

undefined

Confirm the application ID

确认应用ID

pipelines list-applications

Check whether a job is already running on the branch

检查分支上是否已有作业在运行

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


Proceed with `start` only after confirming the correct application and branch.

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


确认应用和分支正确后，再执行`start`命令。

Start for the current branch

为当前分支启动作业

Run from inside your git repository:

bash

pipelines start --application-id=1g2i3b4b5o6u7s

The CLI detects the current branch automatically.

在你的git仓库内运行：

bash

pipelines start --application-id=1g2i3b4b5o6u7s

CLI会自动检测当前分支。

Start for a specific branch

为指定分支启动作业

bash

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

bash

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

Start and write artifact to a deploy branch

启动作业并将构建产物推送到部署分支

bash

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

The build artifact is pushed to

deploy/my-branch

on success.

bash

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

构建成功后，产物会被推送到

deploy/my-branch

分支。

Start with environment variables

使用环境变量启动作业

bash

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

bash

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

Start and stream logs immediately

启动作业并立即流式查看日志

bash

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

bash

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

Start with log streaming delay

延迟流式查看日志启动作业

Useful when the build takes a moment to produce output:

bash

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

适用于构建需要一段时间才会输出内容的场景：

bash

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

Start with retry options

使用重试选项启动作业

Control how many times the log streaming retries on failure:

bash

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

控制日志流式传输失败时的重试次数：

bash

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

Start from an external (non-Acquia) repository

从外部（非Acquia）仓库启动作业

Use

--source-vcs-uri

to pull source code from a GitHub or other external repo, with

--source-key-path

pointing to the SSH private key for access:

bash

pipelines start \
  --application-id=1g2i3b4b5o6u7s \
  --source-vcs-uri=git@github.com:myorg/myrepo.git \
  --source-key-path=~/.ssh/id_rsa \
  --vcs-path=main

Note: Pass the private key path, not the
.pub
file.

使用

--source-vcs-uri

从GitHub或其他外部仓库拉取源代码，

--source-key-path

指向用于访问的SSH私钥：

bash

pipelines start \
  --application-id=1g2i3b4b5o6u7s \
  --source-vcs-uri=git@github.com:myorg/myrepo.git \
  --source-key-path=~/.ssh/id_rsa \
  --vcs-path=main

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

Start with container kept alive for debugging

启动作业并保持容器存活以进行调试

Keeps the build container running after the job completes so you can SSH in to debug:

bash

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

You will be prompted to confirm before the build starts.

作业完成后保持构建容器运行，以便你通过SSH进入调试：

bash

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

构建启动前会提示你确认。

Start using a codebase ID instead of application ID

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

bash

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

Output on success:

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

bash

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

Checking Job Status

检查作业状态

Check status of the latest job

检查最新作业状态

bash

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

bash

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

Check status for a specific job

检查指定作业状态

bash

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

bash

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

Check status of latest job on a specific branch

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

bash

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

Output:

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)

Possible status values:

succeeded

aborted

system failure

build error

queued

running

paused

bash

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

。

Machine-readable JSON output

机器可读的JSON格式输出

bash

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

bash

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

Viewing Logs

查看日志

View logs for the latest job

查看最新作业日志

bash

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

bash

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

View logs for a specific job

查看指定作业日志

bash

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

bash

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

Stream (tail) logs live

实时流式查看日志

bash

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

bash

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

Save logs to file

将日志保存到文件

bash

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

bash

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

Listing Jobs

列出作业

bash

pipelines list-jobs 1g2i3b4b5o6u7s

Output lists recent jobs with their IDs, statuses, and branches.

bash

pipelines list-jobs 1g2i3b4b5o6u7s

输出会列出近期作业的ID、状态和分支信息。

Terminating a Job

终止作业

Cancel a running job:

bash

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

取消运行中的作业：

bash

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

Encrypting Pipeline Variables

加密流水线变量

Encrypt sensitive values for use in

acquia-pipelines.yml

bash

pipelines encrypt

You will be prompted for the confidential data. Paste the encrypted output into your

acquia-pipelines.yml

file.

加密敏感值以在

acquia-pipelines.yml

中使用：

bash

pipelines encrypt

系统会提示你输入机密数据。将加密后的输出粘贴到

acquia-pipelines.yml

文件中。

Container Configuration

容器配置

Container configuration for Acquia Pipelines is defined in

acquia-pipelines.yml

at the root of your repository. The

pipelines start

command picks this file up automatically — there are no CLI flags for container settings.

Acquia Pipelines的容器配置在仓库根目录的

acquia-pipelines.yml

文件中定义。

pipelines start

命令会自动读取该文件——没有用于容器设置的CLI参数。

Minimal configuration structure

最小配置结构

yaml

version: 1.1.0

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

yaml

version: 1.1.0

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

Configure the PHP version

配置PHP版本

Use the

services

key to pin the PHP version for the build container:

yaml

version: 1.1.0

services:
  - php:
      version: 8.2

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

Supported versions depend on your Acquia Cloud subscription. Common values:

8.1

8.2

8.3

使用

services

字段为构建容器指定PHP版本：

yaml

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

。

Add a MySQL service

添加MySQL服务

Include

mysql

under

services

when your build needs a database:

yaml

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 is available at

127.0.0.1:3306

with credentials

root:root

当构建需要数据库时，在

services

下添加

mysql

：

yaml

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

。

Set environment variables

设置环境变量

Declare plain-text variables in the

variables.global

section:

yaml

version: 1.1.0

variables:
  global:
    APP_ENV: ci
    PHP_MEMORY_LIMIT: 512M

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

For sensitive values, encrypt first with the CLI then paste the result:

bash

pipelines encrypt

在

variables.global

部分声明明文变量：

yaml

version: 1.1.0

variables:
  global:
    APP_ENV: ci
    PHP_MEMORY_LIMIT: 512M

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

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

bash

pipelines encrypt

Paste your secret value when prompted

提示时输入你的机密值

Copy the output — a long encoded string

复制输出——一段长编码字符串


Then reference it in the YAML:

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

The decrypted value is available as

$MY_SECRET

inside build steps.


然后在YAML中引用：

```yaml
variables:
  global:
    MY_SECRET:
      secure: <粘贴加密输出>

解密后的值可在构建步骤中通过

$MY_SECRET

访问。

Add SSH keys for private dependencies

添加SSH密钥用于私有依赖

If your build pulls from private repositories, add an encrypted SSH key:

bash

undefined

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

bash

undefined

Encrypt your private key

加密你的私钥

cat ~/.ssh/id_rsa | pipelines encrypt


Reference it in the YAML under `ssh-keys`:

```yaml
version: 1.1.0

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

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

The key is loaded automatically into the build container before steps run.

cat ~/.ssh/id_rsa | pipelines encrypt


在YAML的`ssh-keys`下引用：

```yaml
version: 1.1.0

ssh-keys:
  my-deploy-key:
    secure: <加密后的私钥>

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

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

Multi-service example (PHP + MySQL + Node)

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

yaml

version: 1.1.0

services:
  - php:
      version: 8.2
  - mysql

variables:
  global:
    APP_ENV: ci
    DB_URL: mysql://root:root@127.0.0.1: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

yaml

version: 1.1.0

services:
  - php:
      version: 8.2
  - mysql

variables:
  global:
    APP_ENV: ci
    DB_URL: mysql://root:root@127.0.0.1:3306/mydb
    NPM_TOKEN:
      secure: <加密后的令牌>

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

Validate your configuration before triggering

触发前验证配置

There is no

pipelines validate

command. Check for common issues manually:

bash

undefined

目前没有

pipelines validate

命令。手动检查常见问题：

bash

undefined

Confirm the file is valid YAML

确认文件是有效的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

确认文件已提交并推送——pipelines会读取远程分支的内容

git status acquia-pipelines.yml git push


Then trigger and stream logs to catch runtime errors immediately:

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

git status acquia-pipelines.yml git push


然后触发作业并流式查看日志，以便立即捕获运行时错误：

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

GitHub Integration

GitHub集成

Connect a GitHub repository

连接GitHub仓库

bash

pipelines github:connect

bash

pipelines github:connect

Disconnect a GitHub repository

断开GitHub仓库连接

bash

pipelines github:disconnect

bash

pipelines github:disconnect

CI/CD Integration

CI/CD集成

GitHub Actions — trigger and wait

GitHub Actions — 触发并等待

yaml

undefined

yaml

undefined

.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

undefined

name: Trigger Acquia Pipeline

on: push: branches: [main]

  - 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

undefined

Poll for status in a script

在脚本中轮询状态

bash

#!/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

bash

#!/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

Best Practices

最佳实践

Verify before starting — Always run
```
pipelines list-applications
```
to confirm the app ID before
```
pipelines start
```
.
Use
--tail
during development — Stream logs immediately so failures surface without a separate
```
logs
```
call.
Store credentials securely — Use
```
pipelines configure
```
to store credentials; never hardcode them in env vars or scripts.
Avoid duplicate runs — Check
```
pipelines status --job-id=latest
```
before re-triggering to avoid redundant builds.
Encrypt sensitive values — Use
```
pipelines encrypt
```
for any secrets referenced in
```
acquia-pipelines.yml
```
.

启动前验证 — 执行
```
pipelines start
```
前，务必运行
```
pipelines list-applications
```
确认应用ID。
开发时使用
--tail
— 立即流式查看日志，无需单独调用
```
logs
```
命令即可发现失败情况。
安全存储凭据 — 使用
```
pipelines configure
```
存储凭据；切勿在环境变量或脚本中硬编码。
避免重复运行 — 重新触发前检查
```
pipelines status --job-id=latest
```
，避免冗余构建。
加密敏感值 —
```
acquia-pipelines.yml
```
中引用的任何机密信息都要使用
```
pipelines encrypt
```
加密。

Troubleshooting

故障排查

Error	Cause	Solution
`Unable to authenticate`	Credentials not configured or expired	Run `pipelines configure` again
`No pipeline configuration found`	Missing `acquia-pipelines.yml` in repo	Add the build definition file and push
`The vcs branch does not exist in remote`	Branch not pushed to Acquia remote	Push the branch first: `git push acquia feature/my-branch`
`The build file has local uncommitted changes`	`acquia-pipelines.yml` has unsaved changes	Commit and push the build file
`Badly formed job`	Job ID is invalid or expired	Use `pipelines list-jobs` to find a valid job ID

错误	原因	解决方案
`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