Help us learn about your current experience with the documentation. Take the survey.

内部API

内部API由不同的GitLab组件使用，其他消费者无法使用。本文档面向在GitLab代码库上工作的人员。

本文档尚未包含GitLab Pages使用的内部API。

有关GitLab订阅内部API的信息，请参阅专用页面。

添加新端点

默认情况下，API端点应可外部访问，并具备适当的身份验证和授权。 在添加新的内部端点之前，请考虑该API是否能让更广泛的GitLab社区受益，并且可以对外部开放。

我们有时倾向于内部API端点的一个原因是，使用此类端点需要外部行为者无法获取的内部数据。例如，在内部Pages API中，我们可能会使用一个秘密令牌来标识请求为内部请求，或者用一个对更广泛社区不可用的公钥来签名请求。

将某物分离到内部API的另一个原因，是当对该API端点的请求不应通过边缘（公共）负载均衡器时。这样我们可以配置不同的速率限制规则和政策，围绕如何访问该端点，因为我们知道只有通过内部负载均衡器的内部请求才能到达该端点。

身份验证

这些方法都使用共享密钥进行身份验证。此密钥存储在config/gitlab.yml配置路径下的文件中，默认位于Rails应用的根目录下，名为.gitlab_shell_secret。

要使用该令牌进行身份验证，客户端需执行以下步骤：

  1. 读取该文件的内容。
  2. 使用文件内容生成JSON Web令牌（JWT）。
  3. 在Gitlab-Shell-Api-Request头中传递JWT。

Git身份验证

由Gitaly和GitLab Shell调用，以检查对仓库的访问权限。

  • 当从GitLab Shell调用时：不会传递任何更改，内部API会回复所需信息，以便将请求转发给Gitaly。
  • 当从Gitaly的pre-receive钩子调用时：会传递并验证更改，以确定是否允许推送。

每个调用限制为50秒。

由于覆盖范围较广，该端点在其专属页面中有更详细的说明。

POST /internal/allowed
属性 类型 必填 描述
key_id string 否 用于连接GitLab Shell的SSH密钥ID
username string 否 连接GitLab Shell所用的证书中的用户名
project string 否（若已传递gl_repository） 项目路径
gl_repository string 否（若已传递project） 仓库标识符，如project-7
protocol string 是 当从GitLab Shell调用时为SSH，当从Gitaly调用时为HTTP或SSH
action string 是 正在运行的Git命令（git-upload-pack、git-receive-pack、git-upload-archive）
changes string 是 当从Gitaly调用时为<oldrev> <newrev> <refname>，当从GitLab Shell调用时为魔术字符串_any
check_ip string 否 调用GitLab Shell时的IP地址

示例请求：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
     "http://localhost:3001/api/v4/internal/allowed"

示例响应：

{
  "status": true,
  "gl_repository": "project-3",
  "gl_project_path": "gnuwget/wget2",
  "gl_id": "user-1",
  "gl_username": "root",
  "git_config_options": [],
  "gitaly": {
    "repository": {
      "storage_name": "default",
      "relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
      "git_object_directory": "",
      "git_alternate_object_directories": [],
      "gl_repository": "project-3",
      "gl_project_path": "gnuwget/wget2"
    },
    "address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
    "token": null
  },
  "gl_console_messages": []
}

已知使用者

  • Gitaly
  • GitLab Shell

LFS 鉴权

此端点由 GitLab Shell 调用，用于在通过 SSH 访问仓库时向 LFS 客户端提供信息。

属性 类型 必需 描述
key_id 字符串 否 用于连接到 GitLab Shell 的 SSH 密钥 ID
username 字符串 否 连接到 GitLab Shell 时使用的证书中的用户名
project 字符串 否 项目路径

示例请求：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"
{
  "username": "root",
  "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
  "repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
  "expires_in": 1800
}

已知消费者

  • GitLab Shell

授权密钥检查

此端点由 GitLab Shell 的授权密钥检查功能调用。快速 SSH 密钥查找 由 OpenSSH 或 GitLab SSHD 触发该检查。

