CircleCI CLI Docker镜像文档

镜像概述和主要用途

CircleCI CLI Docker镜像是预打包的CircleCI命令行工具环境，提供了与CircleCI平台交互的完整功能集。该镜像封装了所有依赖，无需在本地系统安装额外软件，即可便捷地与CircleCI工作流交互。主要用于本地开发调试、CI/CD流程集成、CircleCI配置验证和作业执行。

核心功能和特性

核心功能

• 配置验证：通过circleci config validate检查.circleci/config.yml文件语法和逻辑正确性
• 本地作业执行：使用circleci local execute在本地环境模拟CircleCI作业运行，复现CI环境问题
• 工作流管理：查看、触发和取消CircleCI工作流，获取实时构建状态
• 上下文与环境变量管理：创建、更新和删除CircleCI上下文，管理环境变量
• 构建日志与详情：获取历史构建日志、作业详情和性能数据

特性

• 零依赖：无需本地安装Go或其他系统依赖，直接通过Docker运行
• 跨平台兼容：支持Linux、macOS和Windows系统的Docker环境
• 版本化：提供多个镜像标签（如latest、v0.1.200），确保环境一致性
• 安全认证：支持通过API令牌（API Token）安全认证，与CircleCI平台无缝对接

使用场景和适用范围

适用场景

• 本地开发调试：开发阶段验证CircleCI配置，避免提交后构建失败
• CI/CD流程集成：在自动化管道中嵌入CLI命令，实现配置验证、工作流触发等操作
• 多环境一致性：确保开发、测试和生产环境使用相同版本的CLI工具
• 培训与演示：快速搭建CircleCI CLI环境，用于团队培训或功能演示

适用人群

• CircleCI用户（开发者、DevOps工程师）
• 需要本地调试CI/CD流程的开发团队
• 自动化脚本编写者（集成CircleCI操作到自定义工作流）

使用方法和配置说明

前提条件

• 安装Docker Engine（20.10+推荐）
• 获取CircleCI API令牌（在CircleCI账户设置 > API访问令牌中生成）

基本使用步骤

1. 拉取镜像

docker pull circleci/circleci-cli:latest

2. 验证配置文件

挂载包含.circleci/config.yml的目录，验证配置语法：

docker run --rm -v $(pwd):/workspace circleci/circleci-cli \
  config validate /workspace/.circleci/config.yml

3. 本地执行作业

通过API令牌认证，并在本地运行指定作业（需挂载项目目录和缓存卷）：

docker run --rm \
  -e CIRCLECI_API_TOKEN=<your-api-token> \
  -v $(pwd):/workspace \
  -v circleci-cache:/root/.circleci \
  circleci/circleci-cli \
  local execute --job <job-name> --workspace /workspace

4. 查看构建状态

获取指定项目的最近构建状态：

docker run --rm \
  -e CIRCLECI_API_TOKEN=<your-api-token> \
  circleci/circleci-cli \
  build list --project-slug github/<username>/<repo>

Docker Compose配置示例

创建docker-compose.yml简化常用操作：

version: '3'
services:
  circleci-cli:
    image: circleci/circleci-cli:latest
    environment:
      - CIRCLECI_API_TOKEN=${CIRCLECI_API_TOKEN}
    volumes:
      - .:/workspace
      - circleci-cache:/root/.circleci
    working_dir: /workspace

volumes:
  circleci-cache:

使用示例：

# 验证配置
docker-compose run --rm circleci-cli config validate .circleci/config.yml

# 本地执行作业
docker-compose run --rm circleci-cli local execute --job test

环境变量配置

常用命令参考

注意事项

• 本地作业执行需确保Docker资源充足（推荐4GB+内存）
• 自托管CircleCI Server用户需设置CIRCLECI_HOST指向私有服务器地址
• 敏感信息（如API令牌）避免硬编码，建议通过环境变量或 secrets 管理工具注入
• 缓存卷（circleci-cache）用于存储认证信息和依赖，避免重复认证和下载