Achievements

A group or project defines an achievement, and awarding it to a person creates a user achievement: a separate record with its own numeric ID that can be revoked, hidden from a profile, reordered or erased apart from the achievement behind it. So two identifiers run through these actions: achievement_id names the achievement, and user_achievement_id names one award of it, which is what achievement.revoke and the achievement.user_achievement_* actions take.

Revoking an award keeps it on record and marks it revoked, achievement.user_achievement_delete erases one award, and achievement.delete removes the achievement with every award made from it. Achievements are generally available from GitLab 19.3; on an older instance an administrator has to enable the achievements feature flag first.

Sample questions

• “What achievements does the platform group define?”
• “Give the First Contribution achievement to user 42”
• “Who holds the First Contribution achievement?”
• “Hide that award from my profile”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as achievement.award, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_achievement with action set to the action’s name, such as award, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_achievement_award, with its parameters as the arguments.

Availability

Every tier serves the whole group, on self-managed instances and on GitLab.com alike.

Read-only actions: 4 of 12, the ones a deployment in read-only mode keeps.

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. 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
achievement.award	gitlab_achievement_award
achievement.create	gitlab_achievement_create
achievement.delete	gitlab_achievement_delete
achievement.list	gitlab_achievement_list
achievement.recipients	gitlab_achievement_recipients
achievement.revoke	gitlab_achievement_revoke
achievement.unique_users	gitlab_achievement_unique_users
achievement.update	gitlab_achievement_update
achievement.user_achievement_delete	gitlab_achievement_user_achievement_delete
achievement.user_achievement_reorder	gitlab_achievement_user_achievement_reorder
achievement.user_achievement_update	gitlab_achievement_user_achievement_update
achievement.user_list	gitlab_achievement_user_list

achievement.award

Award an achievement to a user. Returns: the new award with its own id, achievement_id, user_id, awarded_by_user_id, award_message, priority, show_on_profile, and timestamps. See also: achievement.revoke, achievement.recipients, achievement.user_list.

• Meta-tool: gitlab_achievement, action award
• Individual tool: gitlab_achievement_award
• Tier: Free
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
achievement_id	integer	yes	Numeric ID of the achievement to hand out
user_id	integer	yes	Numeric ID of the user receiving the achievement
award_message	string	no	Note shown alongside the award, up to 200 characters

achievement.create

Define a new achievement in a group or project namespace. Creating one awards it to nobody. Returns: the created achievement with id, namespace_id, name, description, avatar_url, and timestamps. See also: achievement.award, achievement.list, achievement.update.

• Meta-tool: gitlab_achievement, action create
• Individual tool: gitlab_achievement_create
• Tier: Free
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
name	string	yes	Display name of the achievement such as First Contribution
namespace_id	integer	yes	Numeric ID of the group or project namespace that will own the achievement
avatar_content_base64	string	no	Base64-encoded avatar image bytes. Alternative to avatar_file_path. Only one of the two should be provided
avatar_content_type	string	no	MIME type of the avatar image such as image/png. Defaults to application/octet-stream when omitted
avatar_file_path	string	no	Absolute path to a local image file the MCP server reads. Alternative to avatar_content_base64 for files too large to base64-encode. Only one of the two should be provided, and neither is available when the server is reached over HTTP
avatar_filename	string	no	File name for the avatar image such as badge.png. Required whenever an avatar is sent, because GitLab identifies the upload part by its file name
description	string	no	Free-text explanation of what the achievement is awarded for

achievement.delete

Delete an achievement definition and every award made from it. Returns: deletion confirmation plus the achievement as it looked when removed. See also: achievement.revoke, achievement.list, achievement.create.

• Meta-tool: gitlab_achievement, action delete
• Individual tool: gitlab_achievement_delete
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
achievement_id	integer	yes	Numeric ID of the achievement to delete. Every award made from it is removed with it

achievement.list

List the achievements a group or project namespace defines, with cursor pagination. Returns: each achievement with id, namespace_id, name, description, avatar_url, and timestamps, plus pagination cursors. See also: achievement.recipients, achievement.create, achievement.award.

• Meta-tool: gitlab_achievement, action list
• Individual tool: gitlab_achievement_list
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
full_path	string	yes	Full path of the group or project namespace such as my-group or my-group/my-project
after	string	no	Cursor for forward pagination (from previous response end_cursor)
before	string	no	Cursor for backward pagination (from previous response start_cursor). The page size comes from last, or from first when last is omitted
first	integer	no	Number of items to return (default 20, max 100)
ids	integer[]	no	Numeric achievement IDs to restrict the result to. Omit to list every achievement in the namespace
last	integer	no	Number of items to return from the end of the range (backward pagination). Cannot be combined with first

achievement.recipients

List every award of one achievement, revoked awards and repeat awards included, with cursor pagination. Returns: each award with its own id, achievement_id, user_id, award_message, priority, show_on_profile, and revocation stamps, plus pagination cursors. See also: achievement.unique_users, achievement.user_list, achievement.revoke.