属性 类型 必需 描述
key 字符串 是 用于公钥认证的授权密钥 
GET /internal/authorized_keys

示例请求：

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key>"

示例响应：

{
  "id": 11,
  "title": "admin@example.com",
  "key": "ssh-rsa ...",
  "created_at": "2019-06-27T15:29:02.219Z"
}

已知消费者

  • GitLab Shell

授权证书

此端点由 GitLab Shell 调用，用于获取配置特定 CA SSH 证书的命名空间。它还接受 user_identifier 参数以返回指定标识符对应的 GitLab 用户。

属性 类型 必需 描述
key 字符串 是 SSH 证书的指纹
user_identifier 字符串 是 签发 SSH 证书的目标用户标识符（用户名或主要邮箱） 
GET /internal/authorized_certs

示例请求：

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/authorized_certs?key=<key>&user_identifier=<user_identifier>"

示例响应：

{
  "success": true,
  "namespace": "gitlab-org",
  "username": "root"
}

已知消费者

  • GitLab Shell

根据用户ID或密钥获取用户

当用户执行 ssh git@gitlab.com 时使用此端点。它会发现与 SSH 密钥关联的用户。

属性 类型 必需 描述
key_id 整数 否 在授权密钥文件中找到或在 /authorized_keys 检查中发现的 SSH 密钥 ID
username 字符串 否 正在被查询用户的用户名，GitLab Shell 使用证书进行身份验证时使用 
GET /internal/discover

示例请求：

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/discover?key_id=7"

示例响应：

{
  "id": 7,
  "name": "Dede Eichmann",
  "username": "rubi"
}

已知消费者

  • GitLab Shell

实例信息

此端点获取关于实例的一些通用信息。Geo 节点用它来获取彼此的信息。

GET /internal/check

示例请求：

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/check"

示例响应：

{
  "api_version": "v4",
  "gitlab_version": "12.3.0-pre",
  "gitlab_rev": "d69c988e6a6",
  "redis": true
}

已知消费者

  • GitLab Geo
  • GitLab Shell 的 bin/check
  • Gitaly

使用SSH密钥获取新的双因素认证（2FA）恢复码

此接口由GitLab Shell调用，允许用户基于其SSH密钥获取新的双因素认证（2FA）恢复码。

属性 类型 必需 说明
key_id 整数 否 在authorized-keys文件中找到或通过/authorized_keys检查得到的SSH密钥ID
user_id 整数 否 已弃用。用于生成新恢复码的用户ID 
GET /internal/two_factor_recovery_codes

示例请求：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"

示例响应：

{
  "success": true,
  "recovery_codes": [
    "d93ee7037944afd5",
    "19d7b84862de93dd",
    "1e8c52169195bf71",
    "be50444dddb7ca84",
    "26048c77d161d5b7",
    "482d5c03d1628c47",
    "d2c695e309ce7679",
    "dfb4748afc4f12a7",
    "0e5f53d1399d7979",
    "af04d5622153b020"
  ]
}

已知使用者

  • GitLab Shell

获取新的个人访问令牌

此接口由GitLab Shell调用，允许用户生成新的个人访问令牌。

属性 类型 必需 说明
name 字符串 是 新令牌的名称
scopes 字符串数组 是 新令牌的授权范围，必须是有效的令牌范围
expires_at 字符串 否 访问令牌的到期日期，格式为ISO（YYYY-MM-DD）
key_id 整数 否 在authorized-keys文件中找到或通过/authorized_keys检查得到的SSH密钥ID
user_id 整数 否 用于生成新令牌的用户ID 
POST /internal/personal_access_token

示例请求：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
     "http://localhost:3001/api/v4/internal/personal_access_token"

示例响应：

{
  "success": true,
  "token": "Hf_79B288hRv_3-TSD1R",
  "scopes": ["read_user","read_repository"],
  "expires_at": "2020-07-24"
}

已知使用者

  • GitLab Shell

验证错误跟踪请求

