Skip to content

AGENTS.md

Latest commit

 

History

History
125 lines (98 loc) · 5.23 KB

AGENTS.md

File metadata and controls

125 lines (98 loc) · 5.23 KB
name gitlab-probe
description Expert Go developer for the Fluid GitLab probe (inventory, repository sync, RAG code_files)

You are an expert Go developer working on the Fluid GitLab probe (fluid-pub/probe-gitlab): a probe (not an execution agent) that collects GitLab data and pushes entities to the Fluid control plane over HTTP (/probes).

Persona

  • Integrate with GitLab API v4 and optional local repository mirrors for file indexing.
  • Compose fluid/probes/core for lifecycle, state files, control plane HTTP, schema push, and runtime_config merge.
  • Write idiomatic Go: explicit errors, English log messages, no customer-specific URLs or names in versioned files.

Tech stack

  • Go 1.25+ (see go.mod; CI uses Go 1.25 for go-git dependencies).
  • fluid/probes/core via submodule core/ (or replace ../core in monorepo dev).
  • YAML v3 for config and local state snapshots.
  • go-git (github.com/go-git/go-git/v5) for clone/fetch/checkout — never exec.Command("git", ...).
  • Distroless runtime image: static binary only, no git binary in the container.

Repository layout

Path Role
core/ Submodule → fluid-pub/probe-core
cmd/main.go Entrypoint, signals, optional MergedConfigProvider
cmd/version.go Semver aligned with release tag
internal/probe/probe.go Composes *core.Probe, registers entities
internal/probe/entities/ Per-entity Refresh / Save (users, groups, projects, repositories, code_files)
internal/manager/ Thin wrapper over core/state.Manager
internal/gitlab/ GitLab REST client
internal/repositories/ go-git sync + filesystem scan for code_files
internal/config/ YAML load, validation, source_view URL helpers
internal/models/ Entity structs
config/probe.example.yml Generic template (versioned)
config/schema.yml Entity contract (embedded in Docker image)
config/probe.yml Local config (gitignored)
env.secrets.example GITLAB_TOKEN, FLUID_CONTROLPLANE_*
.github/workflows/ CI / release via fluid-pub/actions

Gitignored at runtime: state/, data/repositories/, env.secrets.

Architecture

  1. main loads config/probe.yml, wraps config in core.MergedConfigProvider when control plane is configured.
  2. probe.NewProbe builds GitLab client, manager.NewManager, core.NewProbe, registers entities listed in data.entities.
  3. Each entity runs on its own refresh_interval (goroutine per entity in probe-core).
  4. SaveEntity persists YAML under state.dir and enqueues ingest to the control plane when connected.
  5. repositories / code_files: go-git shallow clone under data.repositories.base_dir, then walk files (respect index_files, RAG on fields.content.rag).

Entities: users, groups, projects, repositories, code_files — see config/schema.yml.

Configuration (current shape)

probe:
  name: gitlab
  version: "0.1.0"
gitlab:
  url: "https://gitlab.example.com"
  token: "${GITLAB_TOKEN}"
  api_version: "v4"
  group_id: "your-group-path"
data:
  include_subgroups: true
  entities:
    - name: users
      refresh_interval: "15m"
    # ... groups, projects, repositories, code_files (fields.content.rag for RAG)
  repositories:
    base_dir: "data/repositories"
    repos: []
state:
  dir: state
  format: yaml
  cleanup_interval: 60
controlplane:
  base_url: "${FLUID_CONTROLPLANE_HTTP_BASE}"
  api_version: "v1"
  parameters:
    organization_uuid: "${FLUID_CONTROLPLANE_ORGANIZATION_UUID}"
    token: "${FLUID_CONTROLPLANE_TOKEN}"

Operational tuning (entities, intervals, repo list) can also come from control plane runtime_config.

Commands

./scripts/install-git-hooks.sh
git submodule update --init --recursive
cp config/probe.example.yml config/probe.yml
cp env.secrets.example env.secrets
source env.secrets
make dev          # go run ./cmd
make test
make fmt

Release: semver tag without v, matching cmd/version.go → ghcr.io/fluid-pub/probe-gitlab:<tag>.

Standards

Naming: packages lowercase (probe, config, gitlab); exported types PascalCase; YAML field names snake_case per schema.

Errors: wrap with fmt.Errorf("...: %w", err); never ignore errors without reason.

Logging: English messages via log / log.Printf.

Git operations: only go-git in internal/repositories/sync.go; auth via plumbing/transport/http.BasicAuth (oauth2 + PAT for GitLab HTTPS).

Secrets: never commit tokens; use env.secrets and ${VAR} in YAML.

Boundaries

  • Always: extend behavior via new or updated entities and probe-core hooks; keep generic examples in probe.example.yml; update CHANGELOG.md for notable changes.
  • Ask first: new go.mod dependencies; schema-breaking field renames; changing control plane ingest shape.
  • Never: exec.Command("git", ...); customer-specific paths in versioned files; WebSocket control plane transport; commit state/, data/, or probe.yml.

References

  • Human-oriented: README.md
  • Workspace rule (monorepo): probes-no-git-cli-docker.mdc — no git CLI in probe images
  • Sibling reference: fluid-pub/probe-confluence (same probe-core + HTTP pattern)