Skip to content

Jira app - improve setup required instructions for GitLab.com

Problem

For both GitLab.com and self-managed - we require that the Jira user that is setting up the GitLab for Jira app is a Site administrator in Atlassian. This is being added to the docs into a new section called "Jira user requirements" via this MR !135671 (merged)

In #427655 (closed), we introduced a checklist for self-managed users to complete in the Jira app. While !135671 (merged) will cross link to the newly proposed "Jira user requirements", we don't have an equivalent checklist for GitLab.com users.

The newly proposed "Jira user requirements" section will also apply to GitLab.com users, and we don't currently instruct users that exclusively install the app via the Atlassian store that their Jira user needs to meet specific requirements.

Proposal

Once !135671 (merged) is merged and we have a "Jira user requirements" section in our docs, should we update the GitLab for Jira app so that:

  • The checklist for the self-managed section also includes a link to the "Jira user requirements" section
  • Add a new step (whether it is just a link on the step, or the checklist format) for the GitLab.com section that includes a link to the "Jira user requirements" section

By ensuring readers meet the requirements on their Jira user, this will hopefully mitigate the risk of them running into the common Failed to link group error https://docs.gitlab.com/ee/administration/settings/jira_cloud_app.html#failed-to-link-group.