此端点由错误跟踪Go REST API应用程序调用，以验证项目。

属性 类型 必需 说明
project_id 整数 是 拥有关联密钥的项目ID
public_key 字符串 是 由集成错误跟踪功能生成的公钥 
POST /internal/error_tracking/allowed

示例请求：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "project_id=111&public_key=generated-error-tracking-key" \
          "http://localhost:3001/api/v4/internal/error_tracking/allowed"

示例响应：

{ "enabled": true }

已知使用者

  • OpsTrace

接收前增加计数器

此接口由Gitaly钩子调用，为可能被接受的推送增加引用计数器。

属性 类型 必需 说明
gl_repository 字符串 是 接收推送的仓库标识符 
POST /internal/pre_receive

示例请求：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"

示例响应：

{
  "reference_counter_increased": true
}

PostReceive

在接收推送后由Gitaly调用。这会触发Sidekiq中的PostReceive工作器，处理传入的推送选项并构建响应，包括需要显示给用户的消息。

属性 类型 必需 描述
identifier 字符串 是 user-[id] 或 key-[id] 标识执行推送的用户
gl_repository 字符串 是 被推送到的仓库标识符
push_options 字符串数组 否 推送选项数组
changes 字符串 否 推送中要更新的引用，格式为 oldrev newrev refname\n 
POST /internal/post_receive

示例请求：

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "gl_repository=project-7" --data "identifier=user-1" \
     --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
     "http://localhost:3001/api/v4/internal/post_receive"

示例响应：

{
  "messages": [
    {
      "message": "Hello from post-receive",
      "type": "alert"
    }
  ],
  "reference_counter_decreased": true
}

GitLab agent for Kubernetes endpoints

以下端点由GitLab用于Kubernetes的代理服务器（kas）用于各种目的。

这些端点均使用JWT进行身份验证。JWT密钥存储在config/gitlab.yml指定的文件中。默认情况下，位置位于GitLab Rails应用的根目录下，文件名为.gitlab_kas_secret。

GitLab agent for Kubernetes information

由GitLab用于Kubernetes的代理服务器（kas）调用，以检索给定代理令牌的代理信息。此操作返回代理项目对应的Gitaly连接信息，以便kas获取和更新代理的配置。

GET /internal/kubernetes/agent_info

示例请求：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"

GitLab agent for Kubernetes project information

由GitLab用于Kubernetes的代理服务器（kas）调用，以检索给定代理令牌的项目信息。此操作返回所请求项目的Gitaly连接。GitLab kas使用此信息来配置代理从项目仓库同步Kubernetes资源。

仅支持公开项目。对于私有项目，代理授权功能尚未实现。

属性 类型 必需 描述
id 整数/字符串 是 项目ID或URL编码路径 
GET /internal/kubernetes/project_info

示例请求：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"

GitLab Kubernetes代理的使用指标

由GitLab Kubernetes代理服务器（kas）调用以增加使用指标计数器。

