Request to remove premature deprecation notices from Epic and EpicIssues APIs

Background

In the recent update to v0.128.0 of the GitLab API client (gitlab.com/gitlab-org/api/client-go), several Epic-related API methods were marked as deprecated in merge request !2237. Specifically, the following methods now include deprecation notices indicating they "will be removed in v5 of the API, use Work Items API instead":

• Epics.ListGroupEpics
• Epics.GetEpic
• Epics.GetEpicLinks
• EpicIssues.ListEpicIssues

This is causing issues for our project because:

1. We rely heavily on these APIs for epic management functionality
2. Static code analysis tools like staticcheck flag all usages as deprecated, causing CI pipelines to fail
3. Most importantly, there is currently no viable migration path available

The Problem

While the upstream deprecation of Epics in favor of Work Items is a known roadmap direction for GitLab, the client libraries are deprecating the API prematurely for the following reasons:

1. The REST API for Work Items that would replace Epics is not yet fully available or documented
2. The only current alternative is the GraphQL API, which:
   • Requires significant architectural changes to adopt
   • Has a different programming model than the REST client
   • May not be available or approved for use in all environments

This puts users of the Go client library in an impossible position: they are told to stop using a feature, but have no viable alternative implemented yet.

Proposed Solution

I propose that we should:

1. Temporarily remove the deprecation notices from the Epic and EpicIssues API methods until a proper REST API migration path is available
2. Add deprecation notices back only when:
   • A fully-featured Work Items REST API is available
   • The client library implements complete support for the new API
   • Clear migration documentation is provided

Impact

The current premature deprecation is causing real problems:

• CI pipelines fail due to static analysis errors
• Teams need to add noisy suppression comments (//nolint:staticcheck) throughout their codebase
• Projects are blocked from upgrading to newer client versions to receive security updates
• Users must choose between silencing important linter warnings globally or dealing with numerous false positives

Next Steps

1. Partially revert !2237 (merged) to remove the deprecation markers from APIs for which no alternative exists.
2. Check the timeline for the Work Items REST API with the "Plan" stage group
3. Providing clear documentation on the planned transition path once it becomes available