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

グループAPI

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

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

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

グループを取得する

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

GET /groups/:id

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

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

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

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

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

レスポンス例:

json
{
  "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,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": 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": "[email protected]: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": "[email protected]: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": "[email protected]: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

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

json
{
  "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,
  "ai_settings": {
    "duo_agent_platform_enabled": true,
    "duo_workflow_mcp_enabled": false,
    "foundational_agents_default_enabled": true,
    "ai_catalog_restricted_to_group_hierarchy": false,
    "ai_usage_data_collection_enabled": false,
    "prompt_injection_protection_level": "no_checks",
    "include_recommended_allowed": false,
    "allow_all_unix_sockets": false,
    "allow_project_extension": true,
    "minimum_access_level_execute": "developer",
    "minimum_access_level_execute_async": "developer",
    "minimum_access_level_manage": "maintainer",
    "minimum_access_level_enable_on_projects": "maintainer"
  },
  ...
}

ai_settingsオブジェクトには、グループのAI関連の設定が含まれています。詳細については、ai_settingsの応答属性を参照してください。

ai_settingsの応答属性

ai_settingsオブジェクトは、グループでGitLab Duo Agent Platformが利用可能な場合に、グループを読み取れるユーザーへの応答に含まれます。オブジェクトには次の属性が含まれています:

属性タイプ説明
ai_catalog_restricted_to_group_hierarchyブール値trueの場合、AIカタログはこのトップレベルグループ階層内の項目に制限されます。PremiumおよびUltimateのみです。
ai_usage_data_collection_enabledブール値trueの場合、このグループでAI使用状況データ収集が有効になります。GitLab.comのみ。
allow_all_unix_socketsブール値trueの場合、すべてのUnixソケットはGitLab Duo Agent Platformで許可されます。
allow_project_extensionブール値trueの場合、プロジェクトはGitLab Duo Agent Platformのネットワークアクセスドメイン許可リストを拡張できます。
duo_agent_platform_enabledブール値trueの場合、このグループでGitLab Duo Agent Platformの機能が有効になります。Premium、Ultimate。GitLab.comのFreeプランでGitLabクレジットでも利用できます。
duo_workflow_mcp_enabledブール値trueの場合、GitLab Duo Agent PlatformのMCPサポートが有効になります。Premium、Ultimate。GitLab.comのFreeプランでGitLabクレジットでも利用できます。
foundational_agents_default_enabledブール値trueの場合、新しい基本エージェントがこのグループでデフォルトで有効になります。Premium、Ultimate。GitLab.comのFreeプランでGitLabクレジットでも利用できます。
include_recommended_allowedブール値trueの場合、GitLab Duo Agent Platformのネットワークアクセス許可リストに推奨ドメインが含まれます。
minimum_access_level_enable_on_projects文字列プロジェクトでGitLab Duo Agent Platformを有効にするために必要な最小アクセスレベル。developer、maintainer、ownerのいずれかです。dap_group_customizable_permissions機能フラグが有効な場合に返されます。
minimum_access_level_execute文字列ユーザーがGitLab Duo Agent Platform機能と対話するために必要な最小アクセスレベル。guest、planner、reporter、developer、maintainer、ownerのいずれか。dap_group_customizable_permissions機能フラグが有効な場合に返されます。
minimum_access_level_execute_async文字列CI/CDでGitLab Duo Agent Platformの機能を実行するために必要な最小アクセスレベル。developer、maintainer、ownerのいずれかです。dap_group_customizable_permissions機能フラグが有効な場合に返されます。
minimum_access_level_manage文字列GitLab Duo Agent Platformを管理するために必要な最小アクセスレベル。developer、maintainer、ownerのいずれかです。dap_group_customizable_permissions機能フラグが有効な場合に返されます。
prompt_injection_protection_level文字列プロンプトインジェクション保護レベル。no_checks、log_only、interruptのいずれかです。

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

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

レスポンス例:

json
{
  "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整数いいえ現在のユーザーが指定されたアクセスレベル以上を持つグループに限定します。使用可能な値: 5 （最小アクセス）、10 （ゲスト）、15 （プランナー）、20 （レポーター）、25 （セキュリティマネージャー）、30 （デベロッパー）、40 （メンテナー）、または50 （オーナー）。
top_level_onlyブール値いいえトップレベルグループに制限します（すべてのサブグループを除外）。
repository_storage文字列いいえグループが使用しているリポジトリストレージでフィルタリングします（管理者のみ）。PremiumおよびUltimateのみです。
marked_for_deletion_on日付いいえグループが削除対象としてマークされた日付でフィルタリングします。GitLab 17.1で導入されました。PremiumおよびUltimateのみです。
activeブール値いいえアーカイブされておらず、削除対象としてマークされていないグループに制限します。
archivedブール値いいえアーカイブされたグループで制限します。GitLab 18.2で導入されました。
GET /groups
json
[
  {
    "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インスタンスの場合、コンテナレジストリサイズ属性を含めるには、コンテナレジストリメタデータデータベースを有効にする必要があります。

json
[
  {
    "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,