Entities

Entities are the fundamental building blocks of your Devgraph ontology. Each entity represents a resource in your infrastructure.

What is an Entity?

An entity is a structured representation of a real-world resource like:

• A GitHub repository
• An Argo application
• A Docker image
• A team or person
• A deployment or service

Entities are similar to Kubernetes resources—they follow a consistent structure with metadata, specifications, and relationships.

Entity Structure

Every entity has this structure:

apiVersion: github.com/v1        # Entity type identifier
kind: Repository                  # Resource kind
metadata:
  name: my-service               # Human-readable name
  namespace: default             # Organizational namespace
  uid: 550e8400-e29b-41d4-a716-446655440000  # Unique ID
  labels:                        # Key-value labels
    language: python
    team: platform
  annotations:                   # Arbitrary metadata
    description: "User authentication service"
spec:                            # Entity-specific data
  url: https://github.com/org/my-service
  default_branch: main
  topics: [api, auth]

API Version and Kind

The apiVersion and kind together define the entity type:

• apiVersion: Provider domain and version (e.g., github.com/v1)
• kind: Resource type (e.g., Repository, Team, Application)

Examples:

• github.com/v1/Repository - GitHub repository
• argo.io/v1/Application - Argo CD application
• docker.io/v1/Image - Docker image
• meta.devgraph.ai/v1/Team - Team or organization

Metadata

All entities share standard metadata fields:

Field	Description	Example
name	Human-readable identifier	user-service
namespace	Organizational namespace	default, production
uid	Unique identifier (UUID)	550e8400-...
labels	Structured key-value pairs	{team: platform, env: prod}
annotations	Arbitrary metadata	{description: "..."}

Labels vs Annotations

Labels are for:

• Filtering and selection
• Grouping entities
• Short, structured data

Annotations are for:

• Longer descriptions
• External system metadata
• Unstructured information

Spec

The spec field contains entity-specific data. Its structure varies by entity type.

GitHub Repository spec:

spec:
  url: https://github.com/org/repo
  default_branch: main
  language: python
  private: false
  topics: [api, microservice]

Argo Application spec:

spec:
  server: https://kubernetes.default.svc
  namespace: production
  source:
    repoURL: https://github.com/org/repo
    path: k8s/manifests
  health:
    status: Healthy

Entity Types

Devgraph includes entity types for multiple providers:

GitHub Entities

• github.com/v1/Repository - Git repositories
• github.com/v1/Team - Organization teams
• github.com/v1/PullRequest - Pull requests

GitLab Entities

• gitlab.com/v1/Project - GitLab projects
• gitlab.com/v1/Group - GitLab groups
• gitlab.com/v1/Pipeline - CI/CD pipelines

Argo Entities

• argo.io/v1/Application - Argo CD applications
• argo.io/v1/Project - Argo projects

Docker Entities

• docker.io/v1/Image - Container images
• docker.io/v1/Repository - Image repositories
• docker.io/v1/Registry - Container registries

Meta Entities

• meta.devgraph.ai/v1/Team - Teams and organizations
• meta.devgraph.ai/v1/Person - People
• meta.devgraph.ai/v1/Project - Logical projects

Querying Entities

By Entity Type

Search for all entities of a specific type:

curl http://localhost:8000/api/entities?kind=Repository

By Name

Find entities by name:

curl http://localhost:8000/api/entities?name=my-service

By Labels (Field Selectors)

Filter using label selectors:

# Single label
curl "http://localhost:8000/api/entities?field_selector=metadata.labels.team=platform"

# Multiple labels
curl "http://localhost:8000/api/entities?field_selector=metadata.labels.team=platform,metadata.labels.env=prod"

# Nested fields
curl "http://localhost:8000/api/entities?field_selector=spec.language=python"

By UID

Get a specific entity:

curl http://localhost:8000/api/entities/{uid}

Entity Lifecycle

Creation

Entities are created during discovery:

1. Provider scans external system (GitHub, Argo, etc.)
2. Resources are converted to entity format
3. Entities are stored in the graph database

Updates

Entities are updated on subsequent discovery runs:

• Existing entities are identified by name and namespace
• Specs are updated with new data
• Metadata timestamps are refreshed

Reconciliation

Devgraph uses reconciliation to keep entities current:

• Entities track their source system
• Discovery runs update existing entities
• Stale entities can be detected and removed

Best Practices

Naming

• Use lowercase, hyphenated names: user-service, payment-api
• Keep names consistent across systems
• Use descriptive names that indicate purpose

Labels

• Use labels for filtering: team, environment, language
• Keep label values short and consistent
• Document your labeling conventions

Namespaces

• Use namespaces to organize entities: default, production, team-a
• Match namespaces to your organizational structure
• Consider namespace-per-environment or namespace-per-team

Annotations

• Use annotations for documentation
• Store external IDs in annotations
• Add discovery metadata (timestamps, sources)

Example: Complete Entity

Here's a real-world example of a GitHub repository entity:

apiVersion: github.com/v1
kind: Repository
metadata:
  name: user-authentication-service
  namespace: default
  uid: 7c4a8d09-3b42-4f8a-b9d4-5e6f7a8b9c0d
  labels:
    team: platform
    language: python
    visibility: private
    environment: production
  annotations:
    description: "Microservice handling user authentication and authorization"
    github.com/created-at: "2023-01-15T10:30:00Z"
    github.com/stars: "42"
spec:
  url: https://github.com/myorg/user-authentication-service
  default_branch: main
  language: python
  private: true
  archived: false
  topics:
    - authentication
    - microservice
    - api
  homepage: https://docs.myorg.com/services/auth

Next Steps

• Configure molecules to discover entities
• Learn about available integrations