グループAPI

REST API を使用してグループと対話します。

応答で返されるフィールドは、認証ユーザーの権限によって異なります。

グループの一覧

GitLab 14.3で導入されたキーセットのページ分割をサポートしました。

認証済みユーザーの可視グループ一覧を取得します。認証なしでアクセスした場合は、公開グループのみが返されます。

API の結果はページ分割されるため、デフォルトではこのリクエストは一度に 20 件の結果を返します。

認証なしでアクセスすると、このエンドポイントはキーセットのページ分割もサポートします:

パラメータを指定します:

属性種類必須説明
skip_groups整数の配列いいえ渡されたグループIDをスキップ
all_availablebooleanいいえアクセス権を持つすべてのグループを表示します(認証ユーザーのデフォルトはfalse 、管理者のデフォルトはtrue )。属性ownedmin_access_level が優先されます。
search文字列です。いいえ検索条件に一致する作成者グループのリストを返します。
order_by文字列です。いいえ name,path,id, またはsimilarity (検索する場合、GitLab 14.1 で導入) でグループを並び替えます。デフォルトはname
sort文字列です。いいえグループをasc またはdesc 順に並べます。デフォルトはasc
statisticsbooleanいいえグループ統計を含める(管理者のみ)
注:REST API レスポンスは、UI に表示される完全なRootStorageStatistics データを提供しません。UI のデータと一致させるには、REST ではなく GraphQL を使用します。詳細については、Group GraphQL API リソースを参照してください。
with_custom_attributesbooleanいいえレスポンスにカスタム属性を含める(管理者のみ)
ownedbooleanいいえ現在のユーザーが明示的に所有するグループに限定
min_access_level整数。いいえ現在のユーザーが少なくともこのロール (access_level) を持っているグループに限定します。
top_level_onlybooleanいいえトップレベルのグループに限定し、すべてのサブグループを除外
repository_storage 文字列です。いいえグループ_(管理者のみ_)が使用するリポジトリストレージでフィルタリングします。GitLab 16.3 で導入されました
GET /groups
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "ip_restriction_ranges": null
  }
]

パラメータstatistics=true を追加し、認証ユーザーが管理者である場合、追加のグループ統計が返されます。

GET /groups?statistics=true
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "statistics": {
      "storage_size": 363,
      "repository_size": 33,
      "wiki_size": 100,
      "lfs_objects_size": 123,
      "job_artifacts_size": 57,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 50,
      "uploads_size": 0
    },
    "wiki_access_level": "private"
  }
]

GitLabプレミアムまたはアルティメットのユーザーにもwiki_access_level 属性が表示されます。

グループは名前やパスで検索することができます。

カスタム属性でフィルタリングできます:

GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value

グループのサブグループのリスト

このグループの表示可能な直接のサブグループのリストを取得します。

API の結果はページ分割されるため、デフォルトではこのリクエストは一度に 20 件の結果を返します。

このリストを

  • 認証されていないユーザーとしてこのリストをリクエストした場合、レスポンスは公開グループのみを返します。
  • 認証済みユーザーの場合は、自分が所属しているグループのみが返され、公開グループは含まれません。

パラメータを指定します:

属性種類必須説明
id整数/文字列yes直接の親グループのグループのIDまたはURLエンコードされたパス
skip_groups整数の配列いいえ渡されたグループIDをスキップ
all_availablebooleanいいえアクセス権を持つすべてのグループを表示します(認証ユーザーのデフォルトはfalse 、管理者のデフォルトはtrue )。属性ownedmin_access_level が優先されます。
search文字列です。いいえ検索条件に一致する作成者グループのリストを返します。サブグループのショートパスのみが検索されます (フルパスではありません)。
order_by文字列です。いいえ name,path またはid によるグループの順序付け。デフォルトはname
sort文字列です。いいえグループをasc またはdesc 順に並べます。デフォルトはasc
statisticsbooleanいいえグループ統計を含める(管理者のみ)
with_custom_attributesbooleanいいえレスポンスにカスタム属性を含める(管理者のみ)
ownedbooleanいいえ現在のユーザーが明示的に所有するグループに限定
min_access_level整数。いいえ現在のユーザーが少なくともこのロール (access_level) を持っているグループに限定します。
GET /groups/:id/subgroups
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://gitlab.example.com/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

GitLabプレミアムまたはアルティメットのユーザーにもwiki_access_level 属性が表示されます。

グループの子孫グループのリスト

GitLab 13.5 で導入されました

このグループの可視の子孫グループの一覧を取得します。認証なしでアクセスした場合は、公開グループのみが返されます。

API の結果はページ分割されるため、デフォルトではこのリクエストは一度に 20 件の結果を返します。

パラメータを指定します:

