CircleCI辅助工具镜像文档

1. 镜像概述

本Docker镜像为CircleCI（持续集成/持续部署平台）提供辅助功能，旨在简化CI/CD流程中的任务执行、配置管理及环境准备等操作，帮助开发团队更高效地实现自动化构建、测试与部署。

2. 核心功能与特性

2.1 轻量级设计

基于精简基础镜像构建，体积小巧，启动快速，减少CI/CD流程中的资源占用。

2.2 任务执行简化

内置常用CI/CD任务处理逻辑，支持直接调用CircleCI API执行工作流、触发构建等操作，减少手动配置步骤。

2.3 配置管理支持

提供配置文件解析与生成工具，可快速整合项目CI/CD配置，支持多环境配置模板复用。

2.4 跨平台兼容性

兼容主流Linux架构，可在各类容器化环境中稳定运行，适配不同CI/CD基础设施。

3. 使用场景和适用范围

3.1 典型使用场景

• CircleCI流程中的自动化测试任务执行
• 构建流程中的前置/后置任务处理（如依赖安装、资源清理）
• 部署前环境检查与配置准备
• 多环境（开发、测试、生产）CI/CD配置管理

3.2 适用范围

适用于需要简化CircleCI流程配置、提升任务执行效率的开发团队，尤其适合中小型项目及需要快速迭代的CI/CD场景。

4. 使用方法和配置说明

4.1 基本使用

4.1.1 直接运行（docker run）

docker run --rm -e CIRCLECI_TOKEN=<your-circleci-token> circleci-helper:latest <command>

• <your-circleci-token>：CircleCI API访问令牌，用于鉴权操作
• <command>：需执行的具体任务命令（如trigger-pipeline、validate-config等）

4.1.2 示例：触发CircleCI工作流

docker run --rm \
  -e CIRCLECI_TOKEN=your_token_here \
  -e PROJECT_SLUG=gh/your-org/your-repo \
  -e BRANCH=main \
  circleci-helper:latest trigger-pipeline

4.2 环境变量配置

4.3 docker-compose配置示例

version: '3'
services:
  circleci-helper:
    image: circleci-helper:latest
    environment:
      - CIRCLECI_TOKEN=your_token_here
      - PROJECT_SLUG=gh/your-org/your-repo
      - BRANCH=develop
    volumes:
      - ./custom-config:/app/config  # 挂载自定义配置目录
    command: validate-config  # 执行配置验证命令

4.4 自定义配置

可通过挂载配置目录（如-v ./custom-config:/app/config）覆盖默认配置，支持自定义任务模板、环境变量映射规则等。配置文件采用YAML格式，示例：

# custom-config/config.yml示例
pipeline:
  triggers:
    - event: push
      branch: [main, develop]
  jobs:
    - name: test
      command: ./run-tests.sh
    - name: build
      command: ./build-app.sh

5. 注意事项

• 使用前需确保CircleCI API令牌具有足够权限（如触发工作流、读取项目配置等）
• 自定义配置文件需符合YAML语法规范，避免格式错误导致任务执行失败
• 镜像定期更新，建议使用指定版本标签（如circleci-helper:1.0.0）以确保环境稳定性