正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

グループAPI

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、GitLabグループを表示および管理します。詳細については、グループを参照してください。

エンドポイントの応答は、グループ内の権限によって異なる場合があります。

単一のグループを取得する

1つのグループのすべての詳細を取得します。グループが公開されている場合、このエンドポイントには認証なしでアクセスできます。グループが公開されている場合、リクエストするユーザーが管理者であれば認証なしでアクセスできます。認証を使用すると、ユーザーが管理者であるか、オーナーのロールを持っている場合、グループのrunners_tokenとenabled_git_access_protocolも返されます。

GET /groups/:id

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。
with_projectsブール値いいえ指定されたグループに属するプロジェクトの詳細を含めます（デフォルトはtrue）。（非推奨。v5で削除される予定です。グループ内のすべてのプロジェクトの詳細を取得するには、グループのプロジェクトをリストするを使用します）。

レスポンス内のprojects属性とshared_projects属性は非推奨であり、v5で削除される予定です。グループ内のすべてのプロジェクトの詳細を取得するには、グループのプロジェクトをリストまたはグループの共有プロジェクトをリストを使用します。

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

このエンドポイントは、最大100個のプロジェクトと共有プロジェクトを返します。グループ内のすべてのプロジェクトの詳細を取得するには、代わりにグループのプロジェクトをリストを使用します。

レスポンス例:

{
  "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,
  "enabled_git_access_protocol": "all",
  "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": "main",
      "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": "main",
      "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": "main",
      "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,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false
}

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
  • duo_features_enabled
  • lock_duo_features_enabled
  • duo_availability
  • experiment_features_enabled

その他のレスポンス属性:

{
  "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",
  "duo_features_enabled": true,
  "lock_duo_features_enabled": false,
  "duo_availability": "default_on",
  "experiment_features_enabled": false,
  ...
}

パラメータ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
}

グループのリストを取得する

すべてのグループのリストを取得する

認証済みユーザーの表示可能なグループのリストを取得します。認証なしでアクセスすると、公開グループのみが返されます。

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

認証なしでアクセスする場合、このキーセットページネーションもサポートします:

パラメータは以下のとおりです:

属性型必須説明
skip_groups整数の配列いいえ渡されたグループIDをスキップします。
all_availableブール値いいえtrueの場合、アクセス可能なすべてのグループを返します。falseの場合、ユーザーがメンバーであるグループのみを返します。ユーザーの場合はfalseがデフォルトであり、管理者の場合はtrueがデフォルトです。認証されていないリクエストでは、常にすべての公開グループが返されます。owned属性とmin_access_level属性が優先されます。
search文字列いいえ検索条件に一致する認証済みグループのリストを返します。
order_by文字列いいえグループをname、path、id、またはsimilarityで並べ替えます。デフォルトはnameです。
sort文字列いいえグループをascまたはdescの順に並べ替えます。デフォルトはascです。
statisticsブール値いいえグループ統計を含めます（管理者のみ）。
トップレベルグループの場合、レスポンスはUIに表示される完全なroot_storage_statisticsデータを返します。GitLab 17.4で導入されました。
visibility文字列いいえpublic、internal、またはprivateのグループに制限します。
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。
ownedブール値いいえ現在の認証済みユーザーが明示的に所有するグループに制限します。
min_access_level整数いいえ現在のユーザーが、指定されているロール（access_level）以上のロールを持っているグループに制限します。
top_level_onlyブール値いいえトップレベルグループに制限します（すべてのサブグループを除外）。
repository_storage文字列いいえグループが使用しているリポジトリストレージでフィルタリングします（管理者のみ）。GitLab 16.3で導入されました。PremiumおよびUltimateのみです。
marked_for_deletion_on日付いいえグループが削除対象としてマークされた日付でフィルタリングします。GitLab 17.1で導入されました。PremiumおよびUltimateのみです。
activeブール値いいえアーカイブされておらず、削除対象としてマークされていないグループに制限します。
archivedブール値いいえアーカイブされたグループで制限します。Introduced in GitLab 18.2.このパラメータは実験的機能です。
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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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を追加すると、認証済みユーザーが管理者の場合、追加のグループ統計が返されます。トップレベルグループの場合、root_storage_statisticsも追加されます。

GET /groups?statistics=true

パラメータstatistics=trueを使用すると、認証済みユーザーが管理者の場合、レスポンスにはコンテナレジストリのストレージサイズに関する情報が含まれます:

  • container_registry_size: グループとそのサブグループ内のすべてのコンテナで使用されるストレージサイズの合計（バイト単位）。グループのプロジェクトとサブグループ内のすべてのリポジトリサイズの合計として計算されます。メタデータデータベースが有効になっている場合にのみ使用できます。

  • container_registry_size_is_estimated: サイズが、すべてのの実際のデータに基づいた正確な計算であるか（false）、パフォーマンスの制約による見積もりであるか（true）を示します。

GitLab Self-Managedインスタンスの場合、コンテナレジストリサイズ属性を含めるには、コンテナレジストリメタデータデータベースを有効にする必要があります。

[
  {
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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
    },
    "root_storage_statistics": {
      "build_artifacts_size": 0,
      "container_registry_size": 0,
      "container_registry_size_is_estimated": false,
      "dependency_proxy_size": 0,
      "lfs_objects_size": 0,
      "packages_size": 0,
      "pipeline_artifacts_size": 0,
      "repository_size": 0,
      "snippets_size": 0,
      "storage_size": 0,
      "uploads_size": 0,
      "wiki_size": 0
  },
    "wiki_access_level": "private",
    "duo_features_enabled": true,
    "lock_duo_features_enabled": false,
    "duo_availability": "default_on",
    "experiment_features_enabled": false,
  }
]

GitLab PremiumまたはUltimateのユーザーには、wiki_access_level、duo_features_enabled、lock_duo_features_enabled、duo_availability、およびexperiment_features_enabled属性も表示されます。

グループは名前またはパスで検索できます。以下を参照してください。

カスタム属性でフィルタリングするには、以下を使用します:

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

グループのページネーション

デフォルトでは、APIの結果はページネーションされるため、一度に20個のグループのみが表示されます。

取得するネームスペースの数を増やすには（最大100個）、以下を引数としてAPIコールに渡します:

/groups?per_page=100

