libri/gitlab-settings-enforcer

GitLab设置强制实施工具镜像

镜像概述

该Docker镜像提供了一个工具，通过读取配置文件并与GitLab API交互，自动化强制实施GitLab实例内的各项设置。旨在帮助管理员标准化GitLab环境配置，确保组织内的GitLab资源（项目、群组、用户等）符合预设规则和策略。

核心功能与特性

• 配置驱动：通过YAML/JSON格式的配置文件定义GitLab设置规则，支持版本化管理
• API集成：与GitLab API深度交互，自动应用配置规则到GitLab实例
• 多实体支持：覆盖GitLab主要实体类型，包括项目、群组、用户、分支等
• 灵活策略：支持多种强制执行策略（如覆盖现有设置、仅检查合规性、报告差异等）
• 错误处理：提供详细的执行日志和错误报告，便于问题排查

使用场景

• 企业GitLab管理：统一管理多项目/多群组的GitLab配置，确保一致性
• 合规性要求：满足行业合规标准（如GDPR、ISO）对代码仓库的配置要求
• 自动化运维：GitLab环境部署后的配置初始化与持续维护
• 安全加固：强制实施安全相关设置（如分支保护、合并规则、访问控制等）

使用方法与配置说明

前置条件

• 可访问的GitLab实例（自托管或GitLab.com）
• 具有足够权限的GitLab个人访问令牌（需包含api、read_user、read_repository等作用域）
• 配置文件（YAML/JSON格式）

配置文件示例

创建配置文件（如config.yaml），定义需要强制实施的设置：

yaml
# 项目级设置示例
projects:
  - name: "my-group/my-project"  # 项目路径
    settings:
      merge_requests:
        squash_option: "always"  # 强制合并前压缩提交
        require_merge_request_approvals: true  # 要求合并请求审批
        approvals_required: 2  # 至少2个审批
      repository:
        allow_merge_on_skipped_pipeline: false  # 不允许跳过流水线后合并
      protected_branches:
        - name: "main"
          push_access_level: "no one"  # 禁止直接推送到main分支
          merge_access_level: "maintainer"  # 仅维护者可合并到main分支

# 群组级设置示例
groups:
  - name: "my-group"  # 群组路径
    settings:
      visibility: "internal"  # 群组可见性设为内部
      require_two_factor_authentication: true  # 强制开启2FA

环境变量说明

Docker Run命令

bash
docker run -d \
  --name gitlab-enforcer \
  -v /path/to/local/config:/config \  # 挂载本地配置目录到容器
  -e GITLAB_URL="https://gitlab.example.com" \
  -e GITLAB_TOKEN="your_personal_access_token" \
  -e CONFIG_PATH="/config/config.yaml" \
  -e LOG_LEVEL="info" \
  [镜像名称]:[标签]

Docker Compose配置

yaml
version: '3.8'

services:
  gitlab-enforcer:
    image: [镜像名称]:[标签]
    container_name: gitlab-enforcer
    volumes:
      - ./config:/config  # 本地配置目录映射
    environment:
      - GITLAB_URL=https://gitlab.example.com
      - GITLAB_TOKEN=your_personal_access_token
      - CONFIG_PATH=/config/config.yaml
      - LOG_LEVEL=info
      - ENFORCE_POLICY=apply
    restart: unless-stopped

执行流程

1. 容器启动后，读取环境变量配置
2. 加载指定路径的配置文件
3. 连接GitLab API验证凭据
4. 根据配置文件定义的规则遍历GitLab实体
5. 按照ENFORCE_POLICY执行相应操作（应用设置或检查合规性）
6. 输出执行日志，记录成功/失败的设置项

注意事项

• 确保GitLab令牌具有足够权限，避免因权限不足导致设置失败
• 首次使用建议先设置ENFORCE_POLICY=check进行合规性检查，确认配置无误后再切换为apply
• 配置文件变更后需重启容器或通过工具内部命令重新加载配置
• 对于大型GitLab实例，建议分批次处理设置以避免API请求限流