アチーブメント

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed
ステータス: 実験的機能

GitLab Self-Managedでは、デフォルトでこの機能は使用できません。管理者がachievementsという名前の機能フラグを有効にすると、この機能を使用できるようになります。

GitLabのアクティビティーに対してユーザーに報酬を与える方法がアチーブメントです。ネームスペースのメンテナーまたはオーナーとして、特定のコントリビューションに対してカスタムアチーブメントを作成できます。定義された基準に基づいて、これらのアチーブメントをユーザーに授与したり、失効させたりすることができます。

ユーザーは、自分のプロフィールのさまざまなプロジェクトまたはグループへのコントリビューションを強調するために、アチーブメントを収集できます。アチーブメントは、名前、説明、およびアバターで構成されます。

アチーブメントは、ユーザーが所有するものと見なされます。これらは、アチーブメントを作成したネームスペースの表示レベル設定に関係なく表示されます。

この機能は、実験です。計画された作業の詳細については、エピック9429を参照してください。エピックにコメントを残して、ユースケースをお知らせください。

アチーブメントの種類

プログラムでアチーブメントを作成、授与、失効、または削除する方法は1つしかありません。

実際には、授与されるアチーブメントを区別できます:

1回限りで取り消し不能。たとえば、「最初のコントリビューションがマージされました」アチーブメント。
1回限りで取り消し可能。たとえば、「コアチームメンバー」アチーブメント。
複数回。たとえば、「今月のコントリビューター」アチーブメント。

グループアチーブメントを表示

グループで利用可能で授与されたすべてのアチーブメントを表示するには:

https://gitlab.com/groups/<group-path>/-/achievementsに移動します。

このページには、アチーブメントのリストと、アチーブメントを授与されたメンバーが表示されます。

ユーザーのアチーブメントを表示

ユーザーのプロファイルページで、ユーザーのアチーブメントを表示できます。

前提要件:

ユーザープロファイルは公開されている必要があります。

ユーザーのアチーブメントを表示するには:

ユーザーのプロフィールページに移動します。
ユーザーのアバターの下に、そのアチーブメントが表示されます。
アチーブメントの詳細を表示するには、カーソルを合わせる。次の情報が表示されます:
- アチーブメントの名前
- アチーブメントの説明
- アチーブメントがユーザーに授与された日付
- ユーザーがネームスペースのメンバーであるか、ネームスペースが公開されている場合にアチーブメントを授与したネームスペース

ユーザーのアチーブメントのリストを取得するには、user GraphQLタイプをクエリします。

query {
  user(username: "<username>") {
    userAchievements {
      nodes {
        achievement {
          name
          description
          avatarUrl
          namespace {
            fullPath
            name
          }
        }
      }
    }
  }
}

アチーブメントを作成

特定のコントリビューションに対して授与するカスタムアチーブメントを作成できます。

前提要件:

ネームスペースのメンテナーまたはオーナーロールを持っている必要があります。

アチーブメントを作成するには:

UIの場合:
1. アチーブメントページで、新しいアチーブメントを選択します。
2. アチーブメントの名前を入力します。
3. オプション。アチーブメントの説明を入力し、アバターをアップロードします。
4. 変更を保存を選択します。

GraphQL APIを使用して、achievementsCreate GraphQLミューテーションを呼び出す:

mutation achievementsCreate($file: Upload!) {
  achievementsCreate(
    input: {
      namespaceId: "gid://gitlab/Namespace/<namespace id>",
      name: "<name>",
      description: "<description>",
      avatar: $file}
  ) {
    errors
    achievement {
      id
      name
      description
      avatarUrl
    }
  }
}

アバターファイルを指定するには、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'

成功すると、応答はアチーブメント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"}}}}

アチーブメントを更新

アチーブメントの名前、説明、およびアバターはいつでも変更できます。

前提要件:

ネームスペースのメンテナーまたはオーナーロールを持っている必要があります。

アチーブメントを更新するには、achievementsUpdate GraphQLミューテーションを呼び出す。

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
    }
  }
}

アチーブメントを授与

ユーザーのコントリビューションを認識するために、アチーブメントをユーザーに授与できます。ユーザーがアチーブメントを授与されると、メール通知が届きます。

前提要件:

ネームスペースのメンテナーまたはオーナーロールを持っている必要があります。

ユーザーにアチーブメントを授与するには、achievementsAward GraphQLミューテーションを呼び出す。

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
  }
}

アチーブメントを失効

ユーザーが授与基準を満たさなくなったと判断した場合は、ユーザーのアチーブメントを失効できます。

前提要件:

ネームスペースのメンテナーまたはオーナーロールを持っている必要があります。

アチーブメントを失効するには、achievementsRevoke GraphQLミューテーションを呼び出す。

mutation {
  achievementsRevoke(input: {
    userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>" }) {
    userAchievement {
      id
      achievement {
        id
        name
      }
      user {
        id
        username
      }
      revokedAt
    }
    errors
  }
}

授与されたアチーブメントを削除

誤ってアチーブメントをユーザーに授与した場合は、削除できます。

前提要件:

ネームスペースのオーナーロールを持っている必要があります。

授与されたアチーブメントを削除するには、userAchievementsDelete GraphQLミューテーションを呼び出す。

mutation {
  userAchievementsDelete(input: {
    userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>" }) {
    userAchievement {
      id
      achievement {
        id
        name
      }
      user {
        id
        username
      }
    }
    errors
  }
}

アチーブメントを削除

アチーブメントが不要になった場合は、削除できます。これにより、アチーブメントの関連するすべての授与済みインスタンスと失効済みインスタンスが削除されます。

前提要件:

ネームスペースのメンテナーまたはオーナーロールを持っている必要があります。

アチーブメントを削除するには、achievementsDelete GraphQLミューテーションを呼び出す。

mutation {
  achievementsDelete(input: {
    achievementId: "gid://gitlab/Achievements::Achievement/<achievement id>" }) {
    achievement {
      id
      name
    }
    errors
  }
}

アチーブメントを非表示

プロファイルにアチーブメントを表示したくない場合は、オプトアウトできます。これを行うには、次の手順を実行します:

左側のサイドバーで、自分のアバターを選択します。
プロファイルの編集を選択します。
主要設定セクションで、プロファイルにアチーブメントを表示するチェックボックスをオフにします。
プロファイル設定を更新を選択します。

特定のアチーブメントの表示レベルを変更

プロファイルにすべてのアチーブメントを表示したくない場合は、特定のアチーブメントの表示レベルを変更できます。

アチーブメントの1つを非表示にするには、userAchievementsUpdate GraphQLミューテーションを呼び出す。

mutation {
  userAchievementsUpdate(input: {
    userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>"
    showOnProfile: false
  }) {
    userAchievement {
      id
      showOnProfile
    }
    errors
  }
}

アチーブメントを再度表示するには、showOnProfile引数の値trueを指定して同じミューテーションを呼び出す。

アチーブメントの順序を変更

デフォルトでは、プロファイルのアチーブメントは、授与された日付の昇順で表示されます。

アチーブメントの順序を変更するには、優先順位が付けられたすべてのアチーブメントの順序付きリストを使用して、userAchievementPrioritiesUpdate GraphQLミューテーションを呼び出す。

mutation {
  userAchievementPrioritiesUpdate(input: {
    userAchievementIds: ["gid://gitlab/Achievements::UserAchievement/<first user achievement id>", "gid://gitlab/Achievements::UserAchievement/<second user achievement id>"],
    }) {
    userAchievements {
      id
      priority
    }
    errors
  }
}