## Summary `AuditEventDetails.Change` is typed as Go `string`, but the GitLab Audit Events REST API can return a **non-string** (object) value in `details.change` for some events. When that happens, `json.Unmarshal` fails and the entire batch decode errors out: ``` json: cannot unmarshal object into Go struct field AuditEventDetails.details.change of type string ``` In addition, some audit events emit a **plural `changes` array** (e.g. `group_share_with_group_link_updated`), which the SDK does not model at all — so that data is **silently dropped** on decode (no error, but the audit information is lost). ## Reproduction Using the SDK against an instance that has a `project_group_link_updated` audit event (created by editing a project's group-share role): ```go package main import ( "log" gitlab "gitlab.com/gitlab-org/api/client-go" ) func main() { git, err := gitlab.NewClient( "<TOKEN>", gitlab.WithBaseURL("https://<instance>/api/v4"), ) if err != nil { log.Fatalf("client: %v", err) } // Fails with: cannot unmarshal object into Go struct field // AuditEventDetails.details.change of type string _, _, err = git.AuditEvents.ListProjectAuditEvents(<project-id>, &gitlab.ListAuditEventsOptions{ ListOptions: gitlab.ListOptions{PerPage: 100}, }) if err != nil { log.Fatalf("fetching audit events: %v", err) } } ``` The API returns, for that event: ```json { "event_name": "project_group_link_updated", "details": { "change": { "access_level": { "from": "Reporter", "to": "Planner" } } } } ``` ## Why this happens The audit `details` payload is not a fixed shape — the fields returned depend on the action recorded (`doc/user/compliance/audit_event_schema.md` notes there is no formal schema). For most events `change` is a plain string, but a small number of events emit an object there, and others emit a plural `changes` array. The current struct assumes `change` is always a string and has no `changes` field. ## Proposed change In `audit_events.go` (`AuditEventDetails`): 1. Make the free-form fields tolerate non-string values by typing them as `json.RawMessage` (or `any`). This mirrors the existing precedent in the same struct, where `TargetID` is already typed `any` for the same reason: ```go type AuditEventDetails struct { // ... Change json.RawMessage `json:"change,omitempty"` From json.RawMessage `json:"from,omitempty"` To json.RawMessage `json:"to,omitempty"` // consider the same for: with, add, remove // ... } ``` `json.RawMessage` is preferable to `any` because it defers parsing — callers can then unmarshal the raw bytes into a `string` or a struct depending on the event. 2. Add a `Changes` (plural) field so array-style payloads are no longer silently dropped: ```go Changes []AuditEventChange `json:"changes,omitempty"` ``` where `AuditEventChange` is `{ Change string; From json.RawMessage; To json.RawMessage }`. ## Notes - This is a defensive/hardening change. The primary fix is a server-side alignment (`project_group_link_updated` should emit the conventional plural `changes` array instead of an object in the singular `change`), tracked separately in `gitlab-org/gitlab`. This SDK change keeps the client robust regardless of when the server-side fix ships, and handles historical/retained audit rows. - Related prior report: `gitlab-org/api/client-go#2141` (same reporter, adjacent SDK-typing theme). - Original customer report https://gitlab.zendesk.com/agent/tickets/728994. Customer unblocked the issue themselves with a local custom type treating `change` as `json.RawMessage`. ## Implementation plan *Added by [GitLab Duo Agent Platform 🤖](https://gitlab.com/components/agents-and-flows/quick-win-labeller)* 1. **Open `audit_events.go`** and locate the `AuditEventDetails` struct. 2. **Change the type of `Change`, `From`, and `To` fields** (and consider `With`, `Add`, `Remove`) from `string` to `json.RawMessage`. This follows the existing pattern used for `TargetID` in the same struct. 3. **Define a new `AuditEventChange` struct** to represent entries in the plural `changes` array: ```go type AuditEventChange struct { Change string `json:"change,omitempty"` From json.RawMessage `json:"from,omitempty"` To json.RawMessage `json:"to,omitempty"` } ``` 4. **Add a `Changes` field** to `AuditEventDetails`: ```go Changes []AuditEventChange `json:"changes,omitempty"` ``` 5. **Update any existing tests** in `audit_events_test.go` that assert on the old `string` type for `Change`/`From`/`To`, adjusting them to work with `json.RawMessage`. 6. **Add new test cases** covering: - An event where `change` is an object (e.g. `project_group_link_updated`) — verify no unmarshal error and the raw bytes are preserved. - An event with a `changes` array — verify the slice is populated correctly.