ページをスイッチするには、以下を追加します:

/groups?per_page=100&page=2

グループを検索する

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

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

グループの詳細のリストを取得する

プロジェクトのリストを取得する

このグループ内のプロジェクトのリストを取得します。認証なしでアクセスすると、公開プロジェクトのみが返されます。

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

GET /groups/:id/projects

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
archivedブール値いいえアーカイブステータスで制限します。
visibility文字列いいえ表示レベル（public、internal、private）で制限します。
order_by文字列いいえid、name、path、created_at、updated_at、similarity1、star_countまたはlast_activity_atフィールドで並べ替えられたプロジェクトを返します。デフォルトはcreated_atです。
sort文字列いいえascまたはdescの順にソートされたプロジェクトを返します。デフォルトはdescです。
search文字列いいえ検索条件に一致する、権限のあるプロジェクトのリストを返します。
simpleブール値いいえプロジェクトごとに制限されたフィールドのみを返します。認証がない場合、何も行われません。単純なフィールドのみが返されます。
ownedブール値いいえ現在のユーザーが所有するプロジェクトで制限します。
starredブール値いいえ現在のユーザーがStar付きに登録したプロジェクトで制限します。
topic文字列いいえトピックに一致するプロジェクトを返します。
with_issues_enabledブール値いいえイシュー機能が有効になっているプロジェクトで制限します。デフォルトはfalseです。
with_merge_requests_enabledブール値いいえマージリクエスト機能が有効になっているプロジェクトで制限します。デフォルトはfalseです。
with_sharedブール値いいえこのグループに共有されているプロジェクトを含めます。デフォルトはtrueです。
include_subgroupsブール値いいえこのグループのサブグループ内のプロジェクトを含めます。デフォルトはfalseです。
min_access_level整数いいえ現在のユーザーが少なくともこのロール（access_level）を持つプロジェクトに制限します
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。
with_security_reportsブール値いいえビルドのいずれかにセキュリティレポートアーティファクトが存在するプロジェクトのみを返します。これは、「セキュリティが有効になっているプロジェクト」を意味します。デフォルトはfalseです。Ultimateのみです。

Footnotes（脚注）:

  1. searchパラメータから計算された類似性スコアで結果を並べ替えます。order_by=similarityを使用すると、sortパラメータは無視されます。searchパラメータが指定されていない場合、APIはnameで並べ替えられたプロジェクトを返します。

レスポンス例:

[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "main",
    "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
  }
]

グループ内のプロジェクトと、グループに共有されているプロジェクトを区別するには、namespaceを使用できます。プロジェクトがグループに共有されている場合、そのnamespaceはリクエストの対象であるグループとは異なります。

共有プロジェクトのリストを取得する

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

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

GET /groups/:id/projects/shared

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
archivedブール値いいえアーカイブステータスで制限します。
visibility文字列いいえ表示レベル（public、internal、private）で制限します。
order_by文字列いいえid、name、path、created_at、updated_at、star_count、またはlast_activity_atフィールドで並べ替えられたプロジェクトを返します。デフォルトはcreated_atです。
sort文字列いいえascまたはdescの順にソートされたプロジェクトを返します。デフォルトはdescです。
search文字列いいえ検索条件に一致する、権限のあるプロジェクトのリストを返します。
simpleブール値いいえプロジェクトごとに制限されたフィールドのみを返します。認証がない場合、何も行われません。単純なフィールドのみが返されます。
starredブール値いいえ現在のユーザーがStar付きに登録したプロジェクトで制限します。
with_issues_enabledブール値いいえイシュー機能が有効になっているプロジェクトで制限します。デフォルトはfalseです。
with_merge_requests_enabledブール値いいえマージリクエスト機能が有効になっているプロジェクトで制限します。デフォルトはfalseです。
min_access_level整数いいえ現在のユーザーが少なくともこのロール（access_level）を持つプロジェクトに制限します
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。

レスポンス例:

[
   {
      "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":"main",
      "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/main/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,
      "emails_enabled": 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"
   }
]

すべてのSAMLユーザーのリストを取得する

  • プラン: Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

指定されたトップレベルグループのすべてのSAMLユーザーをリスト表示します。

結果をフィルタリングするには、pageおよびper_page ページネーションパラメータを使用します。

GET /groups/:id/saml_users

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいトップレベルグループのIDまたはURLエンコードされたパス。
username文字列いいえ指定されたユーザー名のユーザーを返します。
search文字列いいえ一致する名前、メール、またはユーザー名を持つユーザーを返します。部分的な値を使用すると、結果が増えます。
activeブール値いいえアクティブユーザーのみを返します。
blockedブール値いいえブロックされたユーザーのみを返します。
created_after日時いいえ指定された時刻以降に作成されたユーザーを返します。形式は、: ISO 8601（YYYY-MM-DDTHH:MM:SSZ）です。
created_before日時いいえ指定された時刻よりも前に作成されたユーザーを返します。形式は、: ISO 8601（YYYY-MM-DDTHH:MM:SSZ）です。

リクエストの例:

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

レスポンス例:

[
  {
    "id": 66,
    "username": "user22",
    "name": "Sidney Jones22",
    "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": "",
    "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": [
      {
        "provider": "group_saml",
        "extern_uid": "2435223452345",
        "saml_provider_id": 1
      }
    ],
    "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,
    "scim_identities": [
      {
        "extern_uid": "2435223452345",
        "group_id": 1,
        "active": true
      }
    ]
  },
  ...
]

プロビジョニングされたユーザーのリストを取得する

  • プラン: Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

特定のグループによってプロビジョニングされたユーザーのリストを取得します。サブグループは含まれません。

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

GET /groups/:id/provisioned_users

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいIDまたはURLエンコードされたパス。
username文字列いいえ特定のユーザー名を持つ1つのユーザーを返します。
search文字列いいえ名前、メールアドレス、ユーザー名でユーザーを検索します。
activeブール値いいえアクティブユーザーのみを返します。
blockedブール値いいえブロックされたユーザーのみを返します。
created_after日時いいえ指定された時刻以降に作成されたユーザーを返します。
created_before日時いいえ指定された時刻よりも前に作成されたユーザーを返します。

レスポンス例:

[
  {
    "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": "",
    "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
  },
  ...
]

