Member roles API
- Tier: Ultimate
- Offering: GitLab.com, GitLab Self-Managed
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:
- Authenticate yourself as an administrator.
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:
Attribute | Type | Required | Description |
---|---|---|---|
name | string | yes | The name of the member role. |
description | string | no | The description of the member role. |
base_access_level | integer | yes | Base access level for configured role. Valid values are 10 (Guest), 15 (Planner), 20 (Reporter), 30 (Developer), 40 (Maintainer), or 50 (Owner). |
admin_cicd_variables | boolean | no | Permission to create, read, update, and delete CI/CD variables. |
admin_compliance_framework | boolean | no | Permission to administer compliance frameworks. |
admin_group_member | boolean | no | Permission to add, remove and assign members in a group. |
admin_merge_request | boolean | no | Permission to approve merge requests. |
admin_push_rules | boolean | no | Permission to configure push rules for repositories at group or project level. |
admin_terraform_state | boolean | no | Permission to administer project terraform state. |
admin_vulnerability | boolean | no | Permission to edit the vulnerability object, including the status and linking an issue. |
admin_web_hook | boolean | no | Permission to administer web hooks. |
archive_project | boolean | no | Permission to archive projects. |
manage_deploy_tokens | boolean | no | Permission to manage deploy tokens. |
manage_group_access_tokens | boolean | no | Permission to manage group access tokens. |
manage_merge_request_settings | boolean | no | Permission to configure merge request settings. |
manage_project_access_tokens | boolean | no | Permission to manage project access tokens. |
manage_security_policy_link | boolean | no | Permission to link security policy projects. |
read_code | boolean | no | Permission to read project code. |
read_runners | boolean | no | Permission to view project runners. |
read_dependency | boolean | no | Permission to read project dependencies. |
read_vulnerability | boolean | no | Permission to read project vulnerabilities. |
remove_group | boolean | no | Permission to delete or restore a group. |
remove_project | boolean | no | Permission 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:
Attribute | Type | Required | Description |
---|---|---|---|
member_role_id | integer | yes | The 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:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer/string | yes | The 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
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:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the group of the group. |
admin_cicd_variables | boolean | no | Permission to create, read, update, and delete CI/CD variables. |
admin_compliance_framework | boolean | no | Permission to administer compliance frameworks. |
admin_group_member | boolean | no | Permission to add, remove and assign members in a group. |
admin_merge_request | boolean | no | Permission to approve merge requests. |
admin_push_rules | boolean | no | Permission to configure push rules for repositories at group or project level. |
admin_terraform_state | boolean | no | Permission to admin project terraform state. |
admin_vulnerability | boolean | no | Permission to admin project vulnerabilities. |
admin_web_hook | boolean | no | Permission to administer web hooks. |
archive_project | boolean | no | Permission to archive projects. |
manage_deploy_tokens | boolean | no | Permission to manage deploy tokens. |
manage_group_access_tokens | boolean | no | Permission to manage group access tokens. |
manage_merge_request_settings | boolean | no | Permission to configure merge request settings. |
manage_project_access_tokens | boolean | no | Permission to manage project access tokens. |
manage_security_policy_link | boolean | no | Permission to link security policy projects. |
read_code | boolean | no | Permission to read project code. |
read_runners | boolean | no | Permission to view project runners. |
read_dependency | boolean | no | Permission to read project dependencies. |
read_vulnerability | boolean | no | Permission to read project vulnerabilities. |
remove_group | boolean | no | Permission to delete or restore a group. |
remove_project | boolean | no | Permission 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
Attribute | Type | Required | Description |
---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the group of the group. |
member_role_id | integer | yes | The 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"
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support