GitLab

Discovery

Discover and manage GitLab projects and hosting services in your Devgraph knowledge graph.

Overview

The GitLab molecule connects to GitLab's API to automatically discover projects within your groups. It creates entities for projects and the GitLab hosting service itself, along with relationships between them.

Key Features:

• Discover projects from multiple groups
• Filter projects by name patterns (regex)
• Support for both GitLab.com and self-hosted instances
• Read .devgraph.yaml files from projects for additional entities
• Track project metadata (languages, description, etc.)

Quick Start

providers:
  - name: gitlab
    type: gitlab
    every: 300  # Reconcile every 5 minutes
    config:
      namespace: default
      token: ${GITLAB_TOKEN}
      selectors:
        - group: mygroup
          project_name: ".*"  # All projects

Configuration

Basic Configuration

providers:
  - name: gitlab-prod
    type: gitlab
    every: 300
    config:
      namespace: production
      base_url: https://gitlab.com
      api_url: https://gitlab.com/api/v4
      token: ${GITLAB_TOKEN}
      selectors:
        - group: mycompany
          project_name: "backend-.*"
          graph_files:
            - .devgraph.yaml
        - group: mycompany
          project_name: "frontend-.*"

Self-Hosted GitLab

providers:
  - name: gitlab-selfhosted
    type: gitlab
    every: 300
    config:
      namespace: default
      base_url: https://gitlab.mycompany.com
      api_url: https://gitlab.mycompany.com/api/v4
      token: ${GITLAB_TOKEN}
      selectors:
        - group: engineering

Configuration Options

Option	Type	Required	Default	Description
namespace	string	No	default	Namespace for created entities
base_url	string	No	https://gitlab.com	GitLab web interface URL
api_url	string	No	https://gitlab.com/api/v4	GitLab API endpoint
token	string	Yes	-	Personal Access Token or Project Access Token
selectors	list	Yes	[]	Project selectors

Selector Options

Each selector specifies which projects to discover:

Option	Type	Required	Default	Description
group	string	Yes	-	GitLab group path to scan
project_name	string	No	.*	Regex pattern for project names
graph_files	list	No	[.devgraph.yaml]	Files to parse for entities

Authentication

Personal Access Token (Recommended)

1. Go to GitLab → Settings → Access Tokens (or User Settings → Access Tokens)
2. Click "Add new token"
3. Set token name (e.g., "Devgraph Integration")
4. Select scopes:
   • read_api - For reading project data
   • read_repository - To read repository files
5. Click "Create personal access token"
6. Copy token and set in config:

token: ${GITLAB_TOKEN}

Set environment variable:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"

Project Access Token

For project-specific access:

1. Go to Project → Settings → Access Tokens
2. Create token with read_api and read_repository scopes
3. Use in configuration

Group Access Token

For group-level access (GitLab Premium+):

1. Go to Group → Settings → Access Tokens
2. Create token with appropriate scopes
3. Use in configuration

Entities Created

GitlabHostingService

Represents the GitLab platform instance.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: GitlabHostingService
metadata:
  name: gitlab
  namespace: default
  labels:
    organization: gitlab
spec:
  api_url: https://gitlab.com/api/v4

One hosting service entity is created per provider.

GitlabProject

Represents a GitLab project (repository).

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: GitlabProject
metadata:
  name: my-service
  namespace: default
  labels:
    group: mygroup
spec:
  group: mygroup
  name: my-service
  url: https://gitlab.com/mygroup/my-service
  description: "My awesome service"
  languages:
    Python: 15234
    JavaScript: 8432
  default_branch: main
  visibility: private

Fields:

• group: Group or subgroup that owns the project
• name: Project name
• url: Web URL to the project
• description: Project description
• languages: Map of language names to bytes of code
• default_branch: Default branch name (usually main or master)
• visibility: Project visibility (private, internal, public)

Relationships

HOSTED_BY

Every project is linked to the hosting service.

GitlabProject --HOSTED_BY--> GitlabHostingService

Example:

mygroup/backend-api --HOSTED_BY--> gitlab

Graph Files

The GitLab molecule can read .devgraph.yaml files from projects to discover additional entities and relationships. This allows projects to declare their own metadata.

Example .devgraph.yaml:

entities:
  - apiVersion: entities.devgraph.ai/v1
    kind: Service
    metadata:
      name: backend-api
      labels:
        team: platform
    spec:
      type: rest-api
      port: 8080

relations:
  - source:
      kind: Service
      name: backend-api
    target:
      kind: GitlabProject
      name: backend-api
    relation: IMPLEMENTED_BY

