doc/user/profile/achievements.md
{{< details >}}
{{< /details >}}
{{< history >}}
achievements. Disabled by default.{{< /history >}}
[!flag] On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can enable the feature flag named
achievements.
Achievements are a way to reward users for their activity on GitLab. As a namespace maintainer or owner, you can create custom achievements for specific contributions. You can award these achievements to users or revoke them based on defined criteria.
As a user, you can collect achievements to highlight your contributions to different projects or groups on your profile. An achievement consists of a name, a description, and an avatar.
Achievements are considered to be owned by the user. They are visible regardless of the visibility setting of the namespace that created the Achievement.
This feature is an experiment. For more information about planned work, see epic 9429. Tell us about your use cases by leaving comments in the epic.
Programmatically, there is only one way to create, award, revoke, or delete achievements.
Practically, you can differentiate between achievements that are awarded:
To view all available and awarded achievements for a group:
https://gitlab.com/groups/<group-path>/-/achievements.The page displays a list of achievements and the members who were awarded the achievement.
You can view a user's achievements on their profile page.
Prerequisites:
To view a user's achievements:
Go to the user's profile page.
Below the user's avatar, see their achievements.
To view details about an achievement, hover over it. It displays the following information:
To retrieve a list of a user's achievements, query the user GraphQL type.
query {
user(username: "<username>") {
userAchievements {
nodes {
achievement {
name
description
avatarUrl
namespace {
fullPath
name
}
}
}
}
}
}
You can create custom achievements to award for specific contributions.
Prerequisites:
To create an achievement:
In the UI:
With the GraphQL API, call the achievementsCreate GraphQL mutation:
mutation achievementsCreate($file: Upload!) {
achievementsCreate(
input: {
namespaceId: "gid://gitlab/Namespace/<namespace id>",
name: "<name>",
description: "<description>",
avatar: $file}
) {
errors
achievement {
id
name
description
avatarUrl
}
}
}
To supply the avatar file, call the mutation using curl:
curl "https://gitlab.com/api/graphql" \
-H "Authorization: Bearer <your-pat-token>" \
-H "Content-Type: multipart/form-data" \
-F operations='{ "query": "mutation ($file: Upload!) { achievementsCreate(input: { namespaceId: \"gid://gitlab/Namespace/<namespace-id>\", name: \"<name>\", description: \"<description>\", avatar: $file }) { achievement { id name description avatarUrl } } }", "variables": { "file": null } }' \
-F map='{ "0": ["variables.file"] }' \
-F 0='@/path/to/your/file.jpg'
When successful, the response returns the achievement ID:
{"data":{"achievementsCreate":{"achievement":{"id":"gid://gitlab/Achievements::Achievement/1","name":"<name>","description":"<description>","avatarUrl":"https://gitlab.com/uploads/-/system/achievements/achievement/avatar/1/file.jpg"}}}}
You can change the name, description, and avatar of an achievement at any time.
Prerequisites:
To update an achievement, call the achievementsUpdate GraphQL mutation.
mutation achievementsUpdate($file: Upload!) {
achievementsUpdate(
input: {
achievementId: "gid://gitlab/Achievements::Achievement/<achievement id>",
name: "<new name>",
description: "<new description>",
avatar: $file}
) {
errors
achievement {
id
name
description
avatarUrl
}
}
}
You can award an achievement to a user to recognize their contributions. The user receives an email notification when they are awarded an achievement.
Prerequisites:
To award an achievement to a user, call the achievementsAward GraphQL mutation.
mutation {
achievementsAward(input: {
achievementId: "gid://gitlab/Achievements::Achievement/<achievement id>",
userId: "gid://gitlab/User/<user id>" }) {
userAchievement {
id
achievement {
id
name
}
user {
id
username
}
}
errors
}
}
You can revoke a user's achievement if you consider the user no longer meets the awarding criteria.
Prerequisites:
To revoke an achievement, call the achievementsRevoke GraphQL mutation.
mutation {
achievementsRevoke(input: {
userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>" }) {
userAchievement {
id
achievement {
id
name
}
user {
id
username
}
revokedAt
}
errors
}
}
If you awarded an achievement to a user by mistake, you can delete it.
Prerequisites:
To delete an awarded achievement, call the userAchievementsDelete GraphQL mutation.
mutation {
userAchievementsDelete(input: {
userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>" }) {
userAchievement {
id
achievement {
id
name
}
user {
id
username
}
}
errors
}
}
If you consider you no longer need an achievement, you can delete it. This deletes all related awarded and revoked instances of the achievement.
Prerequisites:
To delete an achievement, call the achievementsDelete GraphQL mutation.
mutation {
achievementsDelete(input: {
achievementId: "gid://gitlab/Achievements::Achievement/<achievement id>" }) {
achievement {
id
name
}
errors
}
}
If you don't want to display achievements on your profile, you can opt out. To do this:
{{< history >}}
{{< /history >}}
If you don't want to display all achievements on your profile, you can change the visibility of specific achievements.
To hide one of your achievements, call the userAchievementsUpdate GraphQL mutation.
mutation {
userAchievementsUpdate(input: {
userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>"
showOnProfile: false
}) {
userAchievement {
id
showOnProfile
}
errors
}
}
To show one of your achievements again, call the same mutation with the value true for the showOnProfile argument.
By default, achievements on your profile are displayed in ascending order by awarded date.
To change the order of your achievements, call the userAchievementPrioritiesUpdate GraphQL mutation
with an ordered list of all prioritized achievements.
mutation {
userAchievementPrioritiesUpdate(input: {
userAchievementIds: ["gid://gitlab/Achievements::UserAchievement/<first user achievement id>", "gid://gitlab/Achievements::UserAchievement/<second user achievement id>"],
}) {
userAchievements {
id
priority
}
errors
}
}