Codefresh CLI Docker 镜像文档

一、镜像概述

Codefresh CLI Docker 镜像是预配置的容器化环境，用于运行 Codefresh 命令行工具（CLI）。Codefresh 是一款云原生 CI/CD 平台，CLI 工具提供了与 Codefresh 平台交互的命令行接口，支持流水线管理、构建执行、部署操作等核心功能。该镜像无需本地安装 CLI，可直接通过 Docker 容器快速启动并使用，简化环境配置流程。

二、核心功能与特性

核心功能

• 与 Codefresh 平台 API 直接交互，执行全生命周期操作（如流水线创建/查询/运行、构建日志查看、部署触发等）。
• 支持 CI/CD 流水线的批量管理（如导出/导入流水线配置、批量运行流水线）。
• 集成 Codefresh 生态工具（如 Helm、Kubernetes 等），支持云原生应用部署。
• 提供命令自动补全、输出格式化（JSON/YAML/表格）等增强功能。

特性

• 容器化运行：无需本地安装 CLI，直接通过 Docker 启动，跨平台兼容性强。
• 轻量级：基于 Alpine Linux，镜像体积小，启动速度快。
• 版本可控：支持指定镜像标签（如 latest、v0.145.0 等），确保环境一致性。
• 安全认证：通过环境变量或配置文件传递 API 密钥，无需手动输入认证信息。

三、使用场景

1. 本地开发与调试：开发者无需安装 CLI，直接通过 Docker 运行命令，快速测试流水线配置或触发构建。
2. CI/CD 管道集成：在第三方 CI 系统（如 Jenkins、GitLab CI）中嵌入 Codefresh CLI 命令，实现跨平台流水线联动。
3. 自动化脚本：在 Shell/Python 等脚本中调用 Docker 容器执行 Codefresh 操作，简化自动化流程。
4. 多环境隔离：通过不同容器实例配置不同 API 密钥，实现多 Codefresh 账户/环境的并行操作。

四、使用方法

4.1 安装与运行

前提条件

• 已安装 Docker 环境（Docker Engine 19.03+）。
• 拥有 Codefresh 账户及 API 密钥（获取路径：Codefresh 控制台 → 用户设置 → API 密钥）。

基础运行命令

通过 docker run 直接启动 CLI 容器，执行命令：

docker run --rm -it codefresh/cli [COMMAND]

• --rm：容器退出后自动删除，避免残留。
• -it：交互式终端，支持命令行输入。
• codefresh/cli：默认使用 latest 标签，可指定版本（如 codefresh/cli:v0.145.0）。

配置认证

通过环境变量 CODEFRESH_API_KEY 传递 API 密钥，无需手动登录：

docker run --rm -it -e CODEFRESH_API_KEY=<your-api-key> codefresh/cli [COMMAND]

替代方案：挂载本地配置文件（~/.codefresh/config.yaml）持久化认证信息：

docker run --rm -it -v ~/.codefresh/config.yaml:/root/.codefresh/config.yaml codefresh/cli [COMMAND]

4.2 常用命令示例

1. 验证 CLI 版本

docker run --rm codefresh/cli version

2. 列出所有流水线

docker run --rm -e CODEFRESH_API_KEY=<your-api-key> codefresh/cli get pipelines

3. 运行指定流水线

docker run --rm -e CODEFRESH_API_KEY=<your-api-key> codefresh/cli run <pipeline-name> --branch main

• <pipeline-name>：流水线名称（可通过 get pipelines 获取）。
• --branch：指定代码分支（可选，默认使用流水线配置的分支）。

4. 查看流水线运行日志

docker run --rm -e CODEFRESH_API_KEY=<your-api-key> codefresh/cli logs <build-id>

• <build-id>：流水线运行实例 ID（可通过 get builds 获取）。

5. 导出流水线配置

docker run --rm -e CODEFRESH_API_KEY=<your-api-key> codefresh/cli export pipeline <pipeline-name> > pipeline-config.yaml

五、配置参数

环境变量

配置文件

默认配置文件路径：/root/.codefresh/config.yaml（容器内路径）。可通过本地挂载持久化配置：

-v /local/path/to/config.yaml:/root/.codefresh/config.yaml

六、注意事项

1. API 密钥安全：避免在命令行直接暴露 API 密钥，建议通过环境变量文件（如 .env）传递：

   docker run --rm -it --env-file .env codefresh/cli get pipelines
   

   （.env 文件内容：CODEFRESH_API_KEY=<your-api-key>）

2. 权限问题：挂载本地文件时，确保容器内用户（默认 root）对挂载路径有读写权限，避免配置文件无法保存。

3. 版本兼容性：使用特定版本标签（如 v0.145.0）确保 CLI 功能与 Codefresh 平台版本兼容，避免因版本差异导致命令失效。

4. 网络代理：若需通过代理访问 Codefresh 平台，可通过 --env HTTP_PROXY=... 或 --env HTTPS_PROXY=... 配置代理环境变量。

七、参考链接

• Codefresh CLI 官方文档
• Codefresh API 密钥获取指南
• Codefresh CLI Docker 镜像仓库