• Meta-tool: gitlab_achievement, action recipients
• Individual tool: gitlab_achievement_recipients
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
achievement_id	integer	yes	Numeric ID of the achievement whose awards to list
full_path	string	yes	Full path of the group or project namespace that owns the achievement
after	string	no	Cursor for forward pagination (from previous response end_cursor)
before	string	no	Cursor for backward pagination (from previous response start_cursor). The page size comes from last, or from first when last is omitted
first	integer	no	Number of items to return (default 20, max 100)
last	integer	no	Number of items to return from the end of the range (backward pagination). Cannot be combined with first

achievement.revoke

Revoke one award while keeping its record, which is then stamped with revoked_at and revoked_by_user_id. Returns: confirmation plus the revoked award. See also: achievement.user_achievement_delete, achievement.award, achievement.recipients.

• Meta-tool: gitlab_achievement, action revoke
• Individual tool: gitlab_achievement_revoke
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
user_achievement_id	integer	yes	Numeric ID of the award to revoke. The award record is kept and marked revoked

achievement.unique_users

List the distinct users who hold one achievement, deduplicated across repeat awards, with cursor pagination. Returns: each user with id, username, name, state, avatar_url, and web_url, plus pagination cursors. See also: achievement.recipients, achievement.user_list, achievement.list.

• Meta-tool: gitlab_achievement, action unique_users
• Individual tool: gitlab_achievement_unique_users
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
achievement_id	integer	yes	Numeric ID of the achievement whose recipients to count
full_path	string	yes	Full path of the group or project namespace that owns the achievement
after	string	no	Cursor for forward pagination (from previous response end_cursor)
before	string	no	Cursor for backward pagination (from previous response start_cursor). The page size comes from last, or from first when last is omitted
first	integer	no	Number of items to return (default 20, max 100)
last	integer	no	Number of items to return from the end of the range (backward pagination). Cannot be combined with first

achievement.update

Change an existing achievement’s name, description, or avatar. Omitted fields keep their current value. Returns: the updated achievement with id, namespace_id, name, description, avatar_url, and timestamps. See also: achievement.list, achievement.create, achievement.delete.

• Meta-tool: gitlab_achievement, action update
• Individual tool: gitlab_achievement_update
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
achievement_id	integer	yes	Numeric ID of the achievement to change
avatar_content_base64	string	no	Base64-encoded avatar image bytes. Alternative to avatar_file_path. Only one of the two should be provided
avatar_content_type	string	no	MIME type of the avatar image such as image/png. Defaults to application/octet-stream when omitted
avatar_file_path	string	no	Absolute path to a local image file the MCP server reads. Alternative to avatar_content_base64 for files too large to base64-encode. Only one of the two should be provided, and neither is available when the server is reached over HTTP
avatar_filename	string	no	File name for the avatar image such as badge.png. Required whenever an avatar is sent, because GitLab identifies the upload part by its file name
description	string	no	New description. Omit to leave the current description unchanged
name	string	no	New display name. Omit to leave the current name unchanged

achievement.user_achievement_delete

Erase one award record outright, keeping no revocation history. Returns: confirmation plus the deleted award. See also: achievement.revoke, achievement.user_list, achievement.delete.

• Meta-tool: gitlab_achievement, action user_achievement_delete
• Individual tool: gitlab_achievement_user_achievement_delete
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
user_achievement_id	integer	yes	Numeric ID of the award to delete. The record is removed outright rather than marked revoked

achievement.user_achievement_reorder

Set the display order of one user’s awards, highest priority first. Returns: confirmation plus every award in its new order with the assigned priority. See also: achievement.user_list, achievement.user_achievement_update, achievement.award.

• Meta-tool: gitlab_achievement, action user_achievement_reorder
• Individual tool: gitlab_achievement_user_achievement_reorder
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
user_achievement_ids	integer[]	yes	Numeric award IDs in the order they should appear, highest priority first. All of one user’s awards should be listed

achievement.user_achievement_update

Change one award, which today means its show_on_profile visibility. Returns: the updated award with id, achievement_id, user_id, priority, show_on_profile, and timestamps. See also: achievement.user_list, achievement.user_achievement_reorder, achievement.update.

• Meta-tool: gitlab_achievement, action user_achievement_update
• Individual tool: gitlab_achievement_user_achievement_update
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
user_achievement_id	integer	yes	Numeric ID of the award to change
show_on_profile	boolean	no	Whether the recipient’s profile displays this award. Omit to leave the current visibility unchanged

achievement.user_list

List the awards one user holds, by username, with cursor pagination. Returns: each award with id, achievement_id, user_id, priority, show_on_profile, award_message, and revocation stamps, plus pagination cursors. See also: achievement.recipients, achievement.user_achievement_reorder, achievement.award.

• Meta-tool: gitlab_achievement, action user_list
• Individual tool: gitlab_achievement_user_list
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
username	string	yes	Account name of the user whose awards to list, without a leading at sign
after	string	no	Cursor for forward pagination (from previous response end_cursor)
before	string	no	Cursor for backward pagination (from previous response start_cursor). The page size comes from last, or from first when last is omitted
first	integer	no	Number of items to return (default 20, max 100)
include_hidden	boolean	no	Include awards the user hid from their profile. Only the user themself and namespace or instance maintainers and owners see these
last	integer	no	Number of items to return from the end of the range (backward pagination). Cannot be combined with first