Document Usage of Jira Connect application with Self-hosted GitLab

Problem to solve

The GitLab for Jira application on the Atlassian Connect marketplace works primarily with GitLab.com, but it is possible to get it working with self-hosted GitLab instances.

Further details

The "application" itself is simply an iframe of a view of GitLab.com, and the routes are defined via the app descriptor which is at https://gitlab.com/-/jira_connect/app_descriptor. This application can only work with GitLab.com, because it is quite literally GitLab.com itself.

There are two (current) methods which allow you to use this same functionality with your own self-hosted GitLab instance:

1. Put Jira in "dev mode", which allows you to enter the URL for the app descriptor manually
2. Publish a "private" application, pointing to that app descriptor

By pointing to your self-hosted app descriptor, the Jira instance communicates with that GitLab installation instead of GitLab.com. Either method works equally well, with caveats on both sides:

1. There is some user objection and wariness about putting their Jira installation in "dev mode". Some view this as a potential problem, though this is primarily a misunderstanding of what the mode does.
2. Using a private listing still requires approval from the Atlassian marketplace, which can take up to two weeks to complete

These docs seem to cover the required steps, and could be modified and condensed to fit our specific needs. They also clearly show that the setting required to be enabled for both methods is in the same UI.

Proposal

We should:

1. Document these two methods of installation on docs.gitlab.com
2. Amend our application listing page to point to these docs

Who can address the issue

@eread

Other links/references

Development mode workaround originally noted by @engwan here: &1626 (comment 230478579)