属性種類必須説明
id整数/文字列yes直接の親グループのグループのIDまたはURLエンコードされたパス
skip_groups整数の配列いいえ渡されたグループIDをスキップ
all_availablebooleanいいえアクセス権を持つすべてのグループを表示します (認証ユーザーのデフォルトはfalse で、管理者のデフォルトはtrue です)。ownedmin_access_level の属性が優先されます。
search文字列です。いいえ検索条件に一致する作成者グループのリストを返します。検索されるのは子孫グループのショートパスのみです (フルパスではありません)。
order_by文字列です。いいえ namepath 、またはid でグループを並べ替えます。デフォルトはname
sort文字列です。いいえグループをasc またはdesc 順に並べます。デフォルトはasc
statisticsbooleanいいえグループ統計を含める(管理者のみ)
with_custom_attributesbooleanいいえレスポンスにカスタム属性を含める(管理者のみ)
ownedbooleanいいえ現在のユーザーが明示的に所有するグループに限定
min_access_level整数。いいえ現在のユーザーが少なくともこのロール (access_level) を持っているグループに限定します。
GET /groups/:id/descendant_groups
[
  {
    "id": 2,
    "name": "Bar Group",
    "path": "bar",
    "description": "A subgroup of Foo Group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar",
    "request_access_enabled": false,
    "full_name": "Bar Group",
    "full_path": "foo/bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  },
  {
    "id": 3,
    "name": "Baz Group",
    "path": "baz",
    "description": "A subgroup of Bar Group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar/baz",
    "request_access_enabled": false,
    "full_name": "Baz Group",
    "full_path": "foo/bar/baz",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

GitLabプレミアムまたはアルティメットのユーザーにもwiki_access_level 属性が表示されます。

グループのプロジェクトをリストアップ

このグループのプロジェクトの一覧を取得します。認証なしでアクセスした場合は、公開プロジェクトのみが返されます。

API の結果はページ分割されるため、デフォルトではこのリクエストは一度に 20 件の結果を返します。

GET /groups/:id/projects

パラメータを指定します:

属性種類必須説明
id整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
archivedbooleanいいえアーカイブ状態による制限
visibility文字列です。いいえ視認性による制限public,internal, またはprivate
order_by文字列です。いいえ idnamepathcreated_atupdated_atsimilarity (1)、last_activity_at のフィールド順にプロジェクトを返します。デフォルトはcreated_at
sort文字列です。いいえ asc またはdesc 順序で descソートされたプロジェクトを返しますdesc 。デフォルトは desc
search文字列です。いいえ検索条件に一致する作成者プロジェクトのリストを返します。
simplebooleanいいえ各プロジェクトの限られたフィールドのみを返します。単純なフィールドのみが返されます。
ownedbooleanいいえ現在のユーザーが所有するプロジェクトによる制限
starredbooleanいいえ現在のユーザーがスターを付けたプロジェクトによる制限
topic文字列です。いいえトピックに一致するプロジェクトを返します。
with_issues_enabledbooleanいいえイシュー機能が有効なプロジェクトで制限します。デフォルトはfalse
with_merge_requests_enabledbooleanいいえマージリクエスト機能が有効なプロジェクトによって制限されます。デフォルトはfalse
with_sharedbooleanいいえこのグループに共有されているプロジェクトを含めます。デフォルトはtrue
include_subgroupsbooleanいいえこのグループのサブグループにプロジェクトを含めます。デフォルトはfalse
min_access_level整数。いいえ現在のユーザーが少なくともこのロールを持っているプロジェクトに限定 (access_level)
with_custom_attributesbooleanいいえレスポンスにカスタム属性を含める(管理者のみ)
with_security_reports booleanいいえいずれかのビルドにセキュリティ・レポートのアーティファクトが存在するプロジェクトだけを返します。これは「セキュリティレポートが有効なプロジェクト」を意味します。デフォルトはfalse
  1. 類似度順指定されたsearch URL パラメータから計算された類似度スコアによって結果を並べ替えます。order_by=similarity を使用する場合、sort パラメータは無視されます。search パラメータが提供されない場合、API はnameで並べ替えられたプロジェクトを返します。

応答例

[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "master",
    "tag_list": [], //deprecated, use `topics` instead
    "topics": [],
    "archived": false,
    "visibility": "internal",
    "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
    "jobs_enabled": true,
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
      "kind": "group"
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
    "public_jobs": true,
    "shared_with_groups": [],
    "request_access_enabled": false
  }
]
note
グループ内のプロジェクトとグループに共有されているプロジェクトを区別するために、namespace 属性を使用 namespaceすることができます。namespace プロジェクトがグループに共有 namespaceされている場合、リクエスト先のグループとは異なります。

グループの共有プロジェクト一覧

このグループで共有されているプロジェクトの一覧を取得します。認証なしでアクセスした場合は、公開共有プロジェクトのみが返されます。

API の結果はページ分割されるため、デフォルトではこのリクエストは一度に 20 件の結果を返します。

GET /groups/:id/projects/shared

パラメータを指定します:

属性種類必須説明
id整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
archivedbooleanいいえアーカイブ状態による制限
visibility文字列です。いいえ視認性による制限public,internal, またはprivate
order_by文字列です。いいえ idnamepathcreated_atupdated_atlast_activity_at のフィールド順にプロジェクトを返します。デフォルトはcreated_at
sort文字列です。いいえ asc またはdesc 順序で descソートされたプロジェクトを返しますdesc 。デフォルトは desc
search文字列です。いいえ検索条件に一致する作成者プロジェクトのリストを返します。
simplebooleanいいえ各プロジェクトの限られたフィールドのみを返します。単純なフィールドのみが返されます。
starredbooleanいいえ現在のユーザーがスターを付けたプロジェクトによる制限
with_issues_enabledbooleanいいえイシュー機能が有効なプロジェクトで制限します。デフォルトはfalse
with_merge_requests_enabledbooleanいいえマージリクエスト機能が有効なプロジェクトによって制限されます。デフォルトはfalse
min_access_level整数。いいえ現在のユーザーが少なくともこのロールを持っているプロジェクトに限定 (access_level)
with_custom_attributesbooleanいいえレスポンスにカスタム属性を含める(管理者のみ)

応答例

[
   {
      "id":8,
      "description":"Shared project for Html5 Boilerplate",
      "name":"Html5 Boilerplate",
      "name_with_namespace":"H5bp / Html5 Boilerplate",
      "path":"html5-boilerplate",
      "path_with_namespace":"h5bp/html5-boilerplate",
      "created_at":"2020-04-27T06:13:22.642Z",
      "default_branch":"master",
      "tag_list":[], //deprecated, use `topics` instead
      "topics":[],
      "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git",
      "http_url_to_repo":"https://gitlab.com/h5bp/html5-boilerplate.git",
      "web_url":"https://gitlab.com/h5bp/html5-boilerplate",
      "readme_url":"https://gitlab.com/h5bp/html5-boilerplate/-/blob/master/README.md",
      "avatar_url":null,
      "star_count":0,
      "forks_count":4,
      "last_activity_at":"2020-04-27T06:13:22.642Z",
      "namespace":{
         "id":28,
         "name":"H5bp",
         "path":"h5bp",
         "kind":"group",
         "full_path":"h5bp",
         "parent_id":null,
         "avatar_url":null,
         "web_url":"https://gitlab.com/groups/h5bp"
      },
      "_links":{
         "self":"https://gitlab.com/api/v4/projects/8",
         "issues":"https://gitlab.com/api/v4/projects/8/issues",
         "merge_requests":"https://gitlab.com/api/v4/projects/8/merge_requests",
         "repo_branches":"https://gitlab.com/api/v4/projects/8/repository/branches",
         "labels":"https://gitlab.com/api/v4/projects/8/labels",
         "events":"https://gitlab.com/api/v4/projects/8/events",
         "members":"https://gitlab.com/api/v4/projects/8/members"
      },
      "empty_repo":false,
      "archived":false,
      "visibility":"public",
      "resolve_outdated_diff_discussions":false,
      "container_registry_enabled":true,
      "container_expiration_policy":{
         "cadence":"7d",
         "enabled":true,
         "keep_n":null,
         "older_than":null,
         "name_regex":null,
         "name_regex_keep":null,
         "next_run_at":"2020-05-04T06:13:22.654Z"
      },
      "issues_enabled":true,
      "merge_requests_enabled":true,
      "wiki_enabled":true,
      "jobs_enabled":true,
      "snippets_enabled":true,
      "can_create_merge_request_in":true,
      "issues_access_level":"enabled",
      "repository_access_level":"enabled",
      "merge_requests_access_level":"enabled",
      "forking_access_level":"enabled",
      "wiki_access_level":"enabled",
      "builds_access_level":"enabled",
      "snippets_access_level":"enabled",
      "pages_access_level":"enabled",
      "security_and_compliance_access_level":"enabled",
      "emails_disabled":null,
      "shared_runners_enabled":true,
      "lfs_enabled":true,
      "creator_id":1,
      "import_status":"failed",
      "open_issues_count":10,
      "ci_default_git_depth":50,
      "ci_forward_deployment_enabled":true,
      "ci_forward_deployment_rollback_allowed": true,
      "ci_allow_fork_pipelines_to_run_in_parent_project":true,
      "public_jobs":true,
      "build_timeout":3600,
      "auto_cancel_pending_pipelines":"enabled",
      "ci_config_path":null,
      "shared_with_groups":[
         {
            "group_id":24,
            "group_name":"Commit451",
            "group_full_path":"Commit451",
            "group_access_level":30,
            "expires_at":null
         }
      ],
      "only_allow_merge_if_pipeline_succeeds":false,
      "request_access_enabled":true,
      "only_allow_merge_if_all_discussions_are_resolved":false,
      "remove_source_branch_after_merge":true,
      "printing_merge_request_link_enabled":true,
      "merge_method":"merge",
      "suggestion_commit_message":null,
      "auto_devops_enabled":true,
      "auto_devops_deploy_strategy":"continuous",
      "autoclose_referenced_issues":true,
      "repository_storage":"default"
   }
]

グループの詳細

membership_lock フィールドは GitLab 14.10 で導入されました。

グループの全ての詳細を取得します。グループが公開されている場合、このエンドポイントは認証なしでアクセスできます。グループが公開されている場合、リクエストしたユーザーが管理者の場合。認証ありの場合は、ユーザーが管理者またはグループオーナーであれば、グループのrunners_token も返します。

GET /groups/:id

パラメータを指定します:

属性種類必須説明
id整数/文字列yes認証されたユーザーが所有するグループのID またはURL エンコードされたパス
with_custom_attributesbooleanいいえレスポンスにカスタム属性を含めます (管理者のみ)。
with_projectsbooleanいいえ指定したグループに属するプロジェクトの詳細を含めます (デフォルトはtrue)。(グループ内のすべてのプロジェクトの詳細を取得するには、list a group’s projects エンドポイントを使用してください)。
note
レスポンス内のprojects およびshared_projects 属性は非推奨で、APIv5 で削除される予定です。グループ内のすべてのプロジェクトの詳細を取得するには、list a group’s projectsまたはlist a group’s shared projectsエンドポイントを使用してください。
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4"

このエンドポイントは

  • GitLab 12.5 以前のすべてのプロジェクトと共有プロジェクト。
  • GitLab 12.6以降では最大100のプロジェクトと共有プロジェクト。グループ内のすべてのプロジェクトの詳細を取得するには、代わりにlist a group’s projects エンドポイントを使用してください。

応答例

{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "runners_token": "ba324ca7b1c77fc20bb9",
  "file_template_project_id": 1,
  "parent_id": null,
  "created_at": "2020-01-15T12:36:29.590Z",
  "shared_with_groups": [
    {
      "group_id": 28,
      "group_name": "H5bp",
      "group_full_path": "h5bp",
      "group_access_level": 20,
      "expires_at": null
    }
  ],
  "prevent_sharing_groups_outside_hierarchy": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "master",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "public",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "master",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
      "web_url": "https://gitlab.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "shared_projects": [ // Deprecated and will be removed in API v5
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "master",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "private",
      "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
      "public_jobs": true,
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
          "group_full_path": "twitter",
          "group_access_level": 30,
          "expires_at": null
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
          "group_full_path": "gitlab-org",
          "group_access_level": 10,
          "expires_at": "2018-08-14"
        }
      ]
    }
  ],
  "ip_restriction_ranges": null
}