サブグループのリストを取得する

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

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

このリストを次のいずれかのユーザーとしてリクエストする場合は、次のようになります:

  • 認証されていないユーザーの場合、公開グループのみが返されます。
  • 認証済みユーザーの場合、メンバーであるグループのみが返され、公開グループは含まれません。

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はい直属の親グループのIDまたはURLエンコードされたグループのパス。
skip_groups整数の配列いいえ渡されたグループIDをスキップします。
all_availableブール値いいえアクセスできるすべてのグループを表示します（認証済みユーザーの場合はfalseがデフォルトで、管理者の場合はtrueがデフォルトです）。属性とが優先されます。ownedおよびmin_access_level属性が優先されます。
search文字列いいえ検索条件に一致する認証済みグループのリストを返します。サブグループの（フルパスではなく）短いパスのみが検索されます。
order_by文字列いいえグループをname、path、またはidで並べ替えます。デフォルトはnameです。
sort文字列いいえグループをascまたはdescの順に並べ替えます。デフォルトはascです。
statisticsブール値いいえグループ統計を含めます（管理者のみ）。
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。
ownedブール値いいえ現在の認証済みユーザーが明示的に所有するグループに制限します。
min_access_level整数いいえ現在のユーザーが、指定されているロール（access_level）以上のロールを持っているグループに制限します。
all_availableブール値いいえtrueの場合、アクセス可能なすべてのグループを返します。falseの場合、ユーザーがメンバーであるグループのみを返します。ユーザーの場合はfalseがデフォルトであり、管理者の場合はtrueがデフォルトです。認証されていないリクエストでは、常にすべての公開グループが返されます。owned属性とmin_access_level属性が優先されます。
activeブール値いいえアーカイブされておらず、削除対象としてマークされていないグループに制限します。
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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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 PremiumまたはUltimateのユーザーには、wiki_access_level、duo_features_enabled、lock_duo_features_enabled、duo_availability、およびexperiment_features_enabled属性も表示されます。

子孫グループのリストを取得する

このグループの表示可能な子孫グループのリストを取得します。認証なしでアクセスすると、公開グループのみが返されます。

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

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はい直属の親グループのIDまたはURLエンコードされたグループのパス。
skip_groups整数の配列いいえ渡されたグループIDをスキップします。
all_availableブール値いいえtrueの場合、アクセス可能なすべてのグループを返します。falseの場合、ユーザーがメンバーであるグループのみを返します。ユーザーの場合はfalseがデフォルトであり、管理者の場合はtrueがデフォルトです。認証されていないリクエストでは、常にすべての公開グループが返されます。owned属性とmin_access_level属性が優先されます。
search文字列いいえ検索条件に一致する認証済みグループのリストを返します。子孫グループの（フルパスではなく）短いパスのみが検索されます。
order_by文字列いいえグループをname、path、またはidで並べ替えます。デフォルトはnameです。
sort文字列いいえグループをascまたはdescの順に並べ替えます。デフォルトはascです。
statisticsブール値いいえグループ統計を含めます（管理者のみ）。
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。
ownedブール値いいえ現在の認証済みユーザーが明示的に所有するグループに制限します。
min_access_level整数いいえ現在のユーザーが、指定されているロール（access_level）以上のロールを持っているグループに制限します。
activeブール値いいえアーカイブされておらず、削除対象としてマークされていないグループに制限します。
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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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 PremiumまたはUltimateのユーザーには、wiki_access_level、duo_features_enabled、lock_duo_features_enabled、duo_availability、およびexperiment_features_enabled属性も表示されます。

共有グループのリストを取得する

特定のグループが招待されているグループのリストを取得します。認証なしでアクセスすると、公開されている共有グループのみが返されます。

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

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
skip_groups整数の配列いいえ指定されたグループのIDを除外します。
search文字列いいえ検索条件に一致する認証済みグループのリストを返します。
order_by文字列いいえグループをname、path、id、またはsimilarityで並べ替えます。デフォルトはnameです。
sort文字列いいえグループをascまたはdescの順に並べ替えます。デフォルトはascです。
visibility文字列いいえpublic、internal、またはprivateのグループに制限します。
min_access_level整数いいえ現在のユーザーが、指定されているロール（access_level）以上のロールを持っているグループに制限します。
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。
GET /groups/:id/groups/shared

レスポンス例:

[
  {
    "id": 101,
    "web_url": "http://gitlab.example.com/groups/some_path",
    "name": "group1",
    "path": "some_path",
    "description": "",
    "visibility": "public",
    "share_with_group_lock": "false",
    "require_two_factor_authentication": "false",
    "two_factor_grace_period": 48,
    "project_creation_level": "maintainer",
    "auto_devops_enabled": "nil",
    "subgroup_creation_level": "maintainer",
    "emails_disabled": "false",
    "emails_enabled": "true",
    "mentions_disabled": "nil",
    "lfs_enabled": "true",
    "math_rendering_limits_enabled": "true",
    "lock_math_rendering_limits_enabled": "false",
    "default_branch": "nil",
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
        "allowed_to_push": [
          {
              "access_level": 30
          }
        ],
        "allow_force_push": "true",
        "allowed_to_merge": [
          {
              "access_level": 30
          }
        ],
        "developer_can_initial_push": "false",
        "code_owner_approval_required": "false"
    },
    "avatar_url": "http://gitlab.example.com/uploads/-/system/group/avatar/101/banana_sample.gif",
    "request_access_enabled": "true",
    "full_name": "group1",
    "full_path": "some_path",
    "created_at": "2024-06-06T09:39:30.056Z",
    "parent_id": "nil",
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": "nil",
    "ldap_access": "nil",
    "wiki_access_level": "enabled"
  }
]

招待されたグループのリストを取得する

特定のグループに招待されたグループのリストを取得します。認証なしでアクセスすると、公開されている招待グループのみが返されます。このエンドポイントは、ユーザー（認証済みユーザーの場合）またはIP（認証されていないユーザーの場合）ごとに、1分あたり60リクエストにレート制限されています。

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

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
search文字列いいえ検索条件に一致する認証済みグループのリストを返します。
min_access_level整数いいえ現在のユーザーが、指定されているロール（access_level）以上のロールを持っているグループに制限します。
relation文字列の配列いいえグループを関係（直接または継承）でフィルタリングします。
with_custom_attributesブール値いいえレスポンスにカスタム属性を含めます（管理者のみ）。
GET /groups/:id/invited_groups