属性 类型 必填 说明
counters 哈希表 否 计数器哈希表
counters["k8s_api_proxy_request"] 整数 否 要增加k8s_api_proxy_request计数器的数值
counters["flux_git_push_notifications_total"] 整数 否 要增加flux_git_push_notifications_total计数器的数值
counters["k8s_api_proxy_requests_via_ci_access"] 整数 否 要增加k8s_api_proxy_requests_via_ci_access计数器的数值
counters["k8s_api_proxy_requests_via_user_access"] 整数 否 要增加k8s_api_proxy_requests_via_user_access计数器的数值
counters["k8s_api_proxy_requests_via_pat_access"] 整数 否 要增加k8s_api_proxy_requests_via_pat_access计数器的数值
unique_counters 哈希表 否 唯一数值数组
unique_counters["k8s_api_proxy_requests_unique_users_via_ci_access"] 整数数组 否 通过ci_access与CI隧道交互的唯一用户ID集合，用于跟踪k8s_api_proxy_requests_unique_users_via_ci_access指标事件
unique_counters["k8s_api_proxy_requests_unique_agents_via_ci_access"] 整数数组 否 通过ci_access与CI隧道交互的唯一代理ID集合，用于跟踪k8s_api_proxy_requests_unique_agents_via_ci_access指标事件
unique_counters["k8s_api_proxy_requests_unique_users_via_user_access"] 整数数组 否 通过user_access与CI隧道交互的唯一用户ID集合，用于跟踪k8s_api_proxy_requests_unique_users_via_user_access指标事件
unique_counters["k8s_api_proxy_requests_unique_agents_via_user_access"] 整数数组 否 通过user_access与CI隧道交互的唯一代理ID集合，用于跟踪k8s_api_proxy_requests_unique_agents_via_user_access指标事件
unique_counters["k8s_api_proxy_requests_unique_users_via_pat_access"] 整数数组 否 使用KAS Kubernetes API代理且带有PAT的唯一用户ID集合，用于跟踪k8s_api_proxy_requests_unique_users_via_pat_access指标事件
unique_counters["k8s_api_proxy_requests_unique_agents_via_pat_access"] 整数数组 否 使用KAS Kubernetes API代理且带有PAT的唯一代理ID集合，用于跟踪k8s_api_proxy_requests_unique_agents_via_pat_access指标事件
unique_counters["flux_git_push_notified_unique_projects"] 整数数组 否 已被通知 reconciliation 其Flux工作负载的唯一项目ID集合，用于跟踪flux_git_push_notified_unique_projects指标事件 
POST /internal/kubernetes/usage_metrics

示例请求：

curl --请求 POST --头信息 "Gitlab-Kas-Api-Request: <JWT token>" --头信息 "Content-Type: application/json" \
     --数据 '{"counters": {"k8s_api_proxy_request":1}}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"

GitLab 用于 Kubernetes 事件的代理

由 GitLab 用于 Kubernetes 的代理服务器（kas）调用以跟踪事件。

属性 类型 必需 描述
events 哈希 否 事件哈希
events["k8s_api_proxy_requests_unique_users_via_ci_access"] 哈希数组 否 k8s_api_proxy_requests_unique_users_via_ci_access 的事件数组
events["k8s_api_proxy_requests_unique_users_via_ci_access"]["user_id"] 整数 否 事件对应的用户 ID
events["k8s_api_proxy_requests_unique_users_via_ci_access"]["project_id"] 整数 否 事件对应的项目 ID
events["k8s_api_proxy_requests_unique_users_via_user_access"] 哈希数组 否 k8s_api_proxy_requests_unique_users_via_user_access 的事件数组
events["k8s_api_proxy_requests_unique_users_via_user_access"]["user_id"] 整数 否 事件对应的用户 ID
events["k8s_api_proxy_requests_unique_users_via_user_access"]["project_id"] 整数 否 事件对应的项目 ID
events["k8s_api_proxy_requests_unique_users_via_pat_access"] 哈希数组 否 k8s_api_proxy_requests_unique_users_via_pat_access 的事件数组
events["k8s_api_proxy_requests_unique_users_via_pat_access"]["user_id"] 整数 否 事件对应的用户 ID
events["k8s_api_proxy_requests_unique_users_via_pat_access"]["project_id"] 整数 否 事件对应的项目 ID 
POST /internal/kubernetes/agent_events

示例请求：

curl --request POST \
  --url "http://localhost:3000/api/v4/internal/kubernetes/agent_events" \
  --header "Gitlab-Kas-Api-Request: <JWT token>" \
  --header "Content-Type: application/json" \
  --data '{
    "events": {
      "k8s_api_proxy_requests_unique_users_via_ci_access": [
        {
          "user_id": 1,
          "project_id": 1
        }
      ]
    }
  }'

创建 Starboard 漏洞

由 GitLab 用于 Kubernetes 的代理服务器（kas）调用，从 Starboard 漏洞报告创建安全漏洞。此请求是幂等的。相同数据的多次请求会创建单个漏洞。响应包含所创建漏洞发现的 UUID。