prevent_sharing_groups_outside_hierarchy 属性はトップレベルのグループにのみ存在します。

GitLab PremiumやUltimateのユーザーにも属性が表示されます:

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • marked_for_deletion_on
  • membership_lock
  • wiki_access_level

追加のレスポンス属性

{
  "id": 4,
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "marked_for_deletion_on": "2020-04-03",
  "membership_lock": false,
  "wiki_access_level": "disabled",
  ...
}

パラメータwith_projects=false を追加すると、プロジェクトは返されません。

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4?with_projects=false"

応答例

{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "file_template_project_id": 1,
  "parent_id": null
}

グループアバターのダウンロード

グループのアバターを取得します。グループが公開されている場合、このエンドポイントは認証なしでアクセスできます。

GET /groups/:id/avatar
属性種類必須説明
id整数/文字列yesグループのID

使用例:

curl --header "PRIVATE-TOKEN: $GITLAB_LOCAL_TOKEN" \
  --remote-header-name \
  --remote-name \
  "https://gitlab.example.com/api/v4/groups/4/avatar"

結果制限の無効化

GitLab12.4以前のバージョンで開発されたインテグレーションは、100件という結果制限によって壊れてしまう可能性があります。

GitLab 12.5からGitLab 13.12では、グループのプロジェクト一覧エンドポイントを使用するようにマイグレーションしている間、制限を無効にすることができます。

RailsコンソールにアクセスできるGitLab管理者に以下のコマンドを実行してもらいましょう:

Feature.disable(:limit_projects_in_groups_api)

GitLab 14.0以降では、制限を無効にすることはできません。

新しいグループ

note
GitLab SaaSでは、親グループのないグループを作成するにはGitLab UIを使用する必要があります。APIを使用することはできません。

新しいプロジェクトグループを作成します。グループを作成できるユーザーだけが利用できます。

POST /groups

パラメータを指定します:

属性種類必須説明
name文字列です。yesグループの名前。
path文字列です。yesグループのパス。
auto_devops_enabledbooleanいいえこのグループ内のすべてのプロジェクトのデフォルトはAuto DevOpsパイプラインです。
avatar混合いいえグループのアバター用画像ファイル。GitLab 12.9で導入されました。
default_branch_protection整数。いいえ default_branch_protection](#options-for-default_branch_protection)については[オプションを参照してください。デフォルトはグローバルレベルのデフォルトブランチプロテクション設定です。
description文字列です。いいえグループの説明。
emails_disabledbooleanいいえメール通知を無効にします。
lfs_enabledbooleanいいえこのグループのプロジェクトに対して、Large File Storage(LFS) を有効/無効にします。
mentions_disabledbooleanいいえグループが言及されないようにします。
parent_id整数。いいえネストされたグループを作成するための親グループID。
project_creation_level文字列です。いいえ開発者がグループでプロジェクトを作成できるかどうかを指定します。noone (No one)、maintainer (メンテナーのロールを持つユーザー)、developer (開発者またはメンテナーのロールを持つユーザー) のいずれかを指定します。
request_access_enabledbooleanいいえユーザーによるメンバーへのアクセス要求を許可します。
require_two_factor_authenticationbooleanいいえこのグループのすべてのユーザーに二要素認証の設定を要求します。
share_with_group_lockbooleanいいえこのグループ内で他のグループとプロジェクトを共有しないようにします。
subgroup_creation_level文字列です。いいえ サブグループの作成を許可します。owner (オーナー)、またはmaintainer (メンテナーのロールを持つユーザー)。
two_factor_grace_period整数。いいえ二要素認証が実施されるまでの時間(時間単位)。
visibility文字列です。いいえグループの可視性。private,internal, またはpublic のいずれか。
membership_lock booleanいいえこのグループのプロジェクトにユーザーを追加することはできません。
extra_shared_runners_minutes_limit 整数。いいえ管理者のみが設定できます。このグループの追加計算分。
shared_runners_minutes_limit 整数。いいえ管理者のみが設定できます。このグループの月間最大計算分数。nil (デフォルト、システムのデフォルトを継承)、0 (無制限)、または> 0
wiki_access_level 文字列です。いいえWiki のアクセスレベル。disabled,private, またはenabled のいずれかです。

のオプションdefault_branch_protection

default_branch_protection 属性は、開発者とメンテナーのどちらのロールを持つユーザーが該当するデフォルトブランチにプッシュできるかを決定します:

説明
0保護なし。開発者またはメンテナーのロールを持つユーザーは、以下のことができます:
- 新しいコミットをプッシュする
- 変更を強制的にプッシュする
- ブランチを削除する
1部分的な保護。開発者またはメンテナーのロールを持つユーザーは、以下のことができます:
- 新しいコミットのプッシュ
2完全な保護。メンテナーのロールを持つユーザーだけができます:
- 新しいコミットをプッシュ
3プッシュからの保護。メンテナーのロールを持つユーザーは次のことができます:
- 新しいコミットをプッシュする
- 変更を強制的にプッシュする
- マージリクエストを受け付ける
開発者ロールを持つユーザーは次のことができます:
- マージリクエストを受け付ける
4最初のプッシュ後の完全な保護。開発者ロールを持つユーザーは以下のことができます:
- 空のリポジトリにコミットをプッシュします。
メンテナーのロールを持つユーザーは次のことができます:
- 新しいコミットをプッシュする
- マージリクエストを受け入れる

新しいサブグループ

これは新規グループの作成に似ています。List groupsの呼び出しからparent_id 。次に、必要な項目を入力します:

  • subgroup_path
  • subgroup_name
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \
     "https://gitlab.example.com/api/v4/groups/"

プロジェクトをグループに移します。

プロジェクトをグループのネームスペースに転送します。インスタンス管理者のみが利用可能ですが、インスタンスの管理者アクセス権を必要としない別の API エンドポイントも利用可能です。プロジェクトのリポジトリにタグ付きパッケージが存在する場合、プロジェクトの転送に失敗することがあります。

POST  /groups/:id/projects/:project_id

パラメータを指定します:

属性種類必須説明
id整数/文字列yes 対象グループのIDまたはURLエンコードされたパス
project_id整数/文字列yes プロジェクトのIDまたはURLエンコードされたパス
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/4/projects/56"

ユーザーがグループを移動できるグループの取得

GitLab 15.4 で導入されました

ユーザーがグループを転送できるグループのリストを取得します。

GET /groups/:id/transfer_locations
属性種類必須説明
id整数または文字列。 {チェックサークル}はい 転送するグループのIDまたはURLエンコードされたパス
search文字列です。 {点線円}いいえ検索するグループ名。

リクエストの例

curl --request GET "https://gitlab.example.com/api/v4/groups/1/transfer_locations"

応答例

[
  {
    "id": 27,
    "web_url": "https://gitlab.example.com/groups/gitlab",
    "name": "GitLab",
    "avatar_url": null,
    "full_name": "GitLab",
    "full_path": "GitLab"
  },
  {
    "id": 31,
    "web_url": "https://gitlab.example.com/groups/foobar",
    "name": "FooBar",
    "avatar_url": null,
    "full_name": "FooBar",
    "full_path": "FooBar"
  }
]

グループを新しい親グループに移す / サブグループを最上位グループにする

GitLab 14.6で導入されました

グループを新しい親グループに移したり、サブグループをトップレベルグループにすることができます。管理者とユーザーが利用できます:

POST  /groups/:id/transfer

パラメータを指定します:

属性種類必須説明
id整数。yes転送するグループのID。
group_id整数。いいえ新しい親グループのID。指定されない場合、転送するグループはトップレベルグループになります。
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7"

グループの更新

unique_project_download_limitGitLab 15.3で導入された unique_project_download_limit_interval_in_secondsunique_project_download_limit_allowlistlimit_unique_project_downloads_per_namespace_userというフラグがあります。デフォルトでは無効になっています。

フラグ: セルフマネジメントGitLabでは、デフォルトでunique_project_download_limit,unique_project_download_limit_interval_in_seconds,unique_project_download_limit_allowlist,auto_ban_user_on_excessive_projects_download は利用できません。これらを利用可能にするには、管理者がlimit_unique_project_downloads_per_namespace_userという機能フラグを有効にします。

プロジェクトグループを更新します。グループオーナーと管理者のみが利用できます。

PUT /groups/:id
属性種類必須説明
id整数。yesグループのID。
name文字列です。いいえグループの名前。
path文字列です。いいえグループのパス。
auto_devops_enabledbooleanいいえこのグループ内のすべてのプロジェクトのデフォルトはAuto DevOpsパイプラインです。
avatar混合いいえグループのアバター用画像ファイル。GitLab 12.9で導入されました。
default_branch_protection整数。いいえ default_branch_protection](#options-for-default_branch_protection)については[オプションを参照。
description文字列です。いいえグループの説明。
emails_disabledbooleanいいえメール通知を無効にします。
lfs_enabledbooleanいいえこのグループのプロジェクトに対して、Large File Storage(LFS) を有効/無効にします。
mentions_disabledbooleanいいえグループが言及されないようにします。
prevent_sharing_groups_outside_hierarchybooleanいいえ グループ階層外でのグループ共有を防止する」を参照してください。この属性はトップレベルのグループでのみ有効です。GitLab 14.1 で導入されました。
project_creation_level文字列です。いいえ開発者がグループでプロジェクトを作成できるかどうかを指定します。noone (No one)、maintainer (メンテナーのロールを持つユーザー)、developer (開発者またはメンテナーのロールを持つユーザー) のいずれかを指定します。
request_access_enabledbooleanいいえユーザーによるメンバーへのアクセス要求を許可します。
require_two_factor_authenticationbooleanいいえこのグループのすべてのユーザーに二要素認証の設定を要求します。
shared_runners_setting文字列です。いいえ shared_runners_setting](#options-for-shared_runners_setting)については、[オプション を参照してください。グループのサブグループとプロジェクトの共有ランナーを有効または無効にします。
share_with_group_lockbooleanいいえこのグループ内で他のグループとプロジェクトを共有しないようにします。
subgroup_creation_level文字列です。いいえ サブグループの作成を許可します。owner (オーナー)、またはmaintainer (メンテナーのロールを持つユーザー)。
two_factor_grace_period整数。いいえ二要素認証が実施されるまでの時間(時間単位)。
visibility文字列です。いいえグループの可視性レベル。private,internal, またはpublic のいずれかです。
extra_shared_runners_minutes_limit 整数。いいえ管理者のみが設定できます。このグループの追加計算分。
file_template_project_id 整数。いいえカスタム・ファイル・テンプレートをロードするプロジェクトのID。
membership_lock booleanいいえこのグループのプロジェクトにユーザーを追加することはできません。
prevent_forking_outside_group booleanいいえ有効にすると、ユーザーはこのグループのプロジェクトを外部のネームスペースにフォークできなくなります。
shared_runners_minutes_limit 整数。いいえ管理者のみが設定できます。このグループの月間最大計算分数。nil (デフォルト、システムのデフォルトを継承)、0 (無制限)、または> 0
unique_project_download_limit 整数。いいえユーザーが禁止される前に、指定された期間内にダウンロードできるユニークなプロジェクトの最大数。トップレベルグループでのみ使用可能。デフォルト:0、最大:10,000.
unique_project_download_limit_interval_in_seconds 整数。いいえユーザーが禁止される前に最大量のプロジェクトをダウンロードできる期間。トップレベルグループでのみ利用可能。デフォルト:0、最大:864,000秒(10日間)。
unique_project_download_limit_allowlist 文字列の配列。いいえ一意のプロジェクトダウンロード制限から除外されるユーザー名のリスト。トップレベルグループでのみ利用可能。デフォルト:[] 、最大:100ユーザー名。
unique_project_download_limit_alertlist 整数の配列いいえ一意のプロジェクトのダウンロード制限を超えたときに電子メールで送信されるユーザーIDのリスト。トップレベルグループでのみ利用可能。デフォルト:[] 、最大:100ユーザーID。GitLab 15.9で導入
auto_ban_user_on_excessive_projects_download booleanいいえ有効にすると、unique_project_download_limitunique_project_download_limit_interval_in_seconds で指定されたユニークなプロジェクトの最大数を超えてダウンロードした場合、ユーザーは自動的にグループから追放されます。 GitLab 15.4 で導入されました
ip_restriction_ranges 文字列です。いいえグループアクセスを制限するIPアドレスまたはサブネットマスクのカンマ区切りリスト。GitLab 15.4 で導入
wiki_access_level 文字列です。いいえWiki のアクセスレベル。disabled,private, またはenabled のいずれかです。
note
レスポンス内のprojects およびshared_projects 属性は非推奨で、APIv5 で削除される予定です。グループ内のすべてのプロジェクトの詳細を取得するには、list a group’s projectsまたはlist a group’s shared projectsエンドポイントを使用してください。
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5?name=Experimental"

このエンドポイントは

  • GitLab 12.5 以前のすべてのプロジェクトと共有プロジェクト。
  • GitLab 12.6以降では最大100のプロジェクトと共有プロジェクト。グループ内のすべてのプロジェクトの詳細を取得するには、代わりにlist a group’s projects エンドポイントを使用してください。

応答例

{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
  "visibility": "internal",
  "avatar_url": null,
  "web_url": "http://gitlab.example.com/groups/h5bp",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Foobar Group",
  "full_path": "h5bp",
  "file_template_project_id": 1,
  "parent_id": null,
  "created_at": "2020-01-15T12:36:29.590Z",
  "prevent_sharing_groups_outside_hierarchy": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 9,
      "description": "foo",
      "default_branch": "master",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "public": false,
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "Experimental / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": true,
      "created_at": "2016-04-05T21:40:50.169Z",
      "last_activity_at": "2016-04-06T16:52:08.432Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "Experimental",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "ip_restriction_ranges": null
}

prevent_sharing_groups_outside_hierarchy 属性は、トップレベルのグループに対してのみレスポンスに存在します。

GitLabプレミアムまたはアルティメットのユーザーにもwiki_access_level 属性が表示されます。

結果制限の無効化

GitLab12.4以前のバージョンで開発されたインテグレーションは、100件という結果制限によって壊れてしまう可能性があります。

GitLab 12.5からGitLab 13.12では、グループのプロジェクト一覧エンドポイントを使用するようにマイグレーションしている間、制限を無効にすることができます。

RailsコンソールにアクセスできるGitLab管理者に以下のコマンドを実行してもらいましょう:

Feature.disable(:limit_projects_in_groups_api)

GitLab 14.0以降では、制限を無効にすることはできません。

のオプションshared_runners_setting

shared_runners_setting 属性は、グループのサブグループとプロジェクトで共有ランナーを有効にするかどうかを決定します。

説明
enabledこのグループ内のすべてのプロジェクトとサブグループの共有Runnerを有効にします。
disabled_and_overridableこのグループ内のすべてのプロジェクトとサブグループに対して共有ランナーを無効にしますが、サブグループはこの設定を上書きできます。
disabled_and_unoverridableこのグループ内のすべてのプロジェクトとサブグループに対して共有ランナーを無効にし、サブグループがこの設定を上書きできないようにします。
disabled_with_override(Deprecated. Usedisabled_and_overridable) このグループのすべてのプロジェクトとサブグループの共有ランナーを無効にします。

グループアバターのアップロード

GitLab 12.9で導入されました

アバターファイルをファイルシステムからアップロードするには、--form 引数を使います。これにより、curl はヘッダContent-Type: multipart/form-data を使ってデータを投稿します。file= パラメータはファイルシステム上のファイルを指し、その前に@をつけなければなりません。例えば

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" \
     --form "avatar=@/tmp/example.png"

グループアバターの削除

GitLab 15.4で導入されました

グループアバターを削除するには、avatar 属性に空白の値を使います。

リクエストの例

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" \
     --data "avatar="

グループの削除

  • サブグループの即時削除はGitLab 15.3でimmediate_delete_subgroup_api というフラグで 導入されました。デフォルトでは無効になっています。
  • サブグループの即時削除はGitLab.comで有効になり、GitLab 15.4で自己管理されるようになりました。
  • サブグループの即時削除は、GitLab 15.4ではデフォルトで有効になっていました。
  • サブグループを即座に削除するフラグimmediate_delete_subgroup_api は GitLab 15.9 で削除されました。

グループオーナーと管理者のみが利用できます。

このエンドポイントは

  • PremiumおよびUltimate層では、削除するグループをマークします。削除はデフォルトで7日後に行われますが、インスタンス設定で保持期間を変更できます。
  • 無料ティアでは、グループを直ちに削除し、グループ内のすべてのプロジェクトを削除するバックグラウンドジョブをキューに入れます。
  • サブグループが削除マークされている場合、直ちにサブグループを削除します (GitLab 15.4 以降)。このエンドポイントはトップレベルのグループを即座に削除しません。
DELETE /groups/:id

パラメータを指定します:

属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
permanently_remove 論理値/文字列いいえサブグループが削除マークされている場合、即座に削除します。GitLab 15.4 で導入
full_path 文字列です。いいえ permanently_remove で使用するサブグループのフルパス。 GitLab 15.4 で導入されました。サブグループのパスを調べるには、グループの詳細を参照してください。

レスポンスは、ユーザーに作成者がいる場合は202 Accepted となります。

note
GitLab.comグループがサブスクリプションにリンクされている場合は削除できません。そのようなグループを削除するには、まずサブスクリプションを別のグループにリンクしてください。

削除されたグループの復元

GitLab 12.8で導入されました

削除されたグループを復元します。

POST /groups/:id/restore

パラメータを指定します:

属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス

グループの検索

名前またはパスに文字列が一致するすべてのグループを取得します。

GET /groups?search=foobar
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]

