Group Access Token availability on GitLab.com SaaS is unclear (docs, settings)

Proposal

The availability of Group Access Tokens is unclear in the docs, and group settings.

The documentation hides the availability in a long text block, which seems hard to digest and parse. The group settings show the feature to configure, with no clear error messages on the why.

The group settings show the feature available, when it should not.

This leads to user frustration, and many questions in the community forum in this topic: https://forum.gitlab.com/t/gitlab-impossible-to-enable-group-access-token/81540

Suggested fixes

• Modify the Product Tier banner in the documentation, and say that Group Access Tokens are only available on GitLab.com SaaS in Premium/Ultimate.
• For Free Tier users: Modify the group settings on GitLab.com SaaS, grey them out and add a note linking to /pricing UX guidance is to hide features that are not available to users, e.g. through a subscription. https://design.gitlab.com/usability/feature-management#visibility
• Update the UI copy on the Access tokens page: The current copy on the page is confusing in the situation where a group previously had created access tokens but no longer has creation access to the feature (like when a paid plan expires). See current and proposed copy (pending TW feedback)

/cc @hsutor @jglassman1

added Category:System Access GitLab Premium GitLab Ultimate bugavailability documentation groupauthentication sectionsec typebug labels

added devopsgovern label

changed the description

changed milestone to %Backlog

@jglassman1 Would you be willing to take on the docs portion of this request when you have capacity?

@jglassman1 Thanks for the fast docs update, I consider this done

@hsutor Who could address the UX parts? I think it only affects frontend, deciding on the user tier how to visualize the setting (intact, or greyed out).

@dnsmichi I believe our rule of thumb with unavailable features is to not display them at all rather than gray them out/disable them. @esybrant Can you confirm?

Once we know the expected UX we can put this in the queue for frontend (or maybe a Community contribution ?)

@hsutor @dnsmichi I believe that our best practice is to hide the nav items that users don't have access to rather than gray them out.

I can't find the guidance in PJs, though, so I've asked about it in Slack to confirm.

@hsutor @dnsmichi Sorry for the additional ping, but I have a link to PJs guidance now:

A feature is hidden when the user shouldn't have access to it due to a lack of permissions. Hiding the feature is recommended because the user doesn't need to be aware of the functionality, and there is no UI that would allow them to obtain access. For example, we should hide the delete branch button if the user's role does not allow deletion of branches.

Based on this guidance, we should hide the Access tokens item if the feature is unavailable to the user/group.

@esybrant @hsutor Thanks for your research, and the great resource https://design.gitlab.com/usability/feature-management#visibility (bookmarked for future questions).

This UX recommendation changes my suggestion with showing the feature as greyed out to keeping it hidden, when the user has no access to it - for example, on GitLab.com SaaS groups in the free tier. This keeps the UX consistent with other features.

We can revisit this decision in future iterations, e.g. for user conversions or onboarding cc @s_awezec

Summary

The documentation explains the group access token availability, and will be the next step for users researching feature availability. Since we updated the documentation earlier, this issue has no more tasks and we can close it, if you agree.

@dnsmichi Would we be able to update the UI copy on the Access tokens page as part of this issue?

As @leipert pointed out in the Slack thread, the current copy on the page is confusing in the situation where a group previously had created access tokens but no longer has creation access to the feature (like when a paid plan expires).

Current copy	Proposed copy
Group access token creation is disabled in this group. You can enable group access token creation in group settings. You can still use and manage existing tokens. Learn more.	Group access token creation is disabled in this group. On GitLab.com only Premium or Ultimate Groups which are not on a trial have access to token creation. You can still use and manage existing tokens. Learn more.

cc @jglassman1 for TW review

@esybrant

Would we be able to update the UI copy on the Access tokens page as part of this issue?

Please go with bias for action :) And thanks for highlighting, I did not read the linked Slack thread.

Issue description updated

Thanks @esybrant. My feedback:

• Two very minor style tweaks: On GitLab.com only Premium or Ultimate Groups which are not on a trial have access to token creation. => On GitLab.com, only Premium or Ultimate groups which are not on a trial have access to token creation.
• Can we make the link text more descriptive? Instead of Learn more, perhaps we could say See [descriptive link] for more information.

Current copy	Proposed copy
Group access token creation is disabled in this group. You can enable group access token creation in group settings. You can still use and manage existing tokens. Learn more.	Group access token creation is disabled in this group. On GitLab.com only Premium or Ultimate Groups which are not on a trial have access to token creation. You can still use and manage existing tokens. Learn more.

@jglassman1 / @idurham - I saw this issue come up in triage. Could we update the copy to your suggestion and then close this out? I believe the merged MR already partially addressed this.

@hsutor

Current copy	Proposed copy
Group access token creation is disabled in this group. You can enable group access token creation in group settings. You can still use and manage existing tokens. Learn more.	Group access token creation is disabled in this group. On GitLab.com, only Premium or Ultimate groups which are not on a trial have access to token creation. You can still use and manage existing tokens. For more information, see [group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html).

mentioned in merge request !145800 (merged)

assigned to @jglassman1

dark pattern to me to hide the settings instead of disabling it with the relevant documentation link ref groups/settings/_resource_access_token_creation.html.haml

@childNode Thanks for your feedback. I have added the UX guidance resources into the issue description, after learning about it in this discussion thread #442671 (comment 1847234816)

changed the description

marked the checklist item Modify the Product Tier banner in the documentation, and say that Group Access Tokens are only available on GitLab.com SaaS in Premium/Ultimate. as completed

changed the description

changed the description

unassigned @jglassman1

I just spent 20 odd minutes trying to figure out why I couldn't create a project access token as per the documentation.

This should be a very simple change folks. Just highlight that Project or Group Access Tokens are only available on a paid tier on SaaS!

changed milestone to %17.8

assigned to @hsutor

mentioned in merge request !177176

added workflowin dev label

changed milestone to %17.9

added missed:17.8 label

changed milestone to %17.10

added missed:17.9 label

This issue was put in one year ago. The amount of human hours wasted trying to find this setting. The amount of human hours wasted writing up questions on why we can't find this setting. The amount of human hours wasted on trying to tell people this setting is premium only. Someone needs to point a spotlight on this wasted time and energy.

changed milestone to %17.11

added missed:17.10 label