Custom member roles
A custom member role adds chosen permissions to one of GitLab’s base access levels. These actions list, create and delete custom roles, at the instance (an administrator’s) or in a top-level group.
Sample questions
Section titled “Sample questions”- “List the custom roles of group acme”
- “Create a Developer-based role that can also manage vulnerabilities”
- “Delete the unused custom role 9”
How to call it
Section titled “How to call it”- Dynamic, the default surface: call
gitlab_execute_actionwithactionset to the action’s ID, such asmember_role.create_group, and its parameters inparams.gitlab_find_actionfinds an ID from a description of the task. - Meta (
GITLAB_MCP_TOOL_SURFACE=meta): callgitlab_member_rolewithactionset to the action’s name, such ascreate_group, and its parameters inparams. - Individual (
GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such asgitlab_create_group_member_role, with its parameters as the arguments.
Availability
Section titled “Availability”How many of these actions an instance serves at each tier, out of a total of 6:
- Free: 0
- Premium: 0
- Ultimate: 6
Read-only actions: 2 of 6, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 2 of the 6.
Actions
Section titled “Actions”The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. The token lines say what GitLab 19.4.1 requires of a token for the requests each action sends; on an instance with Admin Mode turned on, an action only an administrator may run also needs admin_mode. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).
| Action | Individual |
|---|---|
member_role.create_group | gitlab_create_group_member_role |
member_role.create_instance | gitlab_create_instance_member_role |
member_role.delete_group | gitlab_delete_group_member_role |
member_role.delete_instance | gitlab_delete_instance_member_role |
member_role.list_group | gitlab_list_group_member_roles |
member_role.list_instance | gitlab_list_instance_member_roles |
member_role.create_group
Section titled “member_role.create_group”Create a group-level custom member role. Returns: the created role with id, name, base_access_level, and its enabled permission flags. See also:
member_role.list_group,member_role.delete_group,member_role.create_instance.
- Meta-tool:
gitlab_member_role, actioncreate_group - Individual tool:
gitlab_create_group_member_role - Tier: Ultimate
- Classic or OAuth token:
api - Fine-grained token: Member Role: Create at group (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
base_access_level | integer | yes | Base access level (10=Guest, 15=Planner, 20=Reporter, 25=Security Manager, 30=Developer, 40=Maintainer, 50=Owner). 0, 5 and 60 are not valid |
group_id | string/integer | yes | Group ID or URL-encoded path |
admin_cicd_variables | boolean | no | Allow admin CI/CD variables |
admin_compliance_framework | boolean | no | Allow admin compliance framework |
admin_group_member | boolean | no | Allow admin group members |
admin_merge_request | boolean | no | Allow admin merge requests |
admin_push_rules | boolean | no | Allow admin push rules |
admin_terraform_state | boolean | no | Allow admin Terraform state |
admin_vulnerability | boolean | no | Allow admin vulnerability |
admin_web_hook | boolean | no | Allow admin webhooks |
archive_project | boolean | no | Allow archive project |
description | string | no | Description of the custom role |
manage_deploy_tokens | boolean | no | Allow manage deploy tokens |
manage_group_access_tokens | boolean | no | Allow manage group access tokens |
manage_merge_request_settings | boolean | no | Allow manage MR settings |
manage_project_access_tokens | boolean | no | Allow manage project access tokens |
manage_security_policy_link | boolean | no | Allow manage security policy link |
name | string | no | Name of the custom role. GitLab names a role created without one |
read_code | boolean | no | Allow read code |
read_dependency | boolean | no | Allow read dependency |
read_runners | boolean | no | Allow read runners |
read_vulnerability | boolean | no | Allow read vulnerability |
remove_group | boolean | no | Allow remove group |
remove_project | boolean | no | Allow remove project |
member_role.create_instance
Section titled “member_role.create_instance”Create an instance-level custom member role. Returns: the created role with id, name, base_access_level, and its enabled permission flags. See also:
member_role.list_instance,member_role.delete_instance,member_role.create_group.
- Meta-tool:
gitlab_member_role, actioncreate_instance - Individual tool:
gitlab_create_instance_member_role - Tier: Ultimate
- Classic or OAuth token:
api - Fine-grained token: Member Role: Create at instance (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
base_access_level | integer | yes | Base access level (10=Guest, 15=Planner, 20=Reporter, 25=Security Manager, 30=Developer, 40=Maintainer, 50=Owner). 0, 5 and 60 are not valid |
admin_cicd_variables | boolean | no | Allow admin CI/CD variables |
admin_compliance_framework | boolean | no | Allow admin compliance framework |
admin_group_member | boolean | no | Allow admin group members |
admin_merge_request | boolean | no | Allow admin merge requests |
admin_push_rules | boolean | no | Allow admin push rules |
admin_terraform_state | boolean | no | Allow admin Terraform state |
admin_vulnerability | boolean | no | Allow admin vulnerability |
admin_web_hook | boolean | no | Allow admin webhooks |
archive_project | boolean | no | Allow archive project |
description | string | no | Description of the custom role |
manage_deploy_tokens | boolean | no | Allow manage deploy tokens |
manage_group_access_tokens | boolean | no | Allow manage group access tokens |
manage_merge_request_settings | boolean | no | Allow manage MR settings |
manage_project_access_tokens | boolean | no | Allow manage project access tokens |
manage_security_policy_link | boolean | no | Allow manage security policy link |
name | string | no | Name of the custom role. GitLab names a role created without one |
read_code | boolean | no | Allow read code |
read_dependency | boolean | no | Allow read dependency |
read_runners | boolean | no | Allow read runners |
read_vulnerability | boolean | no | Allow read vulnerability |
remove_group | boolean | no | Allow remove group |
remove_project | boolean | no | Allow remove project |
member_role.delete_group
Section titled “member_role.delete_group”Delete a group-level custom member role. Returns: a success confirmation naming the deleted role and group. See also:
member_role.list_group,member_role.create_group.
- Meta-tool:
gitlab_member_role, actiondelete_group - Individual tool:
gitlab_delete_group_member_role - Tier: Ultimate
- Classic or OAuth token:
api - Fine-grained token: Member Role: Delete at group (permissions page)
- Behavior: writes, destructive (needs confirmation), idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
group_id | string/integer | yes | Group ID or URL-encoded path |
member_role_id | integer | yes | Member role ID to delete |
member_role.delete_instance
Section titled “member_role.delete_instance”Delete an instance-level custom member role. Returns: a success confirmation naming the deleted role. See also:
member_role.list_instance,member_role.create_instance.
- Meta-tool:
gitlab_member_role, actiondelete_instance - Individual tool:
gitlab_delete_instance_member_role - Tier: Ultimate
- Classic or OAuth token:
api - Fine-grained token: Member Role: Delete at instance (permissions page)
- Behavior: writes, destructive (needs confirmation), idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
member_role_id | integer | yes | Member role ID to delete |
member_role.list_group
Section titled “member_role.list_group”List group-level custom member roles. Returns: each role with id, name, description, base_access_level, and its enabled permission flags. See also:
member_role.list_instance,member_role.create_group,member_role.delete_group.
- Meta-tool:
gitlab_member_role, actionlist_group - Individual tool:
gitlab_list_group_member_roles - Tier: Ultimate
- Classic or OAuth token:
read_api(orapi) - Fine-grained token: Member Role: Read at group (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
group_id | string/integer | yes | Group ID or URL-encoded path |
member_role.list_instance
Section titled “member_role.list_instance”List instance-level custom member roles. Returns: each role with id, name, description, base_access_level, and its enabled permission flags. See also:
member_role.create_instance,member_role.delete_instance,member_role.list_group.
- Meta-tool:
gitlab_member_role, actionlist_instance - Individual tool:
gitlab_list_instance_member_roles - Tier: Ultimate
- Classic or OAuth token:
read_api(orapi) - Fine-grained token: Member Role: Read at instance (permissions page)
- Behavior: read-only, idempotent
No parameters.