github/ldap-teamsync

镜像概述

saml-ldap-team-sync 是一款用于在LDAP/Active Directory与GitHub之间实现同步的工具。其核心目标是解决大型组织中团队管理的复杂性，尤其适用于那些不使用LDAP进行身份验证或因特定原因未启用GitHub团队同步功能的场景。该工具支持GitHub.com及GitHub Enterprise两种环境，但运行时需部署在能够访问组织内部LDAP服务器的网络位置。

核心功能和特性

• 跨平台同步：实现LDAP/Active Directory与GitHub之间的团队及用户信息同步，确保两边数据一致性。
• 多环境支持：兼容GitHub.com（公共GitHub）和GitHub Enterprise（企业版GitHub）。
• 组织适配性：专为大型组织设计，可高效处理多团队场景下的同步需求。
• 灵活部署：需运行在具备LDAP服务器访问权限的环境中，确保与内部目录服务的连接性。

使用场景和适用范围

适用场景

• 大型组织中，团队结构频繁变动，需要自动化维护GitHub团队成员与LDAP/AD用户的对应关系。
• 组织未采用LDAP作为GitHub身份验证方式，但希望基于LDAP/AD中的用户信息管理GitHub团队。
• 因合规、权限控制等原因，需通过LDAP/AD统一管理用户生命周期（如入职、离职）并同步至GitHub。

适用范围

• 采用LDAP或Active Directory作为内部用户目录服务的组织。
• 使用GitHub.com或GitHub Enterprise进行代码管理和协作的团队。
• 需要简化跨平台用户与团队管理流程的IT或DevOps团队。

使用方法和配置说明

前置条件

1. 运行环境需能够访问组织的LDAP/Active Directory服务器（网络可达性）。
2. 拥有GitHub的个人访问令牌（PAT），且令牌需具备管理组织和团队的权限（如admin:org、write:org范围）。
3. 已获取LDAP/AD的访问凭证（如绑定DN、密码）及目录结构信息（如用户搜索基准DN、团队属性等）。

核心配置参数

该工具的配置需通过环境变量或配置文件（如config.yaml）指定，关键参数包括：

部署示例

1. 通过Docker Run部署

bash
docker run -d \
  --name saml-ldap-team-sync \
  -e LDAP_SERVER=ldap://ldap.example.com:389 \
  -e LDAP_BIND_DN="cn=admin,dc=example,dc=com" \
  -e LDAP_BIND_PASSWORD="your-ldap-password" \
  -e LDAP_USER_BASE_DN="ou=users,dc=example,dc=com" \
  -e GITHUB_TOKEN="ghp_yourgithubtoken" \
  -e GITHUB_ORG="your-github-org" \
  -v /path/to/local/config.yaml:/app/config.yaml \  # 若使用配置文件覆盖默认配置
  github/saml-ldap-team-sync

2. 通过Docker Compose部署

创建docker-compose.yml文件：

yaml
version: '3'
services:
  saml-ldap-team-sync:
    image: github/saml-ldap-team-sync
    container_name: saml-ldap-team-sync
    environment:
      - LDAP_SERVER=ldap://ldap.example.com:389
      - LDAP_BIND_DN=cn=admin,dc=example,dc=com
      - LDAP_BIND_PASSWORD=your-ldap-password
      - LDAP_USER_BASE_DN=ou=users,dc=example,dc=com
      - GITHUB_TOKEN=ghp_yourgithubtoken
      - GITHUB_ORG=your-github-org
    volumes:
      - ./config.yaml:/app/config.yaml  # 本地配置文件挂载
    restart: unless-stopped

同步流程说明

1. 连接验证：工具启动后，首先验证与LDAP/AD服务器及GitHub的连接可用性。
2. 数据拉取：从LDAP/AD获取用户和团队信息，从GitHub获取目标组织的团队和成员信息。
3. 差异对比：对比两边数据，识别新增、删除或变更的用户/团队关系。
4. 执行同步：根据预设规则（如以LDAP为准），在GitHub中创建/更新/删除团队成员，完成数据同步。
5. 日志输出：同步过程及结果通过日志记录，便于问题排查和审计。

注意事项

• 权限控制：GitHub个人访问令牌需严格限制权限范围，仅授予必要的组织管理权限。
• 网络安全：建议通过加密方式（如LDAPS，端口636）连接LDAP服务器，避免敏感信息明文传输。
• 测试验证：首次部署前，建议在测试环境中验证同步规则，避免对生产环境GitHub组织造成意外修改。
• 定期维护：根据组织用户变动频率，调整同步周期（如每日、每小时），确保数据时效性。