プロビジョニングされたユーザーのリスト

GitLab 14.8 で導入されました。

指定したグループによってプロビジョニングされたユーザーの一覧を取得します。サブグループは含まれません。このリストに含まれるユーザーはエンタープライズユーザーとみなされます。

グループに少なくともメンテナーのロールが必要です。

GET /groups/:id/provisioned_users

パラメータを指定します:

属性種類必須説明
id整数/文字列yesグループのIDまたはURLエンコードされたパス
username文字列です。いいえ特定のユーザー名を持つ単一のユーザーを返します。
search文字列です。いいえ名前、Eメール、ユーザー名でユーザーを検索
activebooleanいいえアクティビティユーザーのみを返します。
blockedbooleanいいえブロックされたユーザーのみを返します。
created_afterdatetimeいいえ指定した時間以降に作成されたユーザーを返します。
created_beforedatetimeいいえ指定した時間以前に作成されたユーザーを返します。

応答例

[
  {
    "id": 66,
    "username": "user22",
    "name": "John Doe22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [ ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null
  },
  ...
]

サービスアカウント

サービスアカウントユーザーの作成

GitLab 16.1 で導入されました

自動生成されたメールアドレスとユーザー名を持つサービスアカウントユーザーを作成します。

POST /groups/:id/service_accounts
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts"

