GitLab API Connector Guide

The GitLab API connector lets Tealfabric workflows create, update, and retrieve GitLab resources across GitLab.com and self-hosted GitLab instances. It is useful for automating issue workflows, merge request tracking, and project reporting from a single integration path.

Configure instance and token access

Set url to your GitLab base URL, such as https://gitlab.com or your self-hosted domain, and provide apikey (or private_token from integration configuration) as a personal access token or private token with the scopes required for your target endpoints. Keep path as /api/v4 unless your deployment uses a different API prefix.

Use endpoint and query defaults only when your workflows repeatedly call the same resource pattern. Set timeout_seconds for expected response times, then run test to verify token validity, API path resolution, and basic connectivity.

Create resources with send

Use send for write operations such as creating issues, updating issue metadata, or opening merge requests. Provide the endpoint relative to the API path and send payloads in the format expected by the specific GitLab endpoint.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function createIssue(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "send",
      endpoint: "projects/<ENTITY_ID>/issues",
      method: "POST",
      data: {
        title: "Bug: Checkout error on payment callback",
        description: "Workflow detected repeated 500 responses in checkout callback.",
        labels: "bug,priority::high",
        assignee_ids: [123]
      }
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "endpoint": "projects/<ENTITY_ID>/issues",
    "method": "POST",
    "data": {
      "title": "Bug: Checkout error on payment callback",
      "description": "Workflow detected repeated 500 responses in checkout callback.",
      "labels": "bug,priority::high",
      "assignee_ids": [123]
    }
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "response": {
      "id": "<ENTITY_ID>",
      "iid": 42,
      "title": "Bug: Checkout error on payment callback",
      "state": "opened"
    },
    "http_status": 201
  }
}

Retrieve resources with receive

Use receive to list projects, read issues, or gather merge request state for downstream automation. Include query parameters such as pagination and state filters so workflows process focused result sets.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function listMergeRequests(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "receive",
      endpoint: "projects/<ENTITY_ID>/merge_requests",
      query: "state=opened&per_page=20&page=1"
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "receive",
    "endpoint": "projects/<ENTITY_ID>/merge_requests",
    "query": "state=opened&per_page=20&page=1"
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "data": [
      {
        "id": "<ENTITY_ID>",
        "iid": 17,
        "title": "Feature: Add payment retry handling",
        "state": "opened"
      }
    ],
    "total_size": 1,
    "http_status": 200
  }
}

Verify connectivity with test

Run test after token rotation or GitLab upgrades. The connector validates url and apikey/private_token, then calls GET {path}/user with the PRIVATE-TOKEN header.

{
  "success": true,
  "data": {
    "message": "GitLab API connection test successful",
    "details": {
      "base_url": "https://gitlab.com",
      "api_path": "/api/v4",
      "authenticated_user": "example-user",
      "user_id": 12345,
      "http_status": 200
    }
  }
}

Operate safely in production

GitLab APIs can apply rate limits and may return throttling responses under burst traffic. Use pagination, retries with backoff, and scoped batch sizes to keep automations stable.

Authentication and authorization failures usually indicate invalid tokens, expired credentials, or missing project permissions. Use least-privilege tokens, rotate them regularly, and avoid writing token values to logs or process outputs.

Related resources

For endpoint behavior and authentication details, see the GitLab REST API documentation and personal access token guidance.