Add Work Items API support to replace deprecated Epic API #3442

Description of the problem, including code/CLI snippet

GitLab deprecated the Epic REST API in GitLab 17.0 and plans to remove it in API v5. GitLab 18.1 and later instruct users to use the Work Items API instead. GitLab explicitly describes this migration as a breaking change.

This python-gitlab module still exposes the legacy Epic REST API through objects defined in gitlab/v4/objects/epics.py, including, for example:

• GroupEpic
• GroupEpicIssue
• GroupEpicIssueManager
• GroupEpicManager

Applications using these objects therefore currently depend on GitLab's deprecated Epics REST API.

Support for GitLab's replacement Work Items API would provide python-gitlab users with a migration path before the legacy Epic REST API is removed.

Potentially affected code

At least:

• gitlab/v4/objects/epics.py: legacy Epic object definitions
• docs/gl_objects/epics.rst: Epic documentation
• tests/functional/api/test_epics.py: Epic functional tests

Other references to the legacy Epic APIs may also need to be reviewed.

Expected Behavior

python-gitlab should provide an API for working with epics through GitLab's supported Work Items API, allowing users to migrate away from GroupEpic and related legacy objects.

For example, an eventual interface could look similar to:

group = gl.groups.get(group_id)
epic = group.work_items.create({
    "title": "My Epic",
    "work_item_type": "epic",
})

# Exact API for establishing parent/child relationships is TBD.

My logic suggests that the exact Python interface should follow the capabilities and data model of GitLab's Work Items API rather than necessarily preserving the existing Epic API interface.

It would also be useful to document the migration path from the existing GroupEpic APIs to their Work Items equivalents.

Actual Behavior

The currently available interface uses GitLab's deprecated Epic REST API:

group = gl.groups.get(group_id)
epic = group.epics.create({"title": "My Epic"})
epic_issue = epic.issues.create({"issue_id": 4})

This works with the legacy REST API today, but GitLab has deprecated that API and recommends the Work Items API for GitLab 18.1 and later.

There does not appear to be an equivalent high-level python-gitlab Work Items interface that users can migrate this code to.

Specifications

• python-gitlab version: 8.5.0
• Gitlab server version (or gitlab.com): 19.3.1 or gitlab.com
• GitLab API currently used by python-gitlab version: 4