Download session artifacts for external agent sessions
What does this MR do and why?
The "Download Session Artifacts" button on the AI audit report session drawer now works for external agent sessions (for example Claude Code via glab). Before, only GitLab Duo sessions got a download link. External sessions had a null downloadPath on the AiGovernanceSession GraphQL type.
What changes:
- New routes
GET /groups/:group/-/security/agent_artifacts/:id/download_sessionandGET /:project/-/security/agent_artifacts/:id/download_session. Here:idis the AI governance session ID, not the Duo workflow ID. - New
Ai::Governance::SessionArtifactExportService. It builds the JSON for an external session. AiGovernanceSession.downloadPathnow returns the new path for external sessions. It is the project path when the session has a project, and the group path otherwise. GraphQL docs are regenerated.- The frontend needs no change.
The new routes use the same controllers and checks as the existing Duo download: license, read_agent_artifacts permission and the agent_artifacts_page flag. They also need the ai_governance_sessions_api flag on the root group, and ClickHouse (the analytics database) must be enabled. Otherwise the route returns 404.
How the session and audit events are read
- The session is read from ClickHouse only (
siphon_ai_governance_sessions), through the existingAi::Governance::Sessions::ClickHouseFinder. This is the same way the sessions GraphQL list reads it. - The finder limits the lookup to the requested group (with its subgroups and projects) or to the requested project. A session from elsewhere gives 404.
- GitLab Duo session IDs also give 404 on this route, because the finder only returns external sources. Duo sessions keep using the workflow route and its private-messaging check.
- There is no Postgres lookup. When ClickHouse is off, external sessions have a null
downloadPathand the route returns 404. The issue mentions a ClickHouse fallback for purged Postgres rows. Reading ClickHouse only makes that moot. - The new service subclasses
Ai::DuoWorkflows::SessionArtifactExportService, so theaudit_eventspart is serialized by the same code as the Duo download. - Audit events come from
AuditEvents::AiAuditEvents::ClickHouseFinderbyai_governance_session_id. The lookup starts 1 day before the session start, the same clock-skew window as the GraphQLauditEventsfield. - Like the Duo download, there is no cap on the number of audit events.
Differences from the Duo JSON
In the session object:
flow_typeis used instead ofworkflow_definition.sourceandsession_started_atare added.idis the AI governance session ID.created_at,updated_at,projectand the wholeaudit_eventsarray have the same shape as the Duo download.
Sample external session JSON:
{
"session": {
"id": 11,
"source": "claude_code_glab",
"flow_type": "claude_code",
"session_started_at": "2026-10-06T09:12:03Z",
"created_at": "2026-10-06T09:12:03Z",
"updated_at": "2026-10-06T09:40:11Z",
"project": {
"id": 125,
"name": "secret_fp_5",
"full_path": "gitlab-duo/secret_fp_5"
}
},
"audit_events": [
{
"id": "3f9c2b8e-1d4a-4c55-9a7e-2b1f0c6d8e71",
"event_name": "run_tool",
"author_id": 1,
"ip_address": null,
"created_at": "2026-10-06T09:13:20Z",
"details": {}
}
]
}References
Closes https://gitlab.com/gitlab-org/gitlab/-/work_items/632126
- Epic: https://gitlab.com/groups/gitlab-org/-/work_items/21540
- Frontend MR: !259181 (merged)
- Sessions GraphQL MR: !257545 (merged)
- Audit events finder by session ID: !258505 (merged)
- Flag rollout: https://gitlab.com/gitlab-org/gitlab/-/work_items/630933
Screenshots or screen recordings
No UI change in this MR. The frontend already shows the button when downloadPath is set.
How to set up and validate locally
- Enable ClickHouse in GDK. In the Rails console, run
Feature.enable(:ai_governance_sessions_api)andFeature.enable(:agent_artifacts_page). - Make sure there is an external session row in ClickHouse
siphon_ai_governance_sessions(for example from Claude Code via glab). - As a group owner, go to Settings > GitLab Duo > Governance > Audit events. Open the external session drawer and click "Download Session Artifacts".
- Check the downloaded JSON matches the sample above.
Alternative: query group { aiGovernanceSessions { nodes { downloadPath } } } in GraphQL and open the returned path.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.