API Reference

API Reference

hub2lab exposes three HTTP endpoints.

GET /health

Health check endpoint. Returns a simple status object.

Response 200:

{
  "status": "ok",
  "timestamp": "2026-07-20T13:00:00.000Z"
}

POST /webhook/github

Receives webhook events from GitHub. The request must include a valid X-Hub-Signature-256 header.

Headers

Header	Required	Description
X-Hub-Signature-256	Yes	HMAC-SHA256 of the raw body using GITHUB_WEBHOOK_SECRET
X-GitHub-Event	Yes	Event type (push, create, delete, repository)
Content-Type	Yes	application/json

Request Body

The raw GitHub webhook payload. See GitHub webhook docs for full schemas.

Response Codes

Code	Meaning
202	Webhook accepted and queued for processing (async)
400	Unknown or unparseable event type
401	Invalid signature (token mismatch)

Supported Events

Event	Action	What Happens
push	—	Mirror-push commits to GitLab
create	branch/tag created	Create branch/tag on GitLab
delete	branch/tag deleted	Write deletion marker to GitLab
repository	created	Create project on GitLab
repository	deleted	Write repo deletion marker to GitLab
repository	renamed	Logged (API-level rename tracking)

Example Push Payload

{
  "ref": "refs/heads/main",
  "before": "abc123",
  "after": "def456",
  "repository": {
    "name": "my-repo",
    "full_name": "my-org/my-repo",
    "owner": { "login": "my-org" },
    "private": true
  },
  "organization": { "login": "my-org" },
  "commits": [
    {
      "id": "def456",
      "message": "Add feature",
      "added": ["new-file.txt"],
      "removed": [],
      "modified": ["existing-file.txt"]
    }
  ],
  "sender": { "login": "user" }
}

POST /webhook/gitlab

Receives webhook events from GitLab. The request must include a valid X-GitLab-Token header.

Headers

Header	Required	Description
X-GitLab-Token	Yes	Shared secret matching GITLAB_WEBHOOK_SECRET
Content-Type	Yes	application/json

Request Body

The raw GitLab webhook payload. See GitLab webhook docs for full schemas.

Response Codes

Code	Meaning
202	Webhook accepted and queued for processing (async)
400	Unknown or unparseable event type
401	Invalid token

Supported Events

Event Name	What Happens
push	Mirror-push commits to GitHub
tag_push	Create tag on GitHub (currently logged; no API create)

Example Push Payload

{
  "event_name": "push",
  "ref": "refs/heads/main",
  "before": "abc123",
  "after": "def456",
  "project": {
    "id": 42,
    "name": "my-repo",
    "path_with_namespace": "my-group/my-repo",
    "namespace": "my-group",
    "visibility": "public"
  },
  "commits": [
    {
      "id": "def456",
      "message": "Add feature",
      "added": ["new-file.txt"],
      "removed": [],
      "modified": ["existing-file.txt"]
    }
  ],
  "total_commits_count": 1
}

Event Processing

All webhook endpoints return 202 immediately and process the event asynchronously. Errors during processing are logged but not returned to the webhook sender. This design keeps webhook delivery fast and prevents timeouts.

To monitor processing, check hub2lab's logs:

2026-07-20 [INFO] Processing GitHub push { event: 'push', org: 'my-org', repo: 'my-repo' }
2026-07-20 [INFO] Mirror-pushed refs/heads/main to target
2026-07-20 [INFO] Created GitLab project my-group/my-repo (id=99)
2026-07-20 [WARN] Invalid GitHub webhook signature
2026-07-20 [ERROR] GitHub event processing failed { error: '...' }