GitLabgitlab-org

cli

main
ply9 git calls231 ms100 KiB6 cachedprotocol v2
231 lines6.7 KiBRaw
1// Package gaig provides shared utilities for GitLab AI Agent Governance (GAIG).
2// It handles project ID resolution, machine fingerprint generation, agent identity
3// registration, and local caching.
4package gaig
6import (
7 "context"
8 "crypto/sha256"
9 "encoding/hex"
10 "encoding/json"
11 "fmt"
12 "net/http"
13 "os"
14 "path/filepath"
15 "strings"
16 "time"
18 "github.com/denisbrodbeck/machineid"
20 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
22 "gitlab.com/gitlab-org/cli/internal/api"
23 "gitlab.com/gitlab-org/cli/internal/config"
24 "gitlab.com/gitlab-org/cli/internal/dbg"
25 "gitlab.com/gitlab-org/cli/internal/glrepo"
28const (
29 // appKey is used to scope the machine fingerprint to glab GAIG.
30 // Changing this will invalidate all cached identities.
31 appKey = "glab-gaig-v1"
33 // identityCacheTTL is how long a cached identity is considered valid.
34 // A 24-hour TTL means a revoked identity may remain usable locally for up
35 // to 24 hours after server-side revocation.
36 identityCacheTTL = 24 * time.Hour
39// Identity represents a cached agent identity returned from the GitLab API.
40type Identity struct {
41 ID int `json:"id"`
42 AgentType string `json:"agent_type"`
43 RevokedAt *string `json:"revoked_at"`
44 CreatedAt time.Time `json:"created_at"`
45 CachedAt time.Time `json:"cached_at"`
48// MachineFingerprint returns the GAIG-scoped SHA-256 hash of the machine ID.
49// The raw machine ID is never transmitted -- only this hash.
50func MachineFingerprint() (string, error) {
51 id, err := machineid.ProtectedID(appKey)
52 if err != nil {
53 // Fallback to hostname when machine-id is unavailable (e.g. CI containers)
54 hostname, herr := os.Hostname()
55 if herr != nil {
56 return "", fmt.Errorf("could not generate machine fingerprint: %w", err)
57 }
58 id = appKey + ":" + hostname
59 }
60 h := sha256.Sum256([]byte(id))
61 return hex.EncodeToString(h[:]), nil
64// ResolveProject resolves the GitLab project from the git remote of the
65// current directory. Returns the project and the API client scoped to its host.
66func ResolveProject(
67 baseRepo func() (glrepo.Interface, error),
68 apiClient func(repoHost string) (*api.Client, error),
69) (*gitlab.Project, *api.Client, error) {
70 repo, err := baseRepo()
71 if err != nil {
72 return nil, nil, fmt.Errorf("could not resolve git remote: %w", err)
73 }
75 client, err := apiClient(repo.RepoHost())
76 if err != nil {
77 return nil, nil, fmt.Errorf("could not create API client: %w", err)
78 }
80 project, err := api.GetProject(client.Lab(), repo.FullName())
81 if err != nil {
82 return nil, nil, fmt.Errorf("could not fetch project %s: %w", repo.FullName(), err)
83 }
85 return project, client, nil
88// MaxEventAge is the age of the oldest activity glab uploads. It stays inside
89// the 90 days GitLab accepts, because one older event makes GitLab reject the
90// whole batch.
91const MaxEventAge = 89 * 24 * time.Hour
93// StateDir holds glab's local records of agent sessions: their sync cursors,
94// cached agent identities, the agent lists, when the agents were set up, and
95// the fallback job's status.
96func StateDir() string {
97 return filepath.Join(config.ConfigDir(), "gaig")
100// identityCachePath returns the path to the cached identity file for a given
101// project ID and agent type.
102func identityCachePath(projectID int64, agentType string) (string, error) {
103 if strings.ContainsAny(agentType, "/\\.") {
104 return "", fmt.Errorf("invalid agent type: %q", agentType)
105 }
107 filename := fmt.Sprintf("%d_%s.json", projectID, agentType)
108 return filepath.Join(StateDir(), "identities", filename), nil
111// LoadCachedIdentity loads a cached identity for the given project and agent type.
112// Returns nil if no valid cache entry exists.
113func LoadCachedIdentity(projectID int64, agentType string) (*Identity, error) {
114 path, err := identityCachePath(projectID, agentType)
115 if err != nil {
116 return nil, err
117 }
119 data, err := os.ReadFile(path)
120 if err != nil {
121 if os.IsNotExist(err) {
122 return nil, nil
123 }
124 return nil, fmt.Errorf("could not read identity cache: %w", err)
125 }
127 var identity Identity
128 if err := json.Unmarshal(data, &identity); err != nil {
129 return nil, fmt.Errorf("could not parse identity cache: %w", err)
130 }
132 // Check TTL
133 if time.Since(identity.CachedAt) > identityCacheTTL {
134 return nil, nil
135 }
137 // Check not revoked
138 if identity.RevokedAt != nil {
139 return nil, nil
140 }
142 return &identity, nil
145// SaveCachedIdentity writes an identity to the local cache.
146func SaveCachedIdentity(projectID int64, agentType string, identity *Identity) error {
147 path, err := identityCachePath(projectID, agentType)
148 if err != nil {
149 return err
150 }
152 if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
153 return fmt.Errorf("could not create cache directory: %w", err)
154 }
156 identity.CachedAt = time.Now()
158 data, err := json.MarshalIndent(identity, "", " ") //nolint:forbidigo // serializing to disk, not stdout
159 if err != nil {
160 return fmt.Errorf("could not serialise identity: %w", err)
161 }
163 return os.WriteFile(path, data, 0o600)
166// RegisterIdentity registers or loads a cached agent identity for the given project.
167// It returns (identity, nil) on success, (nil, err) on registration failure,
168// and (identity, err) when registration succeeds but the local cache write fails.
169func RegisterIdentity(
170 ctx context.Context,
171 client *api.Client,
172 projectID int64,
173 agentType string,
174) (*Identity, error) {
175 fingerprint, err := MachineFingerprint()
176 if err != nil {
177 return nil, err
178 }
180 // Attempt to load from cache -- silently fall through to API on any error
181 if cached, err := LoadCachedIdentity(projectID, agentType); err != nil {
182 dbg.Debugf("could not load cached identity: %v", err)
183 } else if cached != nil {
184 return cached, nil
185 }
187 type registerRequest struct {
188 AgentType string `json:"agent_type"`
189 MachineFingerprint string `json:"machine_fingerprint"`
190 }
192 type registerResponse struct {
193 ID int `json:"id"`
194 AgentType string `json:"agent_type"`
195 RevokedAt *string `json:"revoked_at"`
196 }
198 reqBody := registerRequest{
199 AgentType: agentType,
200 MachineFingerprint: fingerprint,
201 }
203 req, err := client.Lab().NewRequest(
204 http.MethodPost,
205 fmt.Sprintf("projects/%d/ai_agent/identities", projectID),
206 reqBody,
207 []gitlab.RequestOptionFunc{gitlab.WithContext(ctx), api.WithSafeRetries()},
208 )
209 if err != nil {
210 return nil, fmt.Errorf("could not create registration request: %w", err)
211 }
213 var resp registerResponse
214 _, err = client.Lab().Do(req, &resp)
215 if err != nil {
216 return nil, fmt.Errorf("could not register agent identity: %w", err)
217 }
219 identity := &Identity{
220 ID: resp.ID,
221 AgentType: resp.AgentType,
222 RevokedAt: resp.RevokedAt,
223 }
225 // Cache the result
226 if err := SaveCachedIdentity(projectID, agentType, identity); err != nil {
227 return identity, fmt.Errorf("could not cache identity: %w", err)
228 }
230 return identity, nil
Diagnostics9 git calls · 231 ms
CallStatusSizeTime0231 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:02001.8 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=1857
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=tree:0
git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1857
git.pkt.payload.max=1830
git.sideband.band1.bytes=1830
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1830
git.pack.trailer=fb03183b7909876778f740d196d7516811003517
Open pack map
fetchtree:0200261 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=261
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=3bb9946301aa8c0dc8d202b83bc9f84bf0400f6d
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=261
git.pkt.payload.max=234
git.sideband.band1.bytes=234
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=234
git.pack.trailer=e0a52f164f79506da6b0dcc275ed62911f5383bf
Open pack map
fetchtree:0200273 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=273
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=5fa160737ad30857ff606d64de1d596bb211ac3d
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=273
git.pkt.payload.max=246
git.sideband.band1.bytes=246
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=246
git.pack.trailer=06dd39b7545811625e04a7645a0a64c9a62c99c6
Open pack map
fetchtree:0200309 B · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=212
git.response.bytes=309
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=2684df6e0595b3410adbf16cd3f2a569566592ee
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=309
git.pkt.payload.max=282
git.sideband.band1.bytes=282
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=282
git.pack.trailer=f8a1f8ce88543c60887eeed57f3d06083ddd00c6
Open pack map
fetch2002.4 KiB212 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2481
git.response.cache=MISS
git.response.duration_ms=212
git.fetch.wants=f1dc3685e2d7a902a2ade107c3ff8232131f8f10
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2481
git.pkt.payload.max=2454
git.sideband.band1.bytes=2454
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e328e76ab74628
Request
a2028b91…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format