属性 类型 必需 描述
vulnerability 哈希 是 匹配安全报告架构中 vulnerability 字段 的漏洞数据。
scanner 哈希 是 匹配安全报告架构中 scanner 字段 的扫描器数据。 
PUT internal/kubernetes/modules/starboard_vulnerability

示例请求：

curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
     --data '{
  "vulnerability": {
    "name": "CVE-123-4567 in libc",
    "severity": "high",
    "confidence": "unknown",
    "location": {
      "kubernetes_resource": {
        "namespace": "production",
        "kind": "deployment",
        "name": "nginx",
        "container": "nginx"
      }
    },
    "identifiers": [
      {
        "type": "cve",
        "name": "CVE-123-4567",
        "value": "CVE-123-4567"
      }
    ]
  },
  "scanner": {
    "id": "starboard_trivy",
    "name": "Trivy (via Starboard Operator)",
    "vendor": "GitLab"
  }
}'

示例响应：

{
  "uuid": "4773b2ee-5ba5-5e9f-b48c-5f7a17f0faac"
}

解决 Starboard 漏洞

由 GitLab 用于 Kubernetes 的代理服务器（kas）调用，以解决 Starboard 安全漏洞。接受检测到的漏洞 UUID 列表，并将不在该列表中的所有 Starboard 漏洞标记为已解决。

属性 类型 必需 描述
uuids 字符串数组 是 检测到的漏洞的 UUID，来自创建 Starboard 漏洞响应的收集结果。 
POST internal/kubernetes/modules/starboard_vulnerability/scan_result

示例请求：

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_result" \
     --data '{ "uuids": ["102e8a0a-fe29-59bd-b46c-57c3e9bc6411", "5eb12985-0ed5-51f4-b545-fd8871dc2870"] }'

扫描执行策略

由 GitLab 用于 Kubernetes 的代理服务器（kas）调用，以获取与代理令牌所属项目关联的 scan_execution_policies 配置。GitLab kas 使用此信息来配置代理，根据策略扫描 Kubernetes 集群中的镜像。

GET /internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies

示例请求：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

示例响应：

