UX issue: Users fail to onboard new repositories for scanning

[wkl3nk]

During UX testing sessions at Bosch with potential future users of the ORT Server UI, we encountered a significant usability issue: Users consistently failed to add a new repository to be scanned by OCaaS (Open Source Compliance as a Service).

Currently, there is a form that allows entering the repository URL, selecting the repository type, and optionally adding a description. However, this was not sufficient for users to complete the onboarding process successfully.

One major source of confusion is that the UI does not make it clear that – in most cases – OCaaS also requires credentials (e.g., username and password) to access the repository. Even if users realize this requirement, the current process forces them to:

• Navigate to a separate section of the UI to create secrets (for username and password),
• Then go to another section to create an Infrastructure Service and link the newly created secrets to that Infrastructure Service

From a UX perspective, this is a highly fragmented and unintuitive flow. Expecting users to switch between three different sections of the UI just to add a new repository is simply not acceptable for such a common task.

Proposal:

To improve the onboarding experience, we suggest the following:

On the same page where a repository is created, users should have the option to directly provide credentials (e.g., username and password) if needed.

If credentials are entered, the UI should:

• Automatically create the necessary secrets,
• Create a corresponding Infrastructure Service behind the scenes,
• And link everything appropriately – all as part of the repository creation process.

Credential entry remains optional – users can still take the manual, multi-step approach if they prefer.

The UI should also include a hint that, in some cases, it might be preferable to use shared credentials instead of per-repository ones.
So all in all, it could look like this:

We believe this approach would drastically lower the barrier to onboarding repositories and improve first-time user experience.
There is a PR at #3124 that implements this.

[sschuberth]

The UI should also include a hint that, in some cases, it might be preferable to use shared credentials instead of per-repository ones.

I doubt that giving a hint is the best we can do in terms of improving UX. How about, instead of adding username / password fields, having a dropdown with all available shared credentials, plus two special entries named "No authentication required" (or similar) and "Create new credentials" (or similar)? Then clicking on the latter would open dialog to create named credentials, adding them to the dropdown and using them for repository.

[wkl3nk]

• We don't even know which secrets are usernames, and which secrets are passwords, so we would propose secrets that act as usernames for selection as passwords, and propose secrets that act as passwords as usernames.
• We cannot even show the value of this secrets, like a username abc123 that would help the user to choose the right one, because this is the nature of the secrets that we don't show their value. So it remains a guessing game.

The most intuitive way from UX perspective is to let the user directly specify username and password.

[sschuberth]

Oh, wow. I was assuming that we'd have a concept of "named credentials" where credentials are always pairs of a username and an optional password (or another mean of authentication). Looks like I was wrong...

[mnonnenmacher]

These "named credentials" are the infrastructure services. They associate a username and password with a URL. When cloning a repository, the infrastructure service with the URL that best matches the repository URL is chosen for authentication. This allows to share credentials for the same host, for example:

• If the URL of the infrastructure service is https://github.com it will be used for all GitHub repositories.
• If the URL of the infrastructure service is https://github.com/eclipse-apoasis it will be used for all GitHub repositories in the eclipse-apoapsis org.

But currently there is no way to directly associate an infrastructure service with a repository, so implementing a dropdown would not be possible. Instead, the UI could offer to create a new infrastructure service and prefill the URL field. Ideally only if credentials are not already available (see the comment below).

[oheger-bosch]

This goes a bit in the direction what I have commented here: #1718 (reply in thread)

[MarcelBochtler]

Yes, the current user flow is really not intuitive, and it has to be improved.

However, I disagree with your proposal from a UX perspective.
Adding two new input fields and a hint improves the creation of Secrets only for this specific repository.

But credentials and infrastructure services should in most cases be shared on Organization or Product level, because this makes updating the credentials way easier and painless.
Your proposal nudges the user to always create secrets on a repository level.
Additionally, your proposal might also result in users entering credentials even if they are already available on Org/Product level.

The best workflow IMO would be:

1. User enters repository URL

2. The UI and Backend check if the system already has access to the entered repository.

3a. Credentials and Infrastructure Services already exist and the system has access to the repository (provided by Org/Product level credentials)
--> Show a green checkmark

3b. The system does not have access yet.
--> Provide input fields for these values, similar to your proposal. However, let the user also choose on what level these credentials should be created.

As a stop gap measure I'm ok with your proposal, but due to the issues mentioned above, I think that we should improve this approach later.

[sschuberth]

The UI and Backend check if the system already has access to the entered repository.