レスポンス例:

[
  {
    "id": 33,
    "web_url": "http://gitlab.example.com/groups/flightjs",
    "name": "Flightjs",
    "path": "flightjs",
    "description": "Illo dolorum tempore eligendi minima ducimus provident.",
    "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": "maintainer",
    "emails_disabled": false,
    "emails_enabled": true,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "math_rendering_limits_enabled": true,
    "lock_math_rendering_limits_enabled": false,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
        {
          "access_level": 40
        }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
        {
          "access_level": 40
        }
      ],
      "developer_can_initial_push": false
    },
    "avatar_url": null,
    "request_access_enabled": true,
    "full_name": "Flightjs",
    "full_path": "flightjs",
    "created_at": "2024-07-09T10:31:08.307Z",
    "parent_id": null,
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": null,
    "ldap_access": null,
    "wiki_access_level": "enabled"
  }
]

監査イベントのリストを取得する

  • プラン: Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

グループ監査イベントには、グループ監査イベントAPIを介してアクセスできます。

グループを管理する

グループを作成する

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

新しいプロジェクトグループを作成します。これは、グループを作成できるユーザーのみが利用できます。

POST /groups

パラメータは以下のとおりです:

属性型必須説明
name文字列はいグループの名前。
path文字列はいグループのパス。
auto_devops_enabledブール値いいえこのグループ内のすべてのプロジェクトでAuto DevOpsパイプラインをデフォルトにします。
avatar混合いいえグループのアバターの画像ファイル。
default_branch文字列いいえグループのプロジェクトのデフォルトブランチ名。GitLab 16.11で導入されました。
default_branch_protection整数いいえGitLab 17.0で非推奨になりました。代わりにdefault_branch_protection_defaultsを使用してください。
default_branch_protection_defaultsハッシュいいえGitLab 17.0で導入されました。利用可能なオプションについては、default_branch_protection_defaultsのオプションを参照してください。
description文字列いいえグループの説明。
enabled_git_access_protocol文字列いいえGitアクセスで有効になっているプロトコル。使用できる値はssh、http、およびall（両方のプロトコルを許可する場合）です。GitLab 16.9で導入されました。
emails_disabledブール値いいえ（GitLab 16.5で非推奨になりました。）メール通知を無効にします。代わりにemails_enabledを使用してください。
emails_enabledブール値いいえメール通知を有効にします。
lfs_enabledブール値いいえこのグループのプロジェクトに対して、Large File Storage（LFS）を有効または無効にします。
mentions_disabledブール値いいえグループがメンションされる機能を無効にします。
organization_id整数いいえグループの組織ID。
parent_id整数いいえネストされたグループを作成するための親グループID。
project_creation_level文字列いいえデベロッパーがグループにプロジェクトを作成できるかどうかを決定します。administrator（管理者モードが有効になっているユーザー）、noone（なし）、maintainer（メンテナーロールを持つユーザー）、またはdeveloper（デベロッパーまたはメンテナーロールを持つユーザー）を指定できます。
request_access_enabledブール値いいえユーザーがメンバーアクセスをリクエストできるようにします。
require_two_factor_authenticationブール値いいえこのグループのすべてのユーザーに対して2要素認証のセットアップを必須にします。
share_with_group_lockブール値いいえこのグループ内で別のグループとプロジェクトを共有することを禁止します。
subgroup_creation_level文字列いいえサブグループの作成を許可します。owner（オーナーロールを持つユーザー）またはmaintainer（メンテナーロールを持つユーザー）を指定できます。
two_factor_grace_period整数いいえ2要素認証が強制的に適用されるまでの時間（時間単位）。
visibility文字列いいえグループの表示レベル。private、internal、またはpublicを指定できます。
membership_lockブール値いいえこのグループのプロジェクトにユーザーを追加できません。PremiumおよびUltimateのみです。
extra_shared_runners_minutes_limit整数いいえ管理者のみが設定できます。このグループの追加のコンピューティング時間です。GitLab Self-Managed、Premium、およびUltimateのみです。
shared_runners_minutes_limit整数いいえ管理者のみが設定できます。このグループの1か月あたりのコンピューティング時間の最大数。nil（デフォルト、システムのデフォルトを継承）、0（無制限）、または> 0のいずれかです。GitLab Self-Managed、Premium、およびUltimateのみです。
wiki_access_level文字列いいえWikiのアクセスレベル。disabled、private、またはenabledを指定できます。PremiumおよびUltimateのみです。
duo_availability文字列いいえGitLab Duoの可用性設定。有効な値はdefault_on、default_off、またはnever_onです。注: UIではnever_onは「常にオフ」として表示されます。
experiment_features_enabledブール値いいえこのグループに対して実験的機能を有効にします。

default_branch_protectionのオプション

default_branch_protection属性は、デベロッパーまたはメンテナーのロールを持つユーザーが該当するデフォルトブランチにプッシュできるかどうかを決定します。次のテーブルで詳しく説明します:

値説明
0保護されません。デベロッパーまたはメンテナーのロールを持つユーザーは、以下の操作を実行できます:
- 新しいコミットをプッシュする
- 変更を強制プッシュする
- ブランチを削除する
1部分的に保護されます。デベロッパーまたはメンテナーのロールを持つユーザーは、以下の操作を実行できます:
- 新しいコミットをプッシュする
2完全に保護されます。メンテナーのロールを持つユーザーのみが、以下の操作を実行できます:
- 新しいコミットをプッシュする
3プッシュから保護されています。メンテナーのロールを持つユーザーが以下の操作を実行できます:
- 新しいコミットをプッシュする
- 変更を強制プッシュする
- マージリクエストを承認する
デベロッパーのロールを持つユーザーは、以下の操作を実行できます:
- マージリクエストを承認する
4初回プッシュ後に完全に保護されます。デベロッパーのロールを持つユーザーは、以下の操作を実行できます:
- 空のリポジトリにコミットをプッシュする
メンテナーのロールを持つユーザーが以下の操作を実行できます:
- 新しいコミットをプッシュする
- マージリクエストを承認する

default_branch_protection_defaultsのオプション