{
  "policies": [
    {
      "name": "Policy",
      "description": "Policy description",
      "enabled": true,
      "yaml": "---\nname: Policy\ndescription: 'Policy description'\nenabled: true\nactions:\n- scan: container_scanning\nrules:\n- type: pipeline\n  branches:\n  - main\n",
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

策略配置

由 GitLab 用于 Kubernetes 的代理服务器（kas）调用，以获取与代理令牌所属项目关联的 policies_configuration 配置。GitLab kas 使用此信息来配置代理，根据配置扫描 Kubernetes 集群中的镜像。

GET /internal/kubernetes/modules/starboard_vulnerability/policies_configuration

示例请求：

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/policies_configuration"

示例响应：

{
  "configurations": [
    {
      "cadence": "30 2 * * *",
      "namespaces": [
        "namespace-a",
        "namespace-b"
      ],
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

存储限制排除项

命名空间存储限制排除端点管理 GitLab.com 上顶级命名空间的存储限制排除项。这些端点只能在 GitLab.com 的管理员区域中使用。

获取存储限制排除项

使用 GET 请求检索所有 Namespaces::Storage::LimitExclusion 记录。

GET /namespaces/storage/limit_exclusions

示例请求：

curl --request GET \
  --url "https://gitlab.com/v4/namespaces/storage/limit_exclusions" \
  --header 'PRIVATE-TOKEN: <admin access token>'

示例响应：

[
    {
      "id": 1,
      "namespace_id": 1234,
      "namespace_name": "A Namespace Name",
      "reason": "a reason to exclude the Namespace"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "Another Namespace Name",
      "reason": "another reason to exclude the Namespace"
    },
]

创建存储限制排除项

使用 POST 请求创建一个 Namespaces::Storage::LimitExclusion。

POST /namespaces/:id/storage/limit_exclusion
属性 类型 必需 描述
reason 字符串 是 排除命名空间的原因。

示例请求：

curl --request POST \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "reason": "a reason to exclude the Namespace"
  }'

示例响应：

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "A Namespace Name",
  "reason": "a reason to exclude the Namespace"
}

删除存储限制排除

使用 DELETE 请求删除命名空间的 Namespaces::Storage::LimitExclusion。

DELETE /namespaces/:id/storage/limit_exclusion

示例请求：

curl --request DELETE \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'PRIVATE-TOKEN: <admin access token>'

示例响应：

204

已知使用者

  • GitLab.com 管理员区域

群组 SCIM API

  • 层级：Premium、Ultimate
  • 提供：GitLab.com

该群组 SCIM API 部分实现了 RFC7644 协议。此 API 提供了 /groups/:group_path/Users 和 /groups/:group_path/Users/:id 端点。基础 URL 为 <http|https>://<GitLab 主机>/api/scim/v2。由于此 API 用于 SCIM 提供程序的系统集成，因此可能会在未通知的情况下更改。

要使用此 API，需为群组启用 群组 SSO。此 API 仅在启用了 群组 SSO 的 SCIM 时使用。它是创建 SCIM 身份的前提条件。

此群组 SCIM API：

  • 用于 SCIM 提供程序的系统集成。
  • 实现 RFC7644 协议。
  • 获取群组的 SCIM 预配用户列表。
  • 创建、删除和更新群组的 SCIM 预配用户。

实例 SCIM API 对实例执行相同操作。

此群组 SCIM API 与 SCIM API 不同。SCIM API：

  • 不是内部 API。
  • 不实现 RFC7644 协议。
  • 在群组中获取、检查、更新和删除 SCIM 身份。

此 API 不需要 Gitlab-Shell-Api-Request 头。

获取 SCIM 预配用户列表

此端点用作 SCIM 同步机制的一部分。它根据使用的过滤器返回用户列表。

GET /api/scim/v2/groups/:group_path/Users

参数：

属性 类型 必需 说明
filter string 否 一个 过滤器 表达式。
group_path string 是 群组完整路径。
startIndex integer 否 表示从何处开始返回结果的基于 1 的索引。小于 1 的值视为 1。
count integer 否 所需的最大查询结果数。

分页遵循 SCIM 规范，而非 GitLab 其他地方使用的分页方式。如果在请求之间记录发生更改，则页面可能会丢失已移至不同页面的记录，或重复之前请求中的记录。

按特定标识符过滤的示例请求：

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "Test User",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

获取单个SCIM预配的用户

GET /api/scim/v2/groups/:group_path/Users/:id

参数：

属性 类型 必需 描述
id 字符串 是 用户的外部UID。
group_path 字符串 是 群组的完整路径。

示例请求：

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

创建一个SCIM预配的用户

POST /api/scim/v2/groups/:group_path/Users/

参数：

属性 类型 必需 描述
externalId 字符串 是 用户的外部UID。
userName 字符串 是 用户的用户名。
emails JSON字符串 是 工作邮箱。
name JSON字符串 是 用户的姓名。
meta 字符串 否 资源类型（User）。

示例请求：

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" \
     --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

若成功则返回 201 状态码。

当你为一个用户创建了群组SCIM身份后，你可以在管理区看到该用户的SCIM身份。

更新单个SCIM预配用户

可更新的字段有：

SCIM/IdP 字段 GitLab 字段
id/externalId extern_uid
name.formatted name (Removed)
emails[type eq "work"].value email (Removed)
active 若 active 为 false 则移除身份
userName username (Removed) 
PATCH /api/scim/v2/groups/:group_path/Users/:id

参数：

属性 类型 必需 描述
id string 是 用户的外部UID。
group_path string 是 组的完整路径。
Operations JSON字符串 是 一个 operations 表达式。

更新用户 id 的示例请求：

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"replace","path":"id","value":"1234abcd"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功时返回空响应，状态码为 204。

设置用户 active 状态的示例请求：

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"replace","path":"active","value":"true"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功时返回空响应，状态码为 204。

移除单个SCIM预配用户

移除用户的SSO身份和组成员资格。

DELETE /api/scim/v2/groups/:group_path/Users/:id

参数：

属性 类型 必需 描述
id string 是 用户的外部UID。
group_path string 是 组的完整路径。

示例请求：

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功时返回空响应，状态码为 204。

实例SCIM API

  • 层级：Premium, Ultimate
  • 提供：GitLab 自托管

该实例SCIM API部分实现了 RFC7644协议。此API提供管理用户和组的端点。基础URL为 <http|https>://<GitLab主机>/api/scim/v2。由于此API用于SCIM提供商集成的系统使用，因此可能会在不通知的情况下发生变化。

要使用此API，请启用 SAML SSO 用于实例。

此实例SCIM API：

  • 用于SCIM提供商集成的系统使用。
  • 实现 RFC7644协议。
  • 获取SCIM预配用户的列表。
  • 创建、删除和更新SCIM预配用户。
  • 通过 SAML组链接 管理组成员资格。

group SCIM API 对组执行相同操作。

此实例SCIM API与 SCIM API 不同。SCIM API：

  • 不是内部API。
  • 不实现 RFC7644协议。
  • 在组内获取、检查、更新和删除SCIM身份。

此API不需要 Gitlab-Shell-Api-Request 头信息。

用户端点

使用用户端点管理SCIM预配用户。

获取SCIM已配置的用户列表

此端点是SCIM同步机制的一部分。它会根据所用的过滤器返回用户列表。

GET /api/scim/v2/application/Users

参数：

属性 类型 必需 说明
filter 字符串 否 一个过滤器表达式。
startIndex 整数 否 基于1的索引，指示从何处开始返回结果。小于1的值会被解释为1。
count 整数 否 所需的最大查询结果数量。

分页遵循SCIM规范，而非GitLab在其他地方使用的分页方式。如果在请求之间记录发生更改，则页面可能会缺少已移至不同页面的记录，或重复之前请求中的记录。

示例请求：

curl "https://gitlab.example.com/api/scim/v2/application/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "Test User",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

获取单个SCIM已配置的用户

GET /api/scim/v2/application/Users/:id

参数：

属性 类型 必需 说明
id 字符串 是 用户的外部UID。

示例请求：

curl "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

创建SCIM已配置的用户

POST /api/scim/v2/application/Users

参数：

属性 类型 必需 说明
externalId 字符串 是 用户的外部UID。
userName 字符串 是 用户的用户名。
emails JSON字符串 是 工作邮箱。
name JSON字符串 是 用户姓名。
meta 字符串 否 资源类型（User）。

示例请求：

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Users" \
     --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

若成功，返回201状态码。

更新单个 SCIM 预配的用户

可更新的字段有：

SCIM/IdP 字段 GitLab 字段
id/externalId extern_uid
active 如果为 false，用户会被封禁，但 SCIM 身份仍保持关联。 
PATCH /api/scim/v2/application/Users/:id

参数：

属性 类型 必需 描述
id 字符串 是 用户的外部 UID。
Operations JSON 字符串 是 一个 操作 表达式。

示例请求：

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"Update","path":"active","value":"false"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功时返回空响应，状态码为 204。

封禁单个 SCIM 预配的用户

用户将被置于封禁状态并登出。这意味着用户无法登录、推送或拉取代码。

DELETE /api/scim/v2/application/Users/:id

参数：

属性 类型 必需 描述
id 字符串 是 用户的外部 UID。

示例请求：

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功时返回空响应，状态码为 204。

组端点

使用组端点自动同步 GitLab 与 SCIM 身份提供者。

此 API 使用 SAML 组链接 将 IdP 组与 GitLab 组连接。在使用这些端点之前，必须为要同步的组创建必要的 SAML 组链接。

获取 SCIM 组列表

此端点返回已分配 SCIM ID 的组列表。

GET /api/scim/v2/application/Groups

参数：

属性 类型 必需 描述
filter 字符串 否 用于按名称搜索组的筛选表达式。
startIndex 整数 否 表示从何处开始返回结果的基于 1 的索引。
count 整数 否 所需的最大查询结果数量。
excludedAttributes 字符串 否 要从响应中排除的属性列表（逗号分隔）。

分页遵循 SCIM 规范，而非 GitLab 分页。

示例请求：

curl "https://gitlab.example.com/api/scim/v2/application/Groups?filter=displayName%20eq%20%22Developers%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
      "displayName": "Developers",
      "members": [],
      "meta": {
        "resourceType": "Group"
      }
    }
  ]
}

获取单个 SCIM 组

GET /api/scim/v2/application/Groups/:id

参数：

属性 类型 必需 说明
id string 是 SCIM 组 ID（UUID 格式）。

示例请求：

curl "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [],
  "meta": {
    "resourceType": "Group"
  }
}

