<!-- Use this template as a starting point for deprecations. -->

**A written process alone is unlikely to be sufficient to navigate through many
complexities. Please use this template as guidance with steps to take when
deprecating functionality, but not as an exhaustive list designed to generate
positive outcomes every time. Deprecations are often nuanced in their impact and
the approach needed may not be fully covered in this template.**

---

### Deprecation Summary

_Add a brief description of the feature or functionality that is deprecated.
Clearly state the potential impact of the deprecation to end users._

#### Documentation

- Deprecation notice: [add link](here)
- Migration guidelines: [add link](here)
- etc.

#### Reasons

\_Describe why deprecation of this feature is necessary

- [add links to the documentation](here) - i.e. Decision-Matrix, etc.

### Breaking Change?

<!-- If the change includes removing functionality, which nearly all deprecations do, then it needs to be tracked as a breaking change. If user workflows rely on it to function, then removing it will break them. -->

Does this deprecation contain a breaking change? `Yes / No`

<!-- If yes:
- Add the ~"breaking change" label to this issue.
- Add instructions for how users can update their workflow.
- After creating this issue, add an Internal Note in the comments below to document the pros and cons of this change and why we are choosing to make a breaking change. Answer the following:
   - What migration paths are available?
   - Describe tradeoffs between the migration paths taking into account customer, financial, technical or operational impact?
   - Are there different migration path options for different users? (ex. available for ultimate users, but not free users?)
   - Are there external requirements that we need to meet that restrict our available options?
   - Consider the information you will also be adding in the "Affected Customers" section - this will impact how you plan for migration alternatives.
 -->

<!--
/label ~"breaking change"
-->

### Affected Users

Who is affected by this deprecation: GitLab.com users, Self-managed users, or
Dedicated users? (choose all that apply)

- [ ] GitLab.com
- [ ] Self-managed
- [ ] Dedicated

### Deprecation Milestone

This deprecation will be announced in milestone: `xx.xx` _If this deprecation
has already been announced, include information about when the initial
announcement went out and what follow-up announcements are scheduled._

### Planned Removal Milestone

The feature / functionality will be removed in milestone: `xx.xx`

### Links

<!--
Add links to any relevant documentation or code that will provide additional details or clarity regarding the planned change.

This issue is the main SSOT for the deprecations and removals process. Be sure to link all
issues and MRs related to this deprecation/removal to this issue. This can include removal
issues that were created ahead of time, and the MRs doing the actual deprecation/removal work.
-->

### Checklists

#### Timeline

#### Communication Plan

- DRI Product Manager: `@PM`

An internal slack post and a release post are not sufficient notification for
our customers or internal stakeholders. Plan to communicate proactively and
directly with affected customers and the internal stakeholders supporting them.

Internal Communication Plan

- [ ] Internal announcement plan (timeline for notifications, audience,
      channels, etc)

External Communication Plan

- [ ] User announcement plan (timeline for notifications, audience, channels,
      etc)
  - [ ] Documentation has been updated to mark the feature as `deprecated`. _Add
        link to the relevant merge request._
- [ ] On the major milestone:
  - [ ] The deprecated item has been removed. _Add link to the relevant merge
        request._
  - [ ] If the removal of the deprecated item is a
        [breaking change](https://docs.gitlab.com/update/terminology/#breaking-change),
        the merge request is labeled ~"breaking change".
  - [ ] Document the migration plan for users, clearly outlining the actions
        they need to take to mitigate the impact of the breaking change.
    - [ ] [Add link](here)

#### Labels

<!-- Populate the Section, Group, and Category -->

/label ~group: ~"Category:

- [ ] This issue is labeled ~deprecation, and with the relevant `~group::`, and
      `~Category:` labels.
- [ ] This issue is labeled ~"breaking change" if the removal of the deprecated
      item will be a
      [breaking change](https://docs.gitlab.com/update/terminology/#breaking-change).

<!-- Identifies that this Issue is related to deprecating a feature -->

/label ~"deprecation"