default_branch_protection_defaults属性は、デフォルトブランチ保護のデフォルトを記述します。すべてのパラメータはオプションです。

キー型説明
allowed_to_push配列プッシュが許可されたアクセスレベルの配列。デベロッパー（30）またはメンテナー（40）をサポートしています。
allow_force_pushブール値プッシュアクセスを持つすべてのユーザーに対して強制プッシュを許可します。
allowed_to_merge配列マージが許可されたアクセスレベルの配列。デベロッパー（30）またはメンテナー（40）をサポートしています。
developer_can_initial_pushブール値デベロッパーに対し初回プッシュを許可します。

サブグループを作成する

これは、新しいグループの作成に似ています。グループのリスト呼び出しからの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/"

グループを削除する

前提要件:

  • グループの管理者であるか、オーナーロールを持っている必要があります。

グループを削除対象としてマークします。グループは、保持期間の終了時に削除されます:

  • GitLab.comでは、グループは30日間保持されます。
  • GitLab Self-Managedでは、保持期間はインスタンスの設定によって制御されます。

このエンドポイントは、以前に削除対象としてマークされたサブグループを即座に削除することもできます。

GitLab.comでは、グループを削除した後、そのデータは30日間保持され、即時削除はできません。GitLab.comでグループをすぐに削除する必要がある場合は、サポートチケットを開いてください。

DELETE /groups/:id

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
permanently_removeブール値/文字列いいえtrueの場合、既に削除対象としてマークされているサブグループをすぐに削除します。トップレベルグループは削除できません。GitLab.comとDedicatedでは無効になっています。
full_path文字列いいえサブグループへのパス全体。サブグループの削除の確認に使用されます。permanently_removeがtrueの場合、この属性は必須です。サブグループのパスを確認するには、グループの詳細を参照してください。

ユーザーに認証がある場合、レスポンスは202 Acceptedです。

サブスクリプションにリンクされているGitLab.comグループは削除できません。最初に、別のグループとのサブスクリプションをリンクする必要があります。

削除対象としてマークされたグループを復元する

以前に削除対象としてマークされたグループを復元します。

POST /groups/:id/restore

パラメータは以下のとおりです:

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

グループをアーカイブする

  • ステータス: 実験的機能

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。この機能はテストには利用できますが、本番環境での使用には適していません。

グループをアーカイブします。

前提要件:

  • グループの管理者であるか、オーナーロールを持っている必要があります。

グループが既にアーカイブされている場合、このエンドポイントは、処理できないエンティティエラー422を返します。

POST /groups/:id/archive

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はい認証済みユーザーが所有しているグループのIDまたはURLエンコードされたパス。

レスポンス例:

{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "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": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": true,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}

グループのアーカイブを解除する

  • ステータス: 実験的機能

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。この機能はテストには利用できますが、本番環境での使用には適していません。

グループのアーカイブを解除します。

前提要件:

  • グループの管理者であるか、オーナーロールを持っている必要があります。

グループがアーカイブされていない場合、このエンドポイントは、処理できないエンティティエラー422を返します。

POST /groups/:id/unarchive

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はい認証済みユーザーが所有しているグループのIDまたはURLエンコードされたパス。

レスポンス例:

{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "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": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": false,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}

グループを転送する

グループを新しい親グループに転送するか、サブグループをトップレベルグループに変換します。

前提要件:

POST /groups/:id/transfer

パラメータは以下のとおりです:

属性型必須説明
id整数はい転送行するグループのID。
id整数はい転送行するグループの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"

グループの転送に利用できる場所のリストを取得する

指定されたグループを転送するために利用可能なすべての親グループを一覧表示します。

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"
  }
]

プロジェクトをグループに転送する

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab Self-Managed、GitLab Dedicated

プロジェクトを別のグループネームスペースに転送します。または、代わりにプロジェクトを新しいネームスペースに転送するエンドポイントを使用します。

タグ付きパッケージがプロジェクトのリポジトリに存在する場合、転送プロセスが失敗する可能性があります。

前提要件:

  • インスタンスの管理者である。
POST /groups/:id/projects/:project_id

パラメータは以下のとおりです:

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

グループの招待

これらのエンドポイントは、グループの招待に使用されます。詳しくは、グループへのグループの招待をご覧ください。

グループ招待の作成

ターゲットグループを指定されたグループに追加するグループ招待を作成します。

POST /groups/:id/share

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいターゲットグループのIDまたはURLエンコードされたパス。
group_id整数はい招待するグループのID。
group_access整数はい招待されたグループに割り当てるデフォルトロール（access_level）。
expires_at日付（ISO 8601）いいえグループ招待の有効期限日。
member_role_id整数いいえ招待されたグループに割り当てるカスタムロールのID定義されている場合、group_accessはカスタムロールの作成に使用されるベースロールと一致する必要があります。

成功すると、200とグループの詳細が返されます。

グループ招待の削除

グループ招待を削除し、指定されたグループからターゲットグループへのアクセスを削除します。

DELETE /groups/:id/share/:group_id
属性型必須説明
id整数または文字列はいターゲットグループのIDまたはURLエンコードされたパス。
group_id整数はい招待を取り消すグループのID。

成功すると204が返されますが、コンテンツは返されません。

グループ属性を更新する

web_based_commit_signing_enabled属性の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。この機能はテストには利用できますが、本番環境での使用には適していません。

指定されたグループの属性を更新します。

前提要件:

  • グループの管理者であるか、オーナーロールを持っている必要があります。