応答例

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user"
}

サービスアカウントユーザーの個人アクセストークンの作成

GitLab 16.1 で導入されました

POST /groups/:id/service_accounts/:user_id/personal_access_tokens
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens" --data "scopes[]=api" --data "name=service_accounts_token"

応答例

{
  "id":6,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:47:13.900Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2024-06-12",
  "token":"<token_value>"
}

サービスアカウントユーザーの個人アクセストークンのローテーション

GitLab 16.1 で導入されました

POST /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id/rotate
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6/rotate"

応答例

{
  "id":7,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:54:49.962Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2023-06-20",
  "token":"<token_value>"
}

フック

グループフックやWebhookとも呼ばれます。これらは、システム全体に適用されるシステムフックや、1つのプロジェクトに限定されるプロジェクトフックとは異なります。

グループフック一覧

グループフックの一覧を取得します。

GET /groups/:id/hooks
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス

グループフックの取得

グループの特定のフックを取得します。

属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
hook_id整数。yesグループフックのID
GET /groups/:id/hooks/:hook_id
{
  "id": 1,
  "url": "http://example.com/hook",
  "group_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "confidential_note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "deployment_events": true,
  "releases_events": true,
  "subgroup_events": true,
  "enable_ssl_verification": true,
  "repository_update_events": false,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [ ],
  "created_at": "2012-10-12T17:04:47Z"
}

グループフックの追加

指定したグループにフックを追加します。

POST /groups/:id/hooks
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
url文字列です。yesフックのURL
push_eventsbooleanいいえプッシュイベントのトリガーフック
push_events_branch_filter文字列です。なしブランチが一致した場合のみ、プッシュイベントをトリガーします。
issues_eventsbooleanいいえイシューイベントのトリガーフック
confidential_issues_eventsbooleanいいえ機密イシューイベントのトリガーフック
merge_requests_eventsbooleanいいえマージリクエストイベントのトリガーフック
tag_push_eventsbooleanいいえタグプッシュイベントのトリガーフック
note_eventsbooleanいいえノートイベントのトリガーフック
confidential_note_eventsbooleanいいえ機密ノートイベントのトリガーフック
job_eventsbooleanいいえジョブイベントのトリガーフック
pipeline_eventsbooleanいいえパイプラインイベントのトリガーフック
wiki_page_eventsbooleanいいえWikiページイベントのトリガーフック
deployment_eventsbooleanいいえデプロイイベントのトリガーフック
releases_eventsbooleanいいえリリースイベントのトリガーフック
subgroup_eventsbooleanいいえサブグループイベントのトリガーフック
enable_ssl_verificationbooleanいいえフック起動時にSSL検証を行うかどうか
token文字列です。いいえ受信したペイロードを検証するためのシークレットトークン。

