cdignam/kodiak-web-api

Kodiak Docker镜像文档

镜像概述

Kodiak是一款专注于自动化GitHub Pull Request（PR）管理的工具，旨在通过配置化规则减少PR处理中的手动操作，解决团队协作中PR管理繁琐、效率低下的问题。其核心目标是自动化PR流程（如合并、依赖更新、冲突处理等），帮助开发团队聚焦代码开发而非流程管理，提升整体协作效率。

核心功能和特性

1. 自动化PR合并

• 基于自定义规则触发自动合并，支持通过标签（如auto-merge）、CI状态（如通过所有检查）、审批状态等条件控制合并时机。
• 支持" squash and merge"、"rebase and merge"等多种合并方式，适配不同团队代码管理规范。

2. 依赖更新管理

• 与Dependabot、Renovate等依赖更新工具无缝集成，自动处理依赖更新PR，减少人工审核依赖更新的重复工作。
• 支持配置依赖更新PR的合并优先级，确保关键依赖优先更新。

3. 合并队列管理

• 提供合并队列功能，自动排序待合并PR并按顺序执行，避免并行合并导致的代码冲突。
• 队列内PR合并前自动同步目标分支（如main），确保代码基于最新基线，降低冲突风险。

4. 灵活的配置能力

• 通过仓库根目录下的.kodiak.toml或.kodiak.yml文件定义规则，支持按仓库、分支或PR标签自定义行为。
• 支持配置忽略规则（如特定用户、标签的PR不触发自动合并），满足复杂场景需求。

5. GitHub生态集成

• 作为GitHub App或Docker容器部署，与GitHub API深度集成，支持webhook事件监听（如PR创建、状态更新）。
• 兼容GitHub Actions，可通过Actions工作流触发Kodiak操作，或由Kodiak触发Actions检查。

使用场景和适用范围

适用场景

• 高频PR团队：需要处理大量PR的开发团队（如大型项目、多模块协作场景），减少手动合并操作。
• 依赖密集型项目：依赖第三方库频繁更新的项目（如Web应用、工具类项目），自动化依赖PR管理。
• 敏捷开发团队：追求快速迭代的团队，通过自动化流程缩短PR从提交到合并的周期。
• 规范化协作场景：需要严格遵循PR合并规范（如必须通过CI、获取审批）的团队，通过规则固化流程。

适用范围

• 代码托管平台：仅支持GitHub（包括GitHub.com及GitHub Enterprise Server）。
• 团队规模：适用于2人以上协作的团队，或需要管理多个仓库的个人开发者。

使用方法和配置说明

部署方式

Kodiak支持两种主要部署方式：GitHub App（官方托管，无需自建服务）和Docker容器（私有部署，需自行维护）。以下为Docker部署说明。

Docker镜像获取

从Docker Hub拉取官方镜像：

bash
docker pull chdsbd/kodiak:latest

Docker Run部署示例

bash
docker run -d \
  --name kodiak \
  -v /path/to/kodiak-config:/app/config \  # 挂载配置目录（存放私钥、配置文件等）
  -e GITHUB_APP_ID=12345 \                # GitHub App ID（在GitHub App设置中获取）
  -e PRIVATE_KEY_PATH=/app/config/private-key.pem \  # 私钥文件路径（GitHub App生成的私钥）
  -e WEBHOOK_SECRET=your-webhook-secret \  # GitHub App设置的webhook密钥
  -e DATABASE_URL=postgres://user:pass@db-host:5432/kodiak \  # 数据库连接地址（支持PostgreSQL）
  -p 8080:8080 \                          # 暴露web服务端口（接收GitHub webhook）
  chdsbd/kodiak:latest

Docker Compose部署示例

yaml
version: '3.8'
services:
  kodiak:
    image: chdsbd/kodiak:latest
    container_name: kodiak
    volumes:
      - ./kodiak-config:/app/config
    environment:
      - GITHUB_APP_ID=12345
      - PRIVATE_KEY_PATH=/app/config/private-key.pem
      - WEBHOOK_SECRET=your-webhook-secret
      - DATABASE_URL=postgres://user:pass@postgres:5432/kodiak
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: postgres:14
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=kodiak
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

核心配置说明

环境变量（Docker部署必需）

仓库配置文件（.kodiak.toml/.kodiak.yml）

在仓库根目录创建配置文件，定义PR处理规则。示例（.kodiak.yml）：

yaml
# 自动合并配置
merge:
  # 触发自动合并的标签（PR添加此标签时触发）
  auto_merge_label: "auto-merge"
  # 允许的合并方式（squash/rebase/merge）
  allowed_merge_methods: ["squash"]
  # 必须通过的状态检查（CI任务名称，如"lint"、"test"）
  required_status_checks: ["lint", "test"]
  # 要求PR获得的审批数量（0表示不需要审批）
  required_approvals: 1

# 合并队列配置
queue:
  # 启用合并队列
  enabled: true
  # 队列内PR合并前自动同步目标分支（如main）
  sync_before_merge: true

# 依赖更新PR配置
dependencies:
  # 自动合并依赖更新PR（如Dependabot创建的PR）
  auto_merge: true
  # 依赖更新PR的标签（用于识别此类PR）
  labels: ["dependencies"]

注意事项

• 部署前需在GitHub创建App并配置权限（如pull_requests: write、statuses: read等），确保Kodiak有权限操作PR。
• 数据库需持久化存储，避免容器重启后队列状态、配置数据丢失。
• 配置文件变更后无需重启容器，Kodiak会自动检测最新配置。

更多详细配置及使用说明可参考官方文档：[***]