Configure which files to read:

selectors:
  - group: mygroup
    graph_files:
      - .devgraph.yaml
      - .devgraph/entities.yaml

Filtering Projects

Use regex patterns to filter projects:

Match All Projects

project_name: ".*"

Match Prefix

project_name: "backend-.*"  # backend-api, backend-worker, etc.

Match Suffix

project_name: ".*-service"  # api-service, auth-service, etc.

Exclude Pattern

project_name: "^(?!archive-).*"  # Exclude projects starting with "archive-"

Multiple Patterns

Use multiple selectors:

selectors:
  - group: mygroup
    project_name: "backend-.*"
  - group: mygroup
    project_name: "frontend-.*"

Use Cases

Multi-Group Discovery

selectors:
  - group: company-backend
  - group: company-frontend
  - group: company-platform

Subgroup Discovery

selectors:
  - group: engineering/backend
  - group: engineering/frontend
  - group: engineering/devops

Environment Separation

# Production
- name: gitlab-prod
  config:
    namespace: production
    selectors:
      - group: production
        project_name: "prod-.*"

# Staging
- name: gitlab-staging
  config:
    namespace: staging
    selectors:
      - group: staging
        project_name: "staging-.*"

Team-Based Organization

selectors:
  - group: platform-team
    project_name: "platform-.*"
    graph_files: [.devgraph.yaml]
  - group: product-team
    project_name: "product-.*"
    graph_files: [.devgraph.yaml]

Troubleshooting

Rate Limiting

Symptom: Logs show "GitLab API rate limit" or 429 errors

Solutions:

1. Increase reconciliation interval (every: 600 for 10 minutes)
2. Reduce number of groups/projects
3. For self-hosted: Check rate limit settings

Check rate limit (GitLab.com):

• 2,000 requests per minute per user
• 300 requests per minute for unauthenticated users

Authentication Errors

Symptom: "401 Unauthorized" or "403 Forbidden"

Solutions:

1. Verify token is correct and not expired
2. Check token has required scopes (read_api, read_repository)
3. Verify token has access to the specified groups
4. For self-hosted: Ensure user/token is active

Missing Projects

Symptom: Expected projects not appearing

Solutions:

1. Check project_name pattern matches project names
2. Verify token has access to projects (private projects need proper permissions)
3. Check group path is correct (case-sensitive)
4. Verify projects are not archived (archived projects are included by default)
5. Review logs for errors

Group Not Found

Symptom: "Group not found" error

Solutions:

1. Verify group path is correct (use full path for subgroups: parent/child)
2. Check token has access to the group
3. Ensure group exists in the GitLab instance

Graph File Parse Errors

Symptom: Errors reading .devgraph.yaml files

Solutions:

1. Verify file exists in project's default branch
2. Check YAML syntax is valid
3. Ensure token has read_repository scope
4. Review file path in graph_files configuration

Performance Tips

1. Optimize selectors: Filter at API level with specific group/project patterns
2. Adjust interval: Balance freshness vs. API usage
3. Minimize graph_files: Only parse files you need
4. Use subgroups: Organize projects into subgroups for better filtering
5. Self-hosted advantage: Self-hosted GitLab often has higher rate limits

Integration Examples

Link CI/CD Pipelines

GitLab CI/CD pipelines can reference projects:

# In GitLab CI, .gitlab-ci.yml can declare dependencies
GitlabProject --DEPENDS_ON--> GitlabProject

Link Deployments to Projects

Kubernetes deployments can link to GitLab projects:

ArgoApplication --USES--> GitlabProject

Link Services to Projects

In your .devgraph.yaml:

relations:
  - source:
      kind: Service
      name: auth-service
    target:
      kind: GitlabProject
      name: auth-service
    relation: IMPLEMENTED_BY

GitLab.com vs Self-Hosted

GitLab.com

base_url: https://gitlab.com
api_url: https://gitlab.com/api/v4

Characteristics:

• Rate limit: 2,000 requests/minute per user
• Free tier available
• Managed service
• Latest features

Self-Hosted GitLab

base_url: https://gitlab.mycompany.com
api_url: https://gitlab.mycompany.com/api/v4

Characteristics:

• Custom rate limits (usually higher)
• Full control over instance
• Can be on-premises or private cloud
• May have different features based on license

Next Steps

• Configure GitHub molecule for GitHub repositories
• Set up Argo CD molecule to link deployments to projects
• Learn about entity definitions
• Explore relationships