Member roles API

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed
History

Use this API to interact with member roles for your GitLab.com groups or entire GitLab Self-Managed instance.

Manage instance member roles

  • Tier: Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

Prerequisites:

Get all instance member roles

Get all member roles in an instance.

GET /member_roles

Example request:

curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/member_roles"

Example response:

[
  {
    "id": 2,
    "name": "Instance custom role",
    "description": "Custom guest that can read code",
    "group_id": null,
    "base_access_level": 10,
    "admin_cicd_variables": false,
    "admin_compliance_framework": false,
    "admin_group_member": false,
    "admin_merge_request": false,
    "admin_push_rules": false,
    "admin_terraform_state": false,
    "admin_vulnerability": false,
    "admin_web_hook": false,
    "archive_project": false,
    "manage_deploy_tokens": false,
    "manage_group_access_tokens": false,
    "manage_merge_request_settings": false,
    "manage_project_access_tokens": false,
    "manage_security_policy_link": false,
    "read_code": true,
    "read_runners": false,
    "read_dependency": false,
    "read_vulnerability": false,
    "remove_group": false,
    "remove_project": false
  }
]

Create a instance member role

Create an instance-wide member role.

POST /member_roles

Supported attributes:

AttributeTypeRequiredDescription
namestringyesThe name of the member role.
descriptionstringnoThe description of the member role.
base_access_levelintegeryesBase access level for configured role. Valid values are 10 (Guest), 15 (Planner), 20 (Reporter), 30 (Developer), 40 (Maintainer), or 50 (Owner).
admin_cicd_variablesbooleannoPermission to create, read, update, and delete CI/CD variables.
admin_compliance_frameworkbooleannoPermission to administer compliance frameworks.
admin_group_memberbooleannoPermission to add, remove and assign members in a group.
admin_merge_requestbooleannoPermission to approve merge requests.
admin_push_rulesbooleannoPermission to configure push rules for repositories at group or project level.
admin_terraform_statebooleannoPermission to administer project terraform state.
admin_vulnerabilitybooleannoPermission to edit the vulnerability object, including the status and linking an issue.
admin_web_hookbooleannoPermission to administer web hooks.
archive_projectbooleannoPermission to archive projects.
manage_deploy_tokensbooleannoPermission to manage deploy tokens.
manage_group_access_tokensbooleannoPermission to manage group access tokens.
manage_merge_request_settingsbooleannoPermission to configure merge request settings.
manage_project_access_tokensbooleannoPermission to manage project access tokens.
manage_security_policy_linkbooleannoPermission to link security policy projects.
read_codebooleannoPermission to read project code.
read_runnersbooleannoPermission to view project runners.
read_dependencybooleannoPermission to read project dependencies.
read_vulnerabilitybooleannoPermission to read project vulnerabilities.
remove_groupbooleannoPermission to delete or restore a group.
remove_projectbooleannoPermission to delete a project.

For more information on available permissions, see custom permissions.

Example request:

 curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"name" : "Custom guest (instance)", "base_access_level" : 10, "read_code" : true}' "https://gitlab.example.com/api/v4/member_roles"

Example response:

{
  "id": 3,
  "name": "Custom guest (instance)",
  "group_id": null,
  "description": null,
  "base_access_level": 10,
  "admin_cicd_variables": false,
  "admin_compliance_framework": false,
  "admin_group_member": false,
  "admin_merge_request": false,
  "admin_push_rules": false,
  "admin_terraform_state": false,
  "admin_vulnerability": false,
  "admin_web_hook": false,
  "archive_project": false,
  "manage_deploy_tokens": false,
  "manage_group_access_tokens": false,
  "manage_merge_request_settings": false,
  "manage_project_access_tokens": false,
  "manage_security_policy_link": false,
  "read_code": true,
  "read_runners": false,
  "read_dependency": false,
  "read_vulnerability": false,
  "remove_group": false,
  "remove_project": false
}

Delete an instance member role

Delete a member role from the instance.

DELETE /member_roles/:member_role_id

Supported attributes:

AttributeTypeRequiredDescription
member_role_idintegeryesThe ID of the member role.

If successful, returns 204 and an empty response.

Example request:

curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/member_roles/1"

Manage group member roles

  • Tier: Ultimate
  • Offering: GitLab.com

Prerequisites:

  • You must have the Owner role for the group.

Get all group member roles

GET /groups/:id/member_roles

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group of the group

Example request:

curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/84/member_roles"

Example response:

[
  {
    "id": 2,
    "name": "Guest + read code",
    "description": "Custom guest that can read code",
    "group_id": 84,
    "base_access_level": 10,
    "admin_cicd_variables": false,
    "admin_compliance_framework": false,
    "admin_group_member": false,
    "admin_merge_request": false,
    "admin_push_rules": false,
    "admin_terraform_state": false,
    "admin_vulnerability": false,
    "admin_web_hook": false,
    "archive_project": false,
    "manage_deploy_tokens": false,
    "manage_group_access_tokens": false,
    "manage_merge_request_settings": false,
    "manage_project_access_tokens": false,
    "manage_security_policy_link": false,
    "read_code": true,
    "read_runners": false,
    "read_dependency": false,
    "read_vulnerability": false,
    "remove_group": false,
    "remove_project": false
  },
  {
    "id": 3,
    "name": "Guest + security",
    "description": "Custom guest that read and admin security entities",
    "group_id": 84,
    "base_access_level": 10,
    "admin_cicd_variables": false,
    "admin_compliance_framework": false,
    "admin_group_member": false,
    "admin_merge_request": false,
    "admin_push_rules": false,
    "admin_terraform_state": false,
    "admin_vulnerability": true,
    "admin_web_hook": false,
    "archive_project": false,
    "manage_deploy_tokens": false,
    "manage_group_access_tokens": false,
    "manage_merge_request_settings": false,
    "manage_project_access_tokens": false,
    "manage_security_policy_link": false,
    "read_code": true,
    "read_runners": false,
    "read_dependency": true,
    "read_vulnerability": true,
    "remove_group": false,
    "remove_project": false
  }
]

Add a member role to a group

History

Adds a member role to a group. You can only add member roles at the root level of the group.

POST /groups/:id/member_roles

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group of the group.
admin_cicd_variablesbooleannoPermission to create, read, update, and delete CI/CD variables.
admin_compliance_frameworkbooleannoPermission to administer compliance frameworks.
admin_group_memberbooleannoPermission to add, remove and assign members in a group.
admin_merge_requestbooleannoPermission to approve merge requests.
admin_push_rulesbooleannoPermission to configure push rules for repositories at group or project level.
admin_terraform_statebooleannoPermission to admin project terraform state.
admin_vulnerabilitybooleannoPermission to admin project vulnerabilities.
admin_web_hookbooleannoPermission to administer web hooks.
archive_projectbooleannoPermission to archive projects.
manage_deploy_tokensbooleannoPermission to manage deploy tokens.
manage_group_access_tokensbooleannoPermission to manage group access tokens.
manage_merge_request_settingsbooleannoPermission to configure merge request settings.
manage_project_access_tokensbooleannoPermission to manage project access tokens.
manage_security_policy_linkbooleannoPermission to link security policy projects.
read_codebooleannoPermission to read project code.
read_runnersbooleannoPermission to view project runners.
read_dependencybooleannoPermission to read project dependencies.
read_vulnerabilitybooleannoPermission to read project vulnerabilities.
remove_groupbooleannoPermission to delete or restore a group.
remove_projectbooleannoPermission to delete a project.

Example request:

 curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"name" : "Custom guest", "base_access_level" : 10, "read_code" : true}' "https://gitlab.example.com/api/v4/groups/84/member_roles"

Example response:

{
  "id": 3,
  "name": "Custom guest",
  "description": null,
  "group_id": 84,
  "base_access_level": 10,
  "admin_cicd_variables": false,
  "admin_compliance_framework": false,
  "admin_group_member": false,
  "admin_merge_request": false,
  "admin_push_rules": false,
  "admin_terraform_state": false,
  "admin_vulnerability": false,
  "admin_web_hook": false,
  "archive_project": false,
  "manage_deploy_tokens": false,
  "manage_group_access_tokens": false,
  "manage_merge_request_settings": false,
  "manage_project_access_tokens": false,
  "manage_security_policy_link": false,
  "read_code": true,
  "read_runners": false,
  "read_dependency": false,
  "read_vulnerability": false,
  "remove_group": false,
  "remove_project": false
}

In GitLab 16.3 and later, you can use the API to:

  • Add a name (required) and description (optional) when you create a new custom role.
  • Update an existing custom role’s name and description.

Remove member role of a group

Deletes a member role of a group.

DELETE /groups/:id/member_roles/:member_role_id
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group of the group.
member_role_idintegeryesThe ID of the member role.

If successful, returns 204 and an empty response.

Example request:

curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/84/member_roles/1"