PUT /groups/:id
属性型必須説明
id整数はいグループのID。
name文字列いいえグループの名前。
path文字列いいえグループのパス。
auto_devops_enabledブール値いいえこのグループ内のすべてのプロジェクトでAuto DevOpsパイプラインをデフォルトにします。
avatar混合いいえグループのアバターの画像ファイル。
default_branch文字列いいえグループのプロジェクトのデフォルトブランチ名。GitLab 16.11で導入されました。
default_branch_protection整数いいえGitLab 17.0で非推奨になりました。代わりにdefault_branch_protection_defaultsを使用してください。
default_branch_protection_defaultsハッシュいいえGitLab 17.0で導入されました。利用可能なオプションについては、default_branch_protection_defaultsのオプションを参照してください。
description文字列いいえグループの説明。
enabled_git_access_protocol文字列いいえGitアクセスで有効になっているプロトコル。使用できる値はssh、http、およびall（両方のプロトコルを許可する場合）です。GitLab 16.9で導入されました。
emails_disabledブール値いいえ（GitLab 16.5で非推奨になりました。）メール通知を無効にします。代わりにemails_enabledを使用してください。
emails_enabledブール値いいえメール通知を有効にします。
lfs_enabledブール値いいえこのグループのプロジェクトに対して、Large File Storage（LFS）を有効または無効にします。
mentions_disabledブール値いいえグループがメンションされる機能を無効にします。
prevent_sharing_groups_outside_hierarchyブール値いいえグループ階層外部でのグループ共有を防ぐを参照してください。この属性は、トップレベルグループでのみ使用できます。
project_creation_level文字列いいえデベロッパーがグループにプロジェクトを作成できるかどうかを決定します。noone（なし）、maintainer（メンテナーロールを持つユーザー）、またはdeveloper（デベロッパーロールまたはメンテナーロールを持つユーザー）のいずれかです。
request_access_enabledブール値いいえユーザーがメンバーアクセスをリクエストできるようにします。
require_two_factor_authenticationブール値いいえこのグループのすべてのユーザーに対して2要素認証のセットアップを必須にします。
shared_runners_setting文字列いいえshared_runners_settingのオプションを参照してください。グループのサブグループおよびプロジェクトのインスタンスRunnerを有効または無効にします。
share_with_group_lockブール値いいえこのグループ内で別のグループとプロジェクトを共有することを禁止します。
step_up_auth_required_oauth_provider文字列いいえステップアップ認証に必要なOAuthプロバイダー。無効にするには、空の文字列を渡します。GitLab 18.4で導入されました。omniauth_step_up_auth_for_namespace機能フラグが有効な場合にのみ使用できます。
subgroup_creation_level文字列いいえサブグループの作成を許可します。owner（オーナーロールを持つユーザー）またはmaintainer（メンテナーロールを持つユーザー）を指定できます。
two_factor_grace_period整数いいえ2要素認証が強制的に適用されるまでの時間（時間単位）。
visibility文字列いいえグループの表示レベル。private、internal、またはpublicを指定できます。
extra_shared_runners_minutes_limit整数いいえ管理者のみが設定できます。このグループの追加のコンピューティング時間です。GitLab Self-Managed、Premium、およびUltimateのみです。
file_template_project_id整数いいえカスタムファイルテンプレートの読み込み元のプロジェクトのID。PremiumおよびUltimateのみです。
membership_lockブール値いいえこのグループのプロジェクトにユーザーを追加できません。PremiumおよびUltimateのみです。
prevent_forking_outside_groupブール値いいえ有効にすると、ユーザーはこのグループから外部ネームスペースへプロジェクトをフォークできません。PremiumおよびUltimateのみです。
shared_runners_minutes_limit整数いいえ管理者のみが設定できます。このグループの1か月あたりのコンピューティング時間の最大数。nil（デフォルト、システムのデフォルトを継承）、0（無制限）、または> 0のいずれかです。GitLab Self-Managed、Premium、およびUltimateのみです。
unique_project_download_limit整数いいえ指定された期間内にユーザーがダウンロードできる一意のプロジェクトの最大数。この数を超えると、ユーザーはBANされます。トップレベルグループでのみ使用できます。デフォルトは、: 0、最大値は: 10,000です。Ultimateのみです。
unique_project_download_limit_interval_in_seconds整数いいえユーザーが最大量のプロジェクトをダウンロードできる期間。この期間を経過すると、ユーザーはBANされます。トップレベルグループでのみ使用できます。デフォルトは、: 0、最大値は: 864,000秒（10日間）です。Ultimateのみです。
unique_project_download_limit_allowlist文字列の配列いいえ一意のプロジェクトのダウンロード制限から除外されるユーザー名のリスト。トップレベルグループでのみ使用できます。デフォルトは[]、最大値は: 100個のユーザー名です。Ultimateのみです。
unique_project_download_limit_alertlist整数の配列いいえ一意のプロジェクトのダウンロード制限を超えた場合にメールで通知されるユーザーIDのリスト。トップレベルグループでのみ使用できます。デフォルトは[]、最大値は: 100個のユーザーIDです。Ultimateのみです。
auto_ban_user_on_excessive_projects_downloadブール値いいえ有効にすると、ユーザーがunique_project_download_limitとunique_project_download_limit_interval_in_secondsで指定されている一意のプロジェクトの最大数を超えてダウンロードすると、.ユーザーは自動的にグループからBANされます。Ultimateのみです。
ip_restriction_ranges文字列いいえグループアクセスを制限するためのIPアドレスまたはサブネットマスクのカンマ区切りリスト。PremiumおよびUltimateのみです。
allowed_email_domains_list文字列いいえグループアクセスを許可するメールアドレスドメインのカンマ区切りリスト。GitLab 17.4で導入されました。GitLab PremiumおよびUltimateのみです。
wiki_access_level文字列いいえWikiのアクセスレベル。disabled、private、またはenabledを指定できます。PremiumおよびUltimateのみです。
duo_availability文字列いいえGitLab Duoの可用性設定。有効な値はdefault_on、default_off、またはnever_onです。注: UIではnever_onは「常にオフ」として表示されます。
experiment_features_enabledブール値いいえこのグループに対して実験的機能を有効にします。
math_rendering_limits_enabledブール値いいえ数式レンダリングの制限がこのグループに使用されるかどうかを示します。
lock_math_rendering_limits_enabledブール値いいえ数式レンダリングの制限がすべての子孫グループに対してロックされているかどうかを示します。
duo_features_enabledブール値いいえこのグループでGitLab Duo機能が有効になっているかどうかを示します。GitLab 16.10で導入されました。GitLab Self-Managed、Premium、およびUltimateのみです。
lock_duo_features_enabledブール値いいえGitLab Duo機能で有効になっている設定がすべてのサブグループに適用されるかどうかを示します。GitLab 16.10で導入されました。GitLab Self-Managed、Premium、およびUltimateのみです。
max_artifacts_size整数いいえ個々のジョブアーティファクトの最大ファイルサイズ（MB単位）。
web_based_commit_signing_enabledブール値いいえGitLab UIから作成されたコミットのWebベースのコミット署名を有効にします。GitLab.comのトップレベルグループでのみ利用可能です。グループに対して有効になっている場合、グループ内のすべてのプロジェクトに適用されます。

レスポンス内のprojects属性とshared_projects属性は非推奨であり、v5で削除される予定です。グループ内のすべてのプロジェクトの詳細を取得するには、グループのプロジェクトをリストまたはグループの共有プロジェクトをリストを使用します。

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5?name=Experimental"

このエンドポイントは、最大100個のプロジェクトと共有プロジェクトを返します。グループ内のすべてのプロジェクトの詳細を取得するには、代わりにグループのプロジェクトをリストエンドポイントを使用します。

レスポンス例:

{
  "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,
  "enabled_git_access_protocol": "all",
  "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": "main",
      "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,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false
}

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

GitLab PremiumまたはUltimateのユーザーには、wiki_access_level、duo_features_enabled、lock_duo_features_enabled、duo_availability、およびexperiment_features_enabled属性も表示されます。

shared_runners_settingのオプション

shared_runners_setting属性は、グループのサブグループとプロジェクトに対してインスタンスRunnerを有効にするかどうかを決定します。

値説明
enabledこのグループ内のすべてのプロジェクトとサブグループに対して、インスタンスRunnerを有効にします。
disabled_and_overridableこのグループ内のすべてのプロジェクトとサブグループに対してインスタンスRunnerを無効にしますが、サブグループでこの設定を上書きできるようにします。
disabled_and_unoverridableこのグループ内のすべてのプロジェクトとサブグループに対してインスタンスRunnerを無効にし、サブグループでこの設定を上書きできないようにします。
disabled_with_override（非推奨。disabled_and_overridableを使用してください。）このグループ内のすべてのプロジェクトとサブグループに対してインスタンスRunnerを無効にしますが、サブグループでこの設定を上書きできるようにします。

グループアバターを更新する

グループアバターを更新します。

グループアバターをダウンロードする

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

GET /groups/:id/avatar
属性型必須説明
id整数または文字列はいグループのID。

例:

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

グループアバターをアップロードする

ファイルシステムからアバターファイルをアップロードするには、--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"

グループアバターを削除する

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

リクエストの例:

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

トークンを失効させる

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。

トークンにグループ、またはそのサブグループとプロジェクトのいずれかへのアクセス権がある場合は、トークンを失効させます。トークンが失効した場合、またはすでに失効している場合は、その詳細がレスポンスで返されます。

次の条件を満たしている必要があります:

  • このグループはトップレベルグループである必要があります。
  • グループのオーナーロールを持っている必要があります。
  • トークンタイプが次のいずれかである必要があります:
    • パーソナルアクセストークン
    • グループアクセストークン
    • プロジェクトアクセストークン
    • グループデプロイトークン
    • ユーザーフィードトークン

追加のトークンタイプが後日サポートされる可能性があります。

POST /groups/:id/tokens/revoke
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
token文字列はいプレーンテキストのトークン。

成功した場合は、200 OKとトークンのJSON表現を返します。返される属性は、トークンタイプによって異なります。

リクエストの例

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"token":"glpat-EXAMPLE"}' \
  --url "https://gitlab.example.com/api/v4/groups/63/tokens/revoke"

レスポンス例:

{
    "id": 9,
    "name": "my-subgroup-deploytoken",
    "username": "gitlab+deploy-token-9",
    "expires_at": null,
    "scopes":
    [
        "read_repository",
        "read_package_registry",
        "write_package_registry"
    ],
    "revoked": true,
    "expired": false
}

グループをLDAPと同期する

  • プラン: Premium、Ultimate
  • 提供形態: GitLab Self-Managed

指定されたグループを、リンクされたLDAPグループと同期させます。

前提要件:

  • グループの管理者であるか、オーナーロールを持っている必要があります。
POST /groups/:id/ldap_sync
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。

認証情報インベントリ

  • プラン: Premium、Ultimate
  • 提供形態: GitLab.com

GitLab.comでエンタープライズユーザーの認証情報を表示、失効、およびローテーションします。

前提要件:

  • グループのオーナーロールを持っている必要があります。

グループのすべてのパーソナルアクセストークンをリスト表示します

トップレベルグループのエンタープライズユーザーに関連付けられているすべてのパーソナルアクセストークンをリストします。

GET /groups/:id/manage/personal_access_tokens
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
created_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に作成されたトークンを返します。
created_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に作成されたトークンを返します。
last_used_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に最終使用されたトークンを返します。
last_used_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に最終使用されたトークンを返します。
revokedブール値いいえtrueの場合、失効したトークンのみを返します。
search文字列いいえ定義されている場合、指定された値が名前に含まれたトークンを返します。
state文字列いいえ定義されている場合、指定された状態のトークンを返します。使用できる値は、activeとinactiveです。
sort文字列いいえ定義されている場合、指定された値で結果を並べ替えます。使用できる値は、created_asc、created_desc、expires_asc、expires_desc、last_used_asc、last_used_desc、name_asc、name_descです。

リクエストの例:

curl --header "PRIVATE-TOKEN: <group_owner_token>" "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens"

レスポンス例:

[
  {
    "id": 1,
    "name": "Test Token",
    "revoked": false,
    "created_at": "2020-07-23T14:31:47.729Z",
    "description": "Test Token description",
    "scopes": [
        "api"
    ],
    "user_id": 3,
    "last_used_at": "2021-10-06T17:58:37.550Z",
    "active": true,
    "expires_at": "2025-11-08"
  }
]

グループのすべてのグループおよびプロジェクトアクセストークンをリスト表示します

トップレベルグループに関連付けられているすべてのグループおよびプロジェクトアクセストークンをリストします。

GET /groups/:id/manage/resource_access_tokens
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
created_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に作成されたトークンを返します。
created_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に作成されたトークンを返します。
last_used_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に最終使用されたトークンを返します。
last_used_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に最終使用されたトークンを返します。
revokedブール値いいえtrueの場合、失効したトークンのみを返します。
search文字列いいえ定義されている場合、指定された値が名前に含まれたトークンを返します。
state文字列いいえ定義されている場合、指定された状態のトークンを返します。使用できる値は、activeとinactiveです。
sort文字列いいえ定義されている場合、指定された値で結果を並べ替えます。使用できる値は、created_asc、created_desc、expires_asc、expires_desc、last_used_asc、last_used_desc、name_asc、name_descです。

リクエストの例:

curl --header "PRIVATE-TOKEN: <group_owner_token>" "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens"

レスポンス例:

[
  {
    "id": 12767703,
    "name": "Test Group Token",
    "revoked": false,
    "created_at": "2025-01-07T00:25:02.128Z",
    "description": "",
    "scopes": [
        "read_registry"
    ],
    "user_id": 25365147,
    "last_used_at": null,
    "active": true,
    "expires_at": "2025-06-19",
    "access_level": 10,
    "resource_type": "group",
    "resource_id": 77449520
  }
]

グループのすべてのSSHキーをリスト表示します

トップレベルグループのエンタープライズユーザーに関連付けられているすべてのSSH公開キーをリストします。

GET /groups/:id/manage/ssh_keys
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス。
created_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に作成されたSSHキーを返します。
created_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に作成されたSSHキーを返します。
expires_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に有効期限が切れるSSHキーを返します。
expires_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に有効期限が切れるSSHキーを返します。
curl --header "PRIVATE-TOKEN: <group_owner_token>" "https://gitlab.example.com/api/v4/groups/1/manage/ssh_keys"

レスポンス例:

[
  {
    "id":3,
    "title":"Sample key 3",
    "created_at":"2024-12-23T05:40:11.891Z",
    "expires_at":null,
    "last_used_at":"2024-12-23T05:40:11.891Z",
    "usage_type":"auth_and_signing",
    "user_id":3
  }
]

エンタープライズユーザーのパーソナルアクセストークンを失効します

指定されたエンタープライズユーザーのパーソナルアクセストークンを失効します。

DELETE groups/:id/manage/personal_access_tokens/:id
属性型必須説明
id整数または文字列はいパーソナルアクセストークン、またはキーワードselfのID。
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens/<personal_access_token_id>"

成功した場合、204: No Contentを返します。

その他の発生しうる応答:

  • 正常に失効しなかった場合は400: Bad Request。
  • アクセストークンが無効な場合は401: Unauthorized。
  • アクセストークンに必要な権限がない場合は403: Forbidden。

エンタープライズユーザーのグループまたはプロジェクトアクセストークンを失効します

トップレベルグループに関連付けられているエンタープライズユーザーの指定されたグループまたはプロジェクトアクセストークンを失効します。

DELETE groups/:id/manage/resource_access_tokens/:id
属性型必須説明
id整数または文字列はいリソースアクセストークンのIDまたはキーワードself。
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens/<personal_access_token_id>"

成功した場合、204: No Contentを返します。

その他の発生しうる応答:

  • 正常に失効しなかった場合は400: Bad Request。
  • アクセストークンが無効な場合は401: Unauthorized。
  • アクセストークンに必要な権限がない場合は403: Forbidden。

エンタープライズユーザーのSSHキーを削除します

トップレベルグループに関連付けられているエンタープライズユーザーの指定されたSSH公開キーを削除します。

DELETE /groups/:id/manage/keys/:key_id

サポートされている属性は以下のとおりです:

属性型必須説明
key_id整数はい既存のキーのID。

成功した場合、204: No Contentを返します。

その他の発生しうる応答:

  • SSHキーが正常に削除されなかった場合は400: Bad Request。
  • SSHキーが無効な場合は401: Unauthorized。
  • ユーザーに必要な権限がない場合は403: Forbidden。

エンタープライズユーザーのパーソナルアクセストークンをローテーションします

トップレベルグループに関連付けられているエンタープライズユーザーの指定されたパーソナルアクセストークンをローテーションします。これにより、以前のトークンは失効し、1週間後に有効期限が切れる新しいトークンが作成されます。

POST groups/:id/manage/personal_access_tokens/:id/rotate
属性型必須説明
id整数または文字列はいパーソナルアクセストークン、またはキーワードselfのID。
expires_at日付いいえISO形式（YYYY-MM-DD）のアクセストークンの有効期限。日付はローテーション日から1年以内である必要があります。未定義の場合、トークンは1週間後に期限切れになります。
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/personal_access_tokens/<personal_access_token_id>/rotate"

レスポンス例:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}

成功した場合、200: OKを返します。

その他の発生しうる応答:

  • ローテーションが正常に完了しなかった場合は400: Bad Request。
  • 次のいずれかの条件に該当する場合は401: Unauthorized:
    • トークンが存在しない。
    • トークンの有効期限が切れた。
    • トークンが失効した。
    • 指定されたトークンへのアクセス権がない。
  • トークンがローテーションを許可されていない場合は403: Forbidden。
  • ユーザーにオーナーロールがあるが、トークンが存在しない場合は404: Not Found。
  • トークンがパーソナルアクセストークンでない場合は405: Method Not Allowed。

エンタープライズユーザーのグループまたはプロジェクトアクセストークンをローテーションします

トップレベルグループに関連付けられているエンタープライズユーザーの指定されたグループまたはプロジェクトアクセストークンをローテーションします。これにより、以前のトークンは失効し、1週間後に有効期限が切れる新しいトークンが作成されます。

POST groups/:id/manage/resource_access_tokens/:id/rotate
属性型必須説明
id整数または文字列はいパーソナルアクセストークン、またはキーワードselfのID。
expires_at日付いいえISO形式（YYYY-MM-DD）のアクセストークンの有効期限。日付はローテーション日から1年以内である必要があります。未定義の場合、トークンは1週間後に期限切れになります。
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/resource_access_tokens/<resource_access_token_id>/rotate"

レスポンス例:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}

成功した場合、200: OKを返します。

その他の発生しうる応答:

  • ローテーションが正常に完了しなかった場合は400: Bad Request。
  • 次のいずれかの条件に該当する場合は401: Unauthorized:
    • トークンが存在しない。
    • トークンの有効期限が切れた。
    • トークンが失効した。
    • 指定されたトークンへのアクセス権がない。
  • トークン自体をローテーションすることが許可されていない場合、またはトークンがボットユーザートークンでない場合は403: Forbidden。
  • ユーザーにオーナーロールがあるが、トークンが存在しない場合は404: Not Found。