Add a GraphQL field to list external agent identities

What does this MR do and why?

The AI governance dashboard needs a "Connected agents" tab that lists each external agent connected through glab: one row per ai_agent_identities record. See https://gitlab.com/gitlab-org/gitlab/-/work_items/633495. This adds the backend for it, an aiAgentIdentities field on Group and Project.

Stacked on !261976 (merged), which adds last_synced_at. I'll retarget to master once that merges.

Each node has:

Field Notes
agentType CLAUDE_CODE, OPENCODE, CURSOR or CODEX. There's no agent name column, so the frontend maps this to a display name.
user, project Who connected it, and where
createdAt First connected
lastSyncedAt Last active. Null until the identity syncs after !261976 (merged) is deployed.
revokedAt Set by glab govern disable
status ACTIVE (synced in the last 30 days, or registered in the last 30 days and not synced yet), INACTIVE, or REVOKED
sessionCount Batched, one query per page. Counts up to 1,000, plus one to show there are more, like Ci::Runner.jobCount.
  • On a group, it lists identities in the group's projects and its subgroups' projects. On a project, just that project.
  • Filters: agentTypes, userId, status. Sorted by lastSyncedAt descending, nulls last, then ID.
  • Same access as aiGovernanceSessions: the parent field requires read_agent_artifacts, and it returns nothing when ai_governance_sessions_api is disabled. Granular tokens are checked on the parent too, so a token with read_group or read_project on it can read this, the same as aiGovernanceSessions today.
  • Revoked identities are listed with status REVOKED rather than hidden, so the dashboard can show them as disconnected. The frontend can filter them out.

Database

The group query scopes identities to the group's projects and sorts by last_synced_at DESC NULLS LAST, id DESC. There's no index for that order, so it's a top-N sort over the group's identities. The table has one row per user, project, agent type and machine, so I didn't add one. Local plan (tiny data, so it mainly shows the access path):

Limit
  ->  Sort
        Sort Key: ai_agent_identities.last_synced_at DESC NULLS LAST, ai_agent_identities.id DESC
        ->  Nested Loop
              ->  HashAggregate
                    Group Key: projects.id
                    ->  Nested Loop
                          ->  Index Scan using index_namespaces_on_traversal_ids_for_groups_btree on namespaces
                          ->  Index Only Scan using index_projects_on_namespace_id_and_id on projects
              ->  Index Scan using idx_ai_agent_identities_on_project_id on ai_agent_identities
                    Filter: ((revoked_at IS NULL) AND (COALESCE(last_synced_at, created_at) >= ...))

Group query, with the status: ACTIVE and agentTypes filters, first page:

SELECT "ai_agent_identities".* FROM "ai_agent_identities"
WHERE "ai_agent_identities"."project_id" IN (
  SELECT "projects"."id" FROM "projects" WHERE "projects"."namespace_id" IN (
    SELECT "namespaces"."id" FROM "namespaces"
    WHERE "namespaces"."type" = 'Group' AND (traversal_ids @> ('{22}'))))
  AND "ai_agent_identities"."agent_type" = 'claude-code'
  AND "ai_agent_identities"."revoked_at" IS NULL
  AND COALESCE("ai_agent_identities"."last_synced_at", "ai_agent_identities"."created_at") >= '2026-09-23 01:28:57.231940'
ORDER BY "ai_agent_identities"."last_synced_at" DESC NULLS LAST, "ai_agent_identities"."id" DESC
LIMIT 101

Project query, first page:

SELECT "ai_agent_identities".* FROM "ai_agent_identities"
WHERE "ai_agent_identities"."project_id" = 1
ORDER BY "ai_agent_identities"."last_synced_at" DESC NULLS LAST, "ai_agent_identities"."id" DESC
LIMIT 101
Limit
  ->  Sort
        Sort Key: last_synced_at DESC NULLS LAST, id DESC
        ->  Index Scan using idx_ai_agent_identities_on_project_id on ai_agent_identities
              Index Cond: (project_id = 1)

sessionCount, once for each page:

SELECT "ai_agent_identities"."id", COUNT(*) FROM "ai_agent_identities"
JOIN LATERAL (
  SELECT 1 FROM "ai_governance_sessions"
  WHERE "ai_governance_sessions"."agent_identity_id" = "ai_agent_identities"."id"
  LIMIT 1001
) limited_sessions ON true
WHERE "ai_agent_identities"."id" IN (1, 2, 3)
GROUP BY "ai_agent_identities"."id"
GroupAggregate  (cost=0.28..10.73 rows=3 width=16) (actual time=0.024..0.025 rows=0 loops=1)
  Group Key: ai_agent_identities.id
  ->  Nested Loop  (cost=0.28..10.69 rows=3 width=8)
        ->  Index Only Scan using ai_agent_identities_pkey on ai_agent_identities
              Index Cond: (id = ANY ('{1,2,3}'::bigint[]))
        ->  Limit  (cost=0.12..2.14 rows=1 width=4)
              ->  Index Only Scan using index_ai_governance_sessions_on_agent_identity_id on ai_governance_sessions
                    Index Cond: (agent_identity_id = ai_agent_identities.id)

sessionCount uses the existing partial index on ai_governance_sessions.agent_identity_id and reads at most 1,001 index entries for each identity on the page. It counts PostgreSQL rows, while aiGovernanceSessions reads ClickHouse, so the two can differ briefly while Siphon catches up.

References

https://gitlab.com/gitlab-org/gitlab/-/work_items/633495

How to set up and validate locally

query {
  group(fullPath: "my-group") {
    aiAgentIdentities(status: ACTIVE) {
      nodes { agentType user { username } project { fullPath } createdAt lastSyncedAt status sessionCount }
    }
  }
}
bundle exec rspec ee/spec/requests/api/graphql/ai/external_agents/agent_identities_spec.rb ee/spec/finders/ai/external_agents/agent_identities_finder_spec.rb ee/spec/models/ai/external_agents/agent_identity_spec.rb

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist.

Edited by Jean van der Walt

Merge request reports

Loading
Loading