GitLab integration¶

This section describes the integration of GitPulse with GitLab.

Integration overview¶

graph LR
    subgraph "GitLab"
        REPO["Repository"]
        HOOK["Webhooks"]
        API["GitLab API"]
    end

    subgraph "GitPulse"
        WEBHOOK["Webhook Handler"]
        SYNC["Sync Service"]
        DB[("Database")]
    end

    REPO --> |events| HOOK
    HOOK --> |"POST /webhook"| WEBHOOK
    API --> |"pull data"| SYNC
    WEBHOOK --> DB
    SYNC --> DB

Supported features¶

What you will find in this section¶

Quick start¶

1. Token creation¶

1. Go to GitLab -> Settings -> Access Tokens
2. Create a token with permissions:
3. api - Full API access
4. read_repository - Read repository
5. Store the token in .env:

1
2

GITLAB_URL=https://gitlab.kpi.tuke.sk
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

2. Webhook configuration¶

1. In the GitLab project: Settings -> Webhooks
2. URL: https://gitpulse.kpi.fei.tuke.sk/api/v1/webhooks/gitlab
3. Secret Token: Generate and save to .env
4. Trigger events: Push, MR, Issues, Pipeline

3. Connection test¶

1
2
3
4
5
6

# Test API connection
curl -H "Private-Token: ${GITLAB_TOKEN}" \
  "${GITLAB_URL}/api/v4/user"

# Test webhook (from GitPulse)
curl -X POST http://localhost:8000/api/v1/webhooks/test

Architecture¶

sequenceDiagram
    participant GL as GitLab
    participant WH as Webhook Handler
    participant Q as Redis Queue
    participant W as Worker
    participant DB as Database

    GL->>WH: POST /webhooks/gitlab
    WH->>WH: Verify signature
    WH->>Q: Enqueue event
    WH-->>GL: 200 OK

    W->>Q: Dequeue event
    W->>W: Process event
    W->>DB: Store event
    W->>W: Calculate metrics

Supported event types¶

Push Events¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "object_kind": "push",
  "event_name": "push",
  "ref": "refs/heads/main",
  "commits": [
    {
      "id": "abc123...",
      "message": "feat: add new feature",
      "author": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "added": ["file1.py"],
      "modified": ["file2.py"],
      "removed": []
    }
  ]
}

Merge Request Events¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "object_kind": "merge_request",
  "event_type": "merge_request",
  "object_attributes": {
    "iid": 1,
    "title": "Feature: Add login",
    "state": "merged",
    "source_branch": "feature/login",
    "target_branch": "main",
    "author_id": 123
  }
}

Pipeline Events¶

1
2
3
4
5
6
7
8
9

{
  "object_kind": "pipeline",
  "object_attributes": {
    "id": 456,
    "status": "success",
    "duration": 120,
    "stages": ["build", "test", "deploy"]
  }
}

Limits and rate limiting¶

Security¶

• All tokens are stored encrypted
• Webhook signature verification
• IP whitelist for webhook endpoints (recommended)
• Audit logs of all API calls

Next steps¶

1. Token Configuration
2. Setting Webhooks
3. GitLab CI integration