holmusk/pi-haskell-ci

haskell-ci-pi 镜像文档

镜像概述

haskell-ci-pi 是一个专为PI仓库设计的Haskell项目持续集成(CI)工具镜像。该镜像基于Haskell官方环境构建，集成了GHC编译器、Cabal/Stack构建工具及CI流程所需的自动化脚本，旨在简化Haskell项目在PI仓库中的CI/CD流程，实现代码拉取、依赖管理、构建、测试及报告生成的全自动化。

核心功能与特性

核心功能

• 自动化构建：支持从PI仓库拉取Haskell项目代码，自动执行Cabal/Stack构建命令，处理项目依赖解析与编译。
• 自动化测试：集成Haskell测试框架（如HUnit、tasty），可配置自定义测试命令，自动执行项目测试用例并生成测试报告。
• 依赖管理：内置Haskell依赖缓存机制，加速重复构建过程，支持指定依赖源（如Hackage、本地仓库）。
• PI仓库集成：原生支持与PI仓库的权限认证（如SSH密钥、访问令牌），可直接拉取指定分支/标签的代码。

特性

• 轻量级：基于Alpine或Debian slim基础镜像，最小化镜像体积，减少资源占用。
• 可定制：支持通过环境变量或配置文件自定义构建/测试流程，适配不同项目需求。
• 多版本支持：提供多个标签版本，对应不同GHC编译器版本（如ghc-9.2、ghc-9.4），满足不同Haskell项目的兼容性需求。

使用场景与适用范围

适用场景

• Haskell开发者在PI仓库中托管项目，需实现代码提交后的自动化构建与测试。
• 需要在PI仓库中搭建Haskell项目的CI/CD流水线，实现"提交即测试"的开发流程。
• 对Haskell项目构建流程进行标准化管理，确保团队成员提交的代码符合项目构建规范。

适用范围

• 基于Cabal或Stack构建的Haskell项目。
• 托管于PI仓库（如企业内部PI代码仓库、私有GitLab/Gitea等兼容PI协议的仓库）的项目。
• 需要自动化处理依赖安装、代码编译、单元测试、集成测试的Haskell应用或库。

使用方法与配置说明

基本使用（docker run 命令）

拉取镜像

bash
docker pull haskell-ci-pi:latest  # 最新稳定版
# 或指定GHC版本
docker pull haskell-ci-pi:ghc-9.4

执行CI流程

bash
docker run -it --rm \
  -e PI_REPO_URL="https://pi-repo.example.com/haskell-project.git" \  # PI仓库URL
  -e BRANCH="main" \  # 构建分支
  -e BUILD_CMD="cabal build --enable-tests" \  # 构建命令
  -e TEST_CMD="cabal test all" \  # 测试命令
  -v /path/to/ssh-key:/root/.ssh/id_rsa:ro \  # 挂载SSH密钥（若仓库需SSH认证）
  -v $(pwd)/ci-output:/ci/output \  # 挂载输出目录（存放构建/测试报告）
  haskell-ci-pi:latest

环境变量配置

docker-compose 配置示例

创建 docker-compose.yml 文件：

yaml
version: '3'
services:
  haskell-ci:
    image: haskell-ci-pi:ghc-9.4
    environment:
      - PI_REPO_URL=https://pi-repo.example.com/haskell-project.git
      - BRANCH=dev
      - BUILD_CMD=stack build --resolver lts-20.3
      - TEST_CMD=stack test
      - OUTPUT_REPORT=true
      - REPORT_FORMAT=html
    volumes:
      - ./ssh-key:/root/.ssh/id_rsa:ro
      - ./ci-reports:/ci/output
    restart: no

执行命令启动CI流程：

bash
docker-compose up

注意事项

1. 仓库认证：若PI仓库需认证，需通过挂载SSH密钥（如示例中的/path/to/ssh-key）或设置环境变量PI_ACCESS_TOKEN（适用于HTTP/HTTPS认证）。
2. 依赖缓存：首次运行会下载项目依赖，耗时较长；后续运行可通过挂载CACHE_DIR目录复用缓存，加速构建。
3. 版本兼容性：需根据项目使用的GHC版本选择对应镜像标签（如项目使用GHC 9.2，选择haskell-ci-pi:ghc-9.2）。