Manage namespaces to sync to Jira Cloud Dev Info API from GitLab.com
Atlassian Connect app descriptor JSON file
Create anGithub's app descriptor can be used as reference.
Important parts here are the lifecycle callback URLs and the post install page which we would need to implement.
This will be uploaded to the Atlassian Marketplace for our app to show up there. In development mode, we can provide a URL that returns the JSON file.
lifecycle callback URLs
ImplementThese URLs are called by Atlassian when someone installs and uninstalls our app in Jira. The most important one is the install callback. Client identifiers and the shared secret are sent to us on install and we need to store this.
Possible jira_installations
schema:
Field | Type |
---|---|
id | int |
client_key | string |
base_url | string |
shared_secret | string (encrypted?) |
post install page iframe
Implement GitLab configuration page in aThis is the postInstallPage
module defined in the app descriptor. This will be loaded when the user clicks on "Get Started" in the popup after install and in the Manage Add-ons page.
This is the page where the user can see which namespaces are linked to the Jira install and administer them. This will be rendered in an iframe within Jira and we'd have to use Atlassian's UI Kit. We can consider loading this from Atlassian's CDN if possible so that we won't have to create a separate CSS / JS build for these pages.
Possible jira_linked_namespaces
(or some better name
Field | Type |
---|---|
id | int |
jira_installation_id | int |
namespace_id | int |
List namespaces that are linked
We need to show the user the GitLab namespaces that are already linked to the current Jira account.
For reference, this is GitHub's configuration page within Jira:
When viewing this page, it is not necessary to be logged in to GitLab. We show the data here based on the JWT token generated by Jira which ensures that the user making the request here is an admin of the Jira account.
This does mean that the Jira admin may be able to see the names of private GitLab namespaces which he doesn't have access to.
Users should also be allowed to remove linked namespaces from this page.
Alternative implementations:
We can require that the user is logged in to GitLab on this page and then:
Only list namespaces of the Jira installation where the current GitLab user has Developer+ (or whatever level we want) permissions.
Problem here is that another Jira admin could have added a namespace here and the other Jira admin wouldn't know that it's linked because he doesn't have access to the GitLab namespace.
Worse is when a Jira admin adds a namespace then loses access to the GitLab namespace for some reason. Since he doesn't have access to the namespace anymore, he can't delete the link.
OR we could list all namespaces but blur / obfuscate names / only show ids of namespaces that the current user doesn't have access to. This allows the Jira admin to know that there's a link to a namespace he doesn't have access to (and maybe also delete it?).
This I guess is more complicated though
😃
Adding a namespace
Users can add a namespace from a button / link on the listing page described above.
This can be implemented as a separate page or as a modal.
For this action, the user must be logged in to GitLab so that we can show the namespaces that the user can add. So a workflow to redirect to login page and back should be taken into consideration.
Future iterations
We can only do this when we actually have the syncing part in #9643 (closed):
- Manually trigger a sync
- Show sync status
Other things that need UX / Technical Writer consideration
-
App name / description
This shows up on the Atlassian Marketplace. Currently I set it to "GitLab for Jira" - "Integrate commits, branches and merge requests from GitLab into Jira".
-
Icon for Jira Dev Module
Atlassian docs says this will be rendered as a 16x16 icon within Jira. Currently I set it to https://about.gitlab.com/images/press/logo/png/gitlab-icon-rgb.png. But I'm not sure if we should be using that URL for production.