GitLab for Jira app self-managed rollout UX

I lined out the steps to roll out the Jira Cloud App proxy for Self-managed GitLab users feature and found that users might not be aware of the additional setup needed and end up with a broken app.

Step 1: enable jira_connect_oauth on GitLab.com

The setup will be done on GitLab.com. Users will then be asked to sign-in via OAuth when accessing the configuration page, but no additional setup is needed.

Step 2: enable jira_connect_oauth for self-managed

Using the app for self-managed is already possible with a workaround. For instances using the workaround, Data sync with Jira will continue to work, but this is what users will see when entering the configuration page:

oauth_not_working

I think we should place a message there if the client_id is not defined. Maybe like this:

GitLab for Jira has switched to OAuth authorization from version 15.x on. Please follow the steps to set up OAuth: documentation_link. You need to have an admin account

Step 3: enable jira_connect_oauth_self_managed

This will introduce official support for self-managed. Users setting up self-managed will see this screen:

Screenshot_2022-08-10_at_14.00.16

But the Sign in button wouldn't work unless OAuth is set up on the instance. We should place a message there too and point users to the documentation. In a later iteration, we can detect if the client_id is set on the instance and only show the message if the setup isn't completed.

Iteration Plan

  1. We'll deliver the first iteration of the GitLab for Jira App Self-Managed Proxy, which will include documentation or a video to guide users through the process.
    1. We'll isolate users of of the Self-managed workaround for the time being and will not deliver the OAuth update to this set of customers. There will be no impact to them.
    2. During this iteration, any users with browsers disallowing cross-site cookies would experience issues logging in to the GitLab for Jira App from Jira.
    3. But if someone wants to switch to OAuth, they can enable the feature on their instance using this guide.
  2. Next we'll iterate to help migrate users of the workaround to the official GitLab for Jira App.
  3. We'll then improve the workflow to reduce complexities and provide smoother UX.

Figma file

Edited by Katie Macoy - on PTO