<!-- The first four sections: "Problem to solve", "Intended users", "User experience goal", and "Proposal", are strongly recommended, while the rest of the sections can be filled out during the problem validation or breakdown phase. However, keep in mind that providing complete and relevant information early helps our product team validate the problem and start working on a solution. --> ### Background Enterprise organizations leverage change management policies and change control systems, such as Jira, to manage the changes they make to company systems and resources. This workflow provides visibility into who made a change, why, when, and what systems or resources it affected. It provides an audit trail of changes and can help isolate problematic changes or prevent non-compliant changes from making it into production systems. Currently, users can add the associated relationship to the `Title`, `Description`, or `Comment` of a Merge Request by entering a ticket reference (e.g. `TEST-2`) |Within a Title|As a mention| |---|---| ||| Then using some complicated logic to crawl a Merge Request for this relationship it can be shown in other tools, like Jira.  ### Problem to solve <!-- What problem do we solve? Try to define the who/what/why of the opportunity as a user story. For example, "As a (who), I want (what), so I can (why/value)." --> Currently, integrating Jira with a GitLab project allows you to associate MRs with Jira issues by typing the Jira ticket ID into the MR title or description. This process is unintuitive, unreliable, and makes external tooling more expensive to build and maintain because there is no single, predictable experience for this association. There is no way for [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) or [Cameron (Compliance Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#cameron-compliance-manager) to reliably know a Jira issue will be associated with an MR. [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) may be unaware of the current, unobvious methods to associate Merge Requests to a Jira issue. ### Intended users * [Cameron (Compliance Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#cameron-compliance-manager) * [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) * [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) * [Rachel (Release Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#rachel-release-manager) ### User experience goal <!-- What is the single user experience workflow this problem addresses? For example, "The user should be able to use the UI/API/.gitlab-ci.yml with GitLab to <perform a specific task>" https://about.gitlab.com/handbook/engineering/ux/ux-research-training/user-story-mapping/ --> A `developer` should have a standard, intuitive way to add a Jira ticket ID to a MR. ### Proposal <!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey --> Implement the following, in order: |1. Add a project-level toggle to require this linkage (to block an MR if it doesn't exist)| |---| || |2. Add QOL improvements to the MR to show the Jira issue is missing| |---| || |3. Add a button to `Edit merge request`| |---| || |4. (maybe) Implement an auto-populating experience of some sort| |---| || ### Further details <!-- Include use cases, benefits, goals, or any other details that will help us understand the problem better. --> Organizations want to encourage a behavior change by making this process easier, more intuitive, and eventually enforceable. Additionally, because of how the association data is manifested today it is difficult to verify and map relationships across platforms. The vision is to extend the auditing capability of Merge Requests to answer the question: does every merge request associate to a change ticket? We will need to add additional capabilities to make this a great compliance experience. Some ideas: 1. **Future iteration:** Extend this experience to include other issues, e.g. GitLab, ServiceNow, etc 1. **Future Iteration:** Accept the an issue ID from a user and perform validation against the service's (e.g. GitLab, Jira, etc) instance to confirm the ticket exists 1. **Future Iteration:** Allow `group owners` to [require this field be completed](https://gitlab.com/gitlab-org/gitlab/-/issues/235626) before MR can be merged _only for regulated projects_ (have a [compliance framework label](https://docs.gitlab.com/ee/user/project/settings/#compliance-framework-premium)) 1. **Future Iteration:** Make this field and value available via Merge Request API 1. **Future Iteration:** Provide auto-complete capabilities to search for Jira tickets as a user types the Jira ticket ID