グループ編集フック

指定したグループのフックを編集します。

PUT /groups/:id/hooks/:hook_id
属性種類必須説明
id整数または文字列。yesグループのIDまたはURLエンコードされたパス
hook_id整数。yesグループフックのID。
url文字列です。yesフックのURL。
push_eventsbooleanいいえプッシュイベントのトリガーフック。
push_events_branch_filter文字列です。なしブランチが一致した場合のみ、プッシュイベントをトリガーします。
issues_eventsbooleanいいえイシューイベントのトリガーフック。
confidential_issues_eventsbooleanいいえ機密イシューイベントのトリガーフック。
merge_requests_eventsbooleanいいえマージリクエストイベントのトリガーフック。
tag_push_eventsbooleanいいえタグプッシュイベントのトリガーフック。
note_eventsbooleanいいえノートイベントのトリガーフック。
confidential_note_eventsbooleanいいえ秘匿音符イベントのトリガーフック。
job_eventsbooleanいいえジョブイベントのトリガーフック。
pipeline_eventsbooleanいいえパイプラインイベントのトリガーフック。
wiki_page_eventsbooleanいいえWikiページイベントのトリガーフック。
deployment_eventsbooleanいいえデプロイイベントのトリガーフック。
releases_eventsbooleanいいえリリースイベントのトリガーフック。
subgroup_eventsbooleanいいえサブグループイベントのトリガーフック。
enable_ssl_verificationbooleanいいえフック起動時にSSL検証を行います。
token文字列です。いいえ受信したペイロードを検証するためのシークレットトークン。レスポンスでは返されません。Webhook URL を変更すると、シークレットトークンはリセットされ、保持されません。

グループフックの削除

グループからフックを削除します。これはべき等メソッドで、複数回呼び出すことができます。フックが使用可能か不可能かのどちらかです。

DELETE /groups/:id/hooks/:hook_id
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
hook_id整数。yesグループフックのID。

グループ監査イベント

グループ監査イベントは、Group Audit Events API経由でアクセスできます。

LDAPとグループの同期

グループをリンク先のLDAPグループと同期します。グループのオーナーと管理者のみが使用できます。

POST /groups/:id/ldap_sync

パラメータを指定します:

  • id (必須) - ユーザーグループのIDまたはパス。

グループのメンバー

グループメンバー」ドキュメントを参照してください。

LDAPグループリンクの一覧表示、追加、削除ができます。

LDAP グループのリンクを一覧表示します。

GET /groups/:id/ldap_group_links
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス

CN またはフィルタを使用して LDAP グループリンクを追加します。フィルタによるグループリンクの追加は、Premium Tier 以上でのみサポートされます。

POST /groups/:id/ldap_group_links
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
cn文字列です。いいえLDAPグループのCN
filter文字列です。いいえグループのLDAPフィルター
group_access整数。yes ロール (access_level) LDAPグループのメンバー用
provider文字列です。yesLDAPグループリンクのLDAPプロバイダ
note
LDAP グループ・リンクを定義するには、cn またはfilter を指定します。

LDAP グループ・リンクを削除します。非推奨。将来のリリースで削除される予定です。

DELETE /groups/:id/ldap_group_links/:cn
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
cn文字列です。yesLDAPグループのCN

特定の LDAP プロバイダの LDAP グループリンクを削除します。非推奨。将来のリリースで削除される予定です。

DELETE /groups/:id/ldap_group_links/:provider/:cn
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
cn文字列です。yesLDAPグループのCN
provider文字列です。yesLDAPグループリンクのLDAPプロバイダ

CN またはフィルタを使用して LDAP グループリンクを削除します。フィルタによる削除は、Premium Tier 以上でのみサポートされています。

DELETE /groups/:id/ldap_group_links
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
cn文字列です。いいえLDAPグループのCN
filter文字列です。いいえグループのLDAPフィルター
provider文字列です。yesLDAPグループリンクのLDAPプロバイダ
note
LDAP グループ・リンクを削除するには、cn またはfilter を指定します。

SAMLグループリンクの一覧、取得、追加、削除。

SAML グループリンクを一覧表示します。

GET /groups/:id/saml_group_links

サポートされる属性:

属性種類必須説明
id整数/文字列yesグループのIDまたはURLエンコードされたパス

成功した場合は、200 と以下のレスポンス属性を返します:

属性種類説明
[].name文字列です。SAML グループの名前。
[].access_level整数。 ロール (access_level) SAML グループのメンバー用。この属性は GitLab 15.3.0 から GitLab 15.3.3 まで文字列型でした。

リクエストの例

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links"

応答例

[
  {
    "name": "saml-group-1",
    "access_level": 10
  },
  {
    "name": "saml-group-2",
    "access_level": 40
  }
]

グループの SAML グループ・リンクを取得します。

GET /groups/:id/saml_group_links/:saml_group_name

サポートされる属性:

属性種類必須説明
id整数/文字列yesグループのIDまたはURLエンコードされたパス
saml_group_name文字列です。yesSAML グループ名

成功した場合は、200 と以下のレスポンス属性を返します:

属性種類説明
name文字列です。SAML グループの名前。
access_level整数。 ロール (access_level) SAML グループのメンバー用。この属性は GitLab 15.3.0 から GitLab 15.3.3 まで文字列型でした。

リクエストの例

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"

応答例

{
"name": "saml-group-1",
"access_level": 10
}

グループの SAML グループ・リンクを追加します。

POST /groups/:id/saml_group_links

サポートされる属性:

属性種類必須説明
id整数または文字列。yesグループのIDまたはURLエンコードされたパス
saml_group_name文字列です。yesSAML グループ名
access_level整数。yes ロール (access_level) SAML グループのメンバ用

成功した場合は、201 と以下のレスポンス属性を返します:

属性種類説明
name文字列です。SAML グループの名前。
access_level整数。 ロール (access_level) SAML グループのメンバー用。この属性は GitLab 15.3.0 から GitLab 15.3.3 まで文字列型でした。

リクエストの例

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{ "saml_group_name": "<your_saml_group_name`>", "access_level": <chosen_access_level> }' --url  "https://gitlab.example.com/api/v4/groups/1/saml_group_links"

応答例

{
"name": "saml-group-1",
"access_level": 10
}

グループの SAML グループ・リンクを削除します。

DELETE /groups/:id/saml_group_links/:saml_group_name

