GitLab for Jira app: Internal/developer technical docs
Problem
Issues like https://gitlab.com/gitlab-com/dev-sub-department/section-dev-request-for-help/-/issues/200 highlight that we do not have good documentation of some technical interactions between GitLab and Jira.
We have improved the customer-facing documentation of data flows in Document security considerations for the GitLab... (#396424 - closed).
In this issue we want to improve technical documentation for developers.
Proposal
Document interactions between GitLab and Jira, and pinpoint the code that's responsible at each point in the flow for these topics:
- The use of GitLab.com and self managed when forwarding Jira lifecycle events (refer to #396424 (closed))
- Linking GitLab groups to Jira subscriptions
- Token auth flows and how tokens are verified
- Lifecycle triggers like installed and uninstalled events, and how they are handled
- Places where data pushes from GitLab to Jira happen and how our payloads are constructed.
Where possible this documentation should be in https://docs.gitlab.com/ee/development/*
and linked from our main GitLab developer documentation.
Examples
Some examples of good documentation are:
- GitHub importer developer docs https://docs.gitlab.com/ee/development/github_importer.html
- Gitlab for Slack app architecture https://gitlab.com/gitlab-org/manage/import-and-integrate/team/-/blob/main/integrations/slack.md#gitlab-for-slack-architecture
Other related issues
- https://gitlab.com/gitlab-com/dev-sub-department/section-dev-request-for-help/-/issues/226 - with info that can be added in https://gitlab.com/gitlab-com/dev-sub-department/section-dev-request-for-help/-/issues/226#note_1806550803
- https://gitlab.com/gitlab-com/dev-sub-department/section-dev-request-for-help/-/issues/173 - closed, check if all information from there has been added
Edited by Luke Duncalfe