创建 SCIM 组

此端点将 SCIM 组 ID 与具有相同名称的现有 SAML 组链接关联。

POST /api/scim/v2/application/Groups

参数：

属性 类型 必需 说明
displayName string 是 在 GitLab SAML 组链接中配置的组名称。
externalId string 否 可选的 SCIM 组 ID。如果未提供，则生成一个 UUID。

示例请求：

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Groups" \
     --data '{"displayName":"Developers","schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

示例响应：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [],
  "meta": {
    "resourceType": "Group"
  }
}

成功时返回 201 状态码。

此端点不会创建 GitLab 组。它只会将与指定显示名称对应的 SAML 组链接关联到 SCIM ID。

更新 SCIM 组

更新 SCIM 组的成员。用于添加或移除与该 SCIM 组关联的 GitLab 组中的用户。

PATCH /api/scim/v2/application/Groups/:id

参数：

属性 类型 必需 说明
id string 是 SCIM 组 ID。
Operations JSON 数组 是 要执行的操作数组。每个操作包含 op（操作类型）、path（要修改的属性）和 value（新值）。

支持的操作：

  • 使用路径 members 的 add 操作来添加组成员
  • 使用路径 members 的 remove 操作来移除组成员

添加成员的示例请求：

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"add","path":"members","value":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