サポートされる属性:

属性種類必須説明
id整数/文字列yesグループのIDまたはURLエンコードされたパス
saml_group_name文字列です。yesSAML グループ名

成功した場合は、レスポンス・ボディなしで204 ステータス・コードを返します。

リクエストの例

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"

グループ内の名前空間

デフォルトでは、API の結果はページ分割されるため、グループには一度に 20 のネームスペースしか取得されません。

それ以上 (最大 100) を取得するには、API 呼び出しの引数として以下を渡します:

/groups?per_page=100

また、ページを切り替えるには、以下を追加します:

/groups?per_page=100&page=2

グループバッジ

詳しくはグループバッジのドキュメントをご覧ください。

グループのインポート/エクスポート

詳しくは、Group Import/ExportおよびGroup Relations Exportをご覧ください。

グループとグループの共有

これらのエンドポイントは、グループを別のグループと共有するためのリンクを作成したり削除したりします。詳しくはGitLab Groupsページにある関連する説明を参照してください。

グループを別のグループと共有します。成功すると200グループの詳細を返します。

POST /groups/:id/share
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
group_id整数。yes共有するグループのID
group_access整数。yes ロール (access_level) をグループに付与します。
expires_at文字列です。いいえISO 8601フォーマットでのシェア有効期限:2016-09-26

他のグループからグループの共有を解除します。成功すると204 を返し、内容は返されません。

DELETE /groups/:id/share/:group_id
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
group_id整数。yes共有するグループのID

プッシュルール

GitLab 13.4で導入されました。

グループプッシュルールの取得

グループのプッシュルールを取得します。

グループオーナーと管理者のみが利用できます。

GET /groups/:id/push_rule
属性種類必須説明
id整数/文字列yesグループのIDまたはグループのURLエンコードされたパス
{
  "id": 2,
  "created_at": "2020-08-17T19:09:19.580Z",
  "commit_message_regex": "[a-zA-Z]",
  "commit_message_negative_regex": "[x+]",
  "branch_name_regex": "[a-z]",
  "deny_delete_tag": true,
  "member_check": true,
  "prevent_secrets": true,
  "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$",
  "file_name_regex": "(exe)$",
  "max_file_size": 100
}

GitLab Premium または Ultimateのユーザーにはcommit_committer_checkreject_unsigned_commits パラメータも表示されます:

{
  "id": 2,
  "created_at": "2020-08-17T19:09:19.580Z",
  "commit_committer_check": true,
  "reject_unsigned_commits": false,
  ...
}

グループプッシュルールの追加

指定したグループにプッシュルールを追加します。

グループオーナーと管理者のみが利用できます。

POST /groups/:id/push_rule
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
deny_delete_tagbooleanいいえタグの削除を拒否
member_checkbooleanいいえGitLab ユーザーだけがコミットを作成できるようにします。
prevent_secretsbooleanいいえ シークレットを含む可能性のあるファイルは拒否されます。
commit_message_regex文字列です。いいえすべてのコミット・メッセージはこの属性で指定された正規表現にマッチしなければなりません、Fixed \d+\..*
commit_message_negative_regex文字列です。いいえこの属性で指定された正規表現にマッチするコミットメッセージは許可されません、ssh\:\/\/
branch_name_regex文字列です。いいえすべてのブランチ名は、この属性で指定された正規表現にマッチする必要があります、(feature|hotfix)\/*
author_email_regex文字列です。いいえすべてのコミット作成者のメールはこの属性で指定された正規表現にマッチしなければなりません、@my-company.com$
file_name_regex文字列です。いいえこの属性で指定された正規表現にマッチするファイル名は許可されません(jar|exe)$
max_file_size整数。いいえ許可される最大ファイルサイズ(MB)
commit_committer_checkbooleanいいえ検証済みの電子メールを使用してプッシュされたコミットのみが許可されます。
reject_unsigned_commitsbooleanいいえGPGで署名されたコミットのみ許可
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule"

レスポンス

{
    "id": 19,
    "created_at": "2020-08-31T15:53:00.073Z",
    "commit_message_regex": "[a-zA-Z]",
    "commit_message_negative_regex": "[x+]",
    "branch_name_regex": null,
    "deny_delete_tag": false,
    "member_check": false,
    "prevent_secrets": false,
    "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$",
    "file_name_regex": null,
    "max_file_size": 100
}

グループプッシュルールの編集

指定したグループのプッシュルールを編集します。

グループオーナーと管理者のみが利用できます。

PUT /groups/:id/push_rule
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス
deny_delete_tagbooleanいいえタグの削除を拒否
member_checkbooleanいいえ既存のGitLabユーザーのみが作成できるようにコミットを制限します。
prevent_secretsbooleanいいえ シークレットを含む可能性のあるファイルは拒否されます。
commit_message_regex文字列です。いいえすべてのコミット・メッセージはこの属性で指定された正規表現にマッチしなければなりません、Fixed \d+\..*
commit_message_negative_regex文字列です。いいえこの属性で指定された正規表現にマッチするコミットメッセージは許可されません、ssh\:\/\/
branch_name_regex文字列です。いいえすべてのブランチ名は、この属性で指定された正規表現にマッチする必要があります、(feature|hotfix)\/*
author_email_regex文字列です。いいえすべてのコミット作成者のメールはこの属性で指定された正規表現にマッチしなければなりません、@my-company.com$
file_name_regex文字列です。いいえこの属性で指定された正規表現にマッチするファイル名は許可されません(jar|exe)$
max_file_size整数。いいえ許可される最大ファイルサイズ(MB)
commit_committer_checkbooleanいいえ検証済みの電子メールを使用してプッシュされたコミットのみが許可されます。
reject_unsigned_commitsbooleanいいえGPGで署名されたコミットのみ許可
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule"

レスポンス

{
    "id": 19,
    "created_at": "2020-08-31T15:53:00.073Z",
    "commit_message_regex": "[a-zA-Z]",
    "commit_message_negative_regex": "[x+]",
    "branch_name_regex": null,
    "deny_delete_tag": false,
    "member_check": false,
    "prevent_secrets": false,
    "author_email_regex": "^[A-Za-z0-9.]+@staging.gitlab.com$",
    "file_name_regex": null,
    "max_file_size": 100
}

グループプッシュルールの削除

グループのプッシュルールを削除します。

グループオーナーと管理者のみが利用できます。

DELETE /groups/:id/push_rule
属性種類必須説明
id整数/文字列yes グループのIDまたはURLエンコードされたパス