GitLab Architecture Proposal

[nickoferrall]

Overview

This is a proposal for our GitLab integration (resolves #5564).

Plenty of progress has already been made in #5829. We've also added the oauth integration to Poker in #5973.

To complete the integration, we need to integrate GitLab Cloud with Sprint Poker and Parabol tasks as well as build a GitLab Self-Hosted integration.

Considerations

• Start with the cloud version. It’s best to start small so we can ship value to our users faster. Let’s ship the GitLab Cloud Poker integration, and then build the GitLab task integration & self-hosted version.
• Use GitLab’s GraphQL API. We can grab the exact data that we need vs REST, and Jordan already stitched the GitLab schema into ours using Matt's npm package.
• Use oauth2. It works with cloud and self-hosted. If users request auth with personal access tokens or project access tokens, then we can build them.
• Searching for GitLab issues in Parabol should feel similar to the UX in GitLab as this will be intuitive for users. However, in the GitLab list view, there is a sort button next to the search input (see img below). We could add this button & menu but it would be inconsistent with our other integrations. Instead, I suggest that we sort issues by last used at (see Sprint Poker: GitLab: Display issues #6034) and offer advanced filtering functionality, but wait until users ask for a sort button before building it.

Feature Flag

Here are my thoughts on how we can use the feature flag & roll this out to customers. If this architecture proposal is accepted by the Reviewer & Maintainer, I'll tag Lorena and/or Aviva to get their advice on this section. I'd prefer to get their input then rather than now as the issues may change based on Reviewer & Maintainer feedback.

• Those with access to the GitLab feature flag will be able to play with the integration while it's being built. By default, this will be everyone in Parabol. The Growth team can choose to give specific users access to the feature at any point.
• When v1 is complete, we remove the feature flag and announce it to our customers. At this point, users will be able to see GitLab issues in Sprint Poker, but they won't be able to integrate Parabol tasks with GitLab. They will only be able to do a basic search for issues (see Sprint Poker: GitLab v1: Search issues #6045), rather than an advanced search which will be built in v2 Sprint Poker: GitLab v2: Advanced search UI part 1 #6047.
• Before dev work begins on v2, we should speak with users to see whether they would like the advanced search functionality or whether there are different features they would prefer.

Implementation Steps

If the task integration architecture (see here) is complete before work has begun on v2, we may wish to integrate GitLab with Parabol tasks before moving to v2.

Version 1: Bread & Butter

• Sprint Poker: GitLab: Display issues #6034
• Sprint Poker: GitLab v1: Issues functionality  #6088
• Sprint Poker: GitLab v1: Create new issue #6033
• Sprint Poker: GitLab v1: Search issues #6045
• Sprint Poker: GitLab v1: Project filter menu #6046
• Sprint Poker: GitLab v1: New Search Input UI #6138
• Sprint Poker: GitLab v1: Issue is visible in Estimate phase #6244

Version 2: Fancy Filtering

• Sprint Poker: GitLab v2: Advanced search UI part 1 #6047
• Sprint Poker: GitLab v2: Advanced search logic part 1 #6048
• Sprint Poker: GitLab v2: Persist favourite queries #6049
• Sprint Poker: GitLab v2: Add "Powered by Parabol" comment after voting #6287

Version 3: Polish & Next Steps

• GitLab v3: Task Integration Spec Written #6050
• GitLab v3: Self-Hosted Architectural Spec Written #6051
• Sprint Poker: GitLab v3: Cache search filters proposal #6052

[nickoferrall]

Hey @igorlesnenko, would you mind reviewing this proposal, please?

[nickoferrall]

Hey @igorlesnenko, just pinging you in case you didn't see my review request

[igorlesnenko]

@nickoferrall looks good to me!

[mattkrick]

looks great!
since this issue is the deliverable, i'm gonna remove it from the sprint board & i moved it to the top of the epic.

[jordanh]

Labelling discussion to remove from default Backlog Grooming query

[jordanh]

@nickoferrall would it be ok to close this issue?

[nickoferrall]

Yep, it's safe to close!