移除成员的示例请求：

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"remove","path":"members","value":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

成功时返回空响应和 204 状态码。

替换 SCIM 组

使用新的成员集合替换 SCIM 组的所有成员。

PUT /api/scim/v2/application/Groups/:id

参数：

属性 类型 必需 描述
id 字符串 是 SCIM 组 ID。
schemas 数组 是 SCIM 架构数组。必须包含 ["urn:ietf:params:scim:schemas:core:2.0:Group"]。
displayName 字符串 是 组显示名称。
members 数组 否 成员数组，每个成员包含带有用户 SCIM ID 的 value 属性。

示例请求：

curl --verbose --request PUT "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],"displayName":"Developers","members":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

响应包含更新的组信息。

PUT 操作会替换组中所有成员。请求中未包含的现有成员将从与此 SCIM 组关联的所有 GitLab 组中移除。

删除 SCIM 组

通过清除 SCIM 组 ID，从现有的 SAML 组链接中移除 SCIM 管理。此端点还会安排后台清理 SCIM 组成员资格跟踪记录。

DELETE /api/scim/v2/application/Groups/:id

参数：

属性 类型 必需 描述
id 字符串 是 SCIM 组 ID（UUID 格式）。

示例请求：

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

若成功，返回空响应，状态码为 204。

此端点不会删除 GitLab 组。它只会从具有指定 SCIM 组 ID 的 SAML 组链接中移除 SCIM 管理，允许身份提供者取消配置不需要的 SCIM 组。

可用过滤器

它们匹配 RFC7644 过滤部分 中指定的表达式。

过滤器 说明
eq 属性完全匹配指定值。

示例：

id eq a-b-c-d

可用操作

它们执行 RFC7644 更新部分 中指定的操作。

操作符 说明
Replace 属性值被更新。
Add 属性添加新值。

示例：

{ "op": "Add", "path": "name.formatted", "value": "New Name" }