<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/engineering/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=65271576&issueIid=2301) </details> <!--IssueSummary end--> ## Summary !3063 carried fixes for places where this library and the GitLab API disagree. Where the right fix would remove an exported name, change a method's signature or change a field's type, it did the half that keeps v3 source compatible and left the rest for 4.0. It was closed on 2026-10-21 without merging, and its fixes go out again as small merge requests, one topic each, that keep the same split. The one exception is the pipeline cancellation role: after the review, !3063 gave the two `CIRestrictPipelineCancellationRole` fields a type of their own. That change goes out again in a merge request of its own, and if it is dropped there, it comes back to this list. One change of behavior, what a nil options pointer sends, is made opt-in instead, in !3065, which the review split out of !3063, and its default follows in 4.0. This issue tracks the rest, as the [review of !3063](https://gitlab.com/gitlab-org/api/client-go/-/merge_requests/3063#note_3920279951) asked. ## Why deferred Each change below removes an exported name, changes a method's signature, changes a field's type or changes what a request sends by default, so it breaks existing callers and has to wait for a major version. ## What 4.0 does ### 1. Methods that return a type their endpoint does not send Each gets a `V2` sibling with the right return type, and the original is deprecated in its favour. In 4.0 the original name takes the `V2` signature and the `V2` method is removed. | Deprecated method | Returns today | `V2` returns | |---|---|---| | `DeploymentsService.ApproveOrRejectProjectDeployment` | nothing (the approval is discarded) | `*DeploymentApproval` | | `GeoSitesService.RepairGeoSite` | `*GeoSite` | `*GeoSiteStatus` | | `MergeRequestsService.CreateMergeRequestPipeline` | `*PipelineInfo` | `*Pipeline` | | `ProjectsService.CreateProjectForkRelation` | `*ProjectForkRelation` | `*Project` | | `ProjectsService.ShareProjectWithGroup` | nothing (the link is discarded) | `*ProjectGroupLink` | | `UsersService.CreateServiceAccountUser` | `*User` | `*ServiceAccount` | `ProjectForkRelation`, which no GitLab entity exposes, is removed with them. `CreateMergeRequestPipelineV2` also takes the route's `async` option. ### 2. Methods that take no options although their routes do In 4.0 the base method takes the options struct. The `WithOptions` sibling stays, deprecated, and is removed in 5.0: - `WorkItemsService.GetWorkItem` and `GetWorkItemWithOptions` (from !3063) - `ProjectMembersService.DeleteProjectMember` and `DeleteProjectMemberWithOptions` (from !3063) - `JobsService.CancelJob`, `DraftNotesService.PublishAllDraftNotes` and `JobsService.GetJobArtifacts`, whose siblings already follow the same pattern and would follow the same schedule The three siblings already on `main` carry `Deprecated` notes that tie them to 4.0, and the two from !3063 carried the same. This schedule makes those notes wrong: each should either say 5.0, or come out until 4.0 deprecates the sibling. ### 3. A field typed narrower than what GitLab sends `GeoSiteStatus.Namespaces` is a `[]string` where GitLab sends namespace objects. The fix from !3063 keeps the full paths there and puts the objects in `NamespaceDetails`. In 4.0 the field takes the object type and `NamespaceDetails` is removed. `Epic.Labels` needs nothing here: the fix from !3063 keeps the names there and puts the objects in `LabelDetails`, which is the shape `Issue` and `MergeRequest` already have. ### 4. Fields current GitLab does not send, and option fields no current route declares !3063 deprecated each of these with a note saying why, and what to read instead where GitLab sends the value under another name, except the two `Skype` options, which !3113 deprecated on `main`. The notes from !3063 go out again with the small merge requests, and in 4.0 the fields are removed: - `AuditEvent.EventType` - `ContributionEvent.Title`, `ProjectEvent.Title`, `ProjectEvent.Data` - `Epic.UserNotesCount` - `Group.DuoAvailability` - `Integration.GroupMentionEvents`, `Integration.GroupConfidentialMentionEvents` - `Issue.IssueLinkID`, which GitLab sends only on the issue links route, decoded there into `IssueRelation` - `LicenseTemplate.Featured` - `Note.Attachment`, `Note.ExpiresAt`, `Note.FileName`, `Note.Title`, `NoteAuthor.Email`, `NoteResolvedBy.Email` - `PendingInvite.ID` - `PipelineTrigger.DeletedAt` - `Project.BuildCoverageRegex`, `Project.CIOptInJWT`, `Project.OperationsAccessLevel` - `CreateProjectOptions.BuildCoverageRegex`, `CreateProjectOptions.OperationsAccessLevel`, `EditProjectOptions.BuildCoverageRegex`, `EditProjectOptions.OperationsAccessLevel` - `ReleaseLink.External`, which GitLab removed from the release link API in 16.0 - `User.CanCreateOrganization`, `User.ExternUID`, `User.Provider`, `User.Skype` - `CreateUserOptions.Skype`, `ModifyUserOptions.Skype` - `WeightEvent.ResourceID`, `WeightEvent.ResourceType`, `WeightEvent.State` Older releases, all out of maintenance, did send some of these, for example `Project.BuildCoverageRegex` up to 15.2, `Project.CIOptInJWT` from 15.2 to 15.11, `Project.OperationsAccessLevel` and `ReleaseLink.External` up to 15.11, `Note.Attachment` up to 17.10, and `User.Skype` up to 18.1. ### 5. Structs that decode more than one entity `Group`, `Project` and `Issue` each decode a narrow Grape entity and one or more wider ones that inherit it: - `BasicGroupDetails` on the job token groups allowlist, `Entities::Group` on the group listings, and `GroupDetail` on the routes that answer with one group - `BasicProjectDetails` on a project listing with `simple` or without authentication, `ProjectDetails` on a single project read without authentication, and `Project` or an entity inheriting it otherwise - `IssueBasic` where other APIs render an issue (a milestone's issues, the issues a merge request closes, search), and `Issue` on the issues API's own routes `User` decodes six. !3063 put the new fields on the one struct, with comments saying when GitLab sends each, and the merge requests that carry them again do the same. In 4.0 a route that answers with a narrower entity returns a struct shaped like it. `BasicUser` already has the shape of `UserBasic`, but `BasicProject` has the shape of the smaller `ProjectIdentity` rather than `BasicProjectDetails`, and no struct has the shape of `Entities::Group` or `IssueBasic`, so `Project`, `Group` and `Issue` each still need another struct. ### 6. A nil options pointer sends `null` by default A nil `*Options` held in an `any` is not `nil`, so a POST, PUT or PATCH request given one sends the JSON literal `null` as its body, and a request with any other method has a query already on its URL replaced with an empty one. `JobsService.CancelJob` and `DraftNotesService.PublishAllDraftNotes` do this on their own, through their `WithOptions` siblings. !3065 adds the client option `WithNilOptionsOmitted()`, off by default, which makes such a pointer mean no options. As the [review of !3063](https://gitlab.com/gitlab-org/api/client-go/-/merge_requests/3063#note_3924608467) asked, 4.0 makes that the default, where the option has no effect, and 5.0 removes the option. ## Not part of this `GetMergeRequestChanges` and `ChangeApprovalConfiguration` return `*MergeRequest` for endpoints that answer with `MergeRequestChanges` and `ApprovalState`. GitLab deprecated both endpoints and both methods are already deprecated here. They stay as they are: deprecated routes live a long time in GitLab, and callers may target older instances. ## Next steps - Add this issue to the 4.0 milestone once there is one. - Land each item in the 4.0 release branch, together with the removal of the deprecation notes it retires. Related: !3063, !3065