However, that approach does not help to reuse shared credentials which are used across multiple repositories.

[mnonnenmacher]

However, that approach does not help to reuse shared credentials which are used across multiple repositories.

Could you explain why? Because I would say it helps if the UI could show that there are already credentials available that can be reused.

[sschuberth]

I wasn't aware of the heuristics you described above, but still, if you have totally unrelated URLs from different hosts and still want to use single shared credentials for both of them, I do not see how that check for "already having access" could work.

[wkl3nk]

As a first short-term measure to improve the UX situation, I would like to add tooltips in the pages where new secrets are created. Users should (voluntarily) adhere to some conventions regarding the names of secrets. I recommend to use prefixes like "username-abc123" or "password-for-user-abc123" as names for the secrets. This recommendation at least would give the users some hints, and drastically improve the chances that Secrets are actually really shared and reused. See #3146 for details.

[wkl3nk]

Having the .ort.env.yml generating Infrastructure Services on the fly each time a repository is scanned, we possibly should keep the idea that an Infrastructure Service has 2 secrets: One for username, the second one for password/PAT.

But, what do you think about the following idea:
Whenever a new secret is generated, the user must state if this is used as username, or as password/PAT.
In the UI, when an Infrastructure Service is created, this would allow to only offer Username Secrets in the ComboBox for username, and only Password/PAT Secrets in the ComboBox for password/PAT.

This would mean, we would make the abstraction of a Secret more concrete, e.g. into a UsernameSecret and a PasswordPATSecret.

What do you think? It would bring forward UX.

[sschuberth]

I'm still wondering whether we should expose the low-level concept of secrets to users at all. Is there a case where users really need to deal with secrets? Don't they always need to deal with credentials only? And why are usernames treated as secrets at all?

I fear that if we don't get this right by now, we never will, as the migration effort will be considered too large for user-managed configuration files.

[oheger-bosch]

FTR, I am aware of only one exception where secrets occur outside the context of credentials; this is to set the value for an environment variable - here a single secret can be referenced.

Regarding the proposal of @wkl3nk, I have the following questions:

• So, we would basically introduce a categorization for secrets. Is it clear upfront which categories to use? Are the categories "username" / "password/PAT" sufficient or will this confuse users who might think "This is not a password or PAT, but an API key, an OAuth client secret, a PIN, ..."?
• If we later decide to implement a credentials concept, is there then a way to do a migration of these categories?

[Etsija]

I wholeheartedly agree with @wkl3nk that the current UX for adding a private repository is terrible. I don't think there actually even exists a workflow for that. At least, I don't know how to do it with the current secrets + infrastructure services entities. I think the usage of those monstrocities should completely be hidden from all non-admins.

The first UX improvement would come from a simple "Test Repository Access" button, which is quite common in web apps of different kind. Interestingly enough, GitHub API actually gives pretty good information, which I tried. I have a private repository on my GitHub, so just by running this

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer YOUR_PAT" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO_NAME

returns:

1. without YOUR_PAT given: 401 Bad credentials
2. with YOUR_PAT given: 200 Success with the data
3. with YOUR_PAT given, but incorrect URL: 404 Not found

This would already improve the UX: the user enters a Git URL of a private repository, then pushes the button, which tells in the UI that the repository is probably private and the user needs to provide credentials. Currently, no such check exists and the user finds this out when starting the ORT run which immediately fails.

[Etsija]

Adding private repositories could - and should - be streamlined in the UI: for example,

1. Dropdown public/private, default public -> the form stays as it is.
2. When choosing private from dropdown -> show the required additional fields (User/credentials/PAT) in the form, and DON'T REQUIRE the user to go elsewhere and create a mystical "infrastructure service", then come back. Instead, provide all needed data in THIS form, and on submit, in the background do whatever needs to be done to make it happen. Create infra service (with a generic name which could be built here), if that's needed (I don't even know), create secrets etc.

The bottomline is: currently, this part (and many other) in the UI is targeted for engineers who built the service, not for those who want to use it. Onboarding new customers is at the moment extremely difficult. We cannot give them the keys and say, "hey take this for a spin". The whole process will grind to a halt the minute the customer wants to add a private Git repository to his product.

[Etsija]

...and, having said all this, I blame myself for so far building the UI too tightly to implement everything directly against the REST endpoints we have. I believe that's one of the reasons why it gives such an engineer-y feeling at the moment. I believe, with careful planning, a lot of the stuff like calling several endpoints to make something a bit "bigger" to happen, without telling/exposing everything to the user, could be the way to a better UX.