GitLab Connector Guide

The GitLab connector lets Tealfabric workflows create and retrieve project data such as issues and merge requests across GitLab.com or self-hosted GitLab environments. This guide focuses on secure setup, practical request patterns, and reliability practices that keep DevOps automations maintainable.

When to use this connector

Use this connector when ProcessFlow must open issues, update delivery metadata, or query project activity to drive downstream automation. It is especially useful for incident routing, release workflows, and QA handoffs where GitLab records should stay synchronized with business processes. Using explicit project references and consistent label conventions improves traceability across teams.

Prerequisites

Before configuring the integration, ensure you have a GitLab personal access token with the minimum scopes required by your workflow actions. Confirm access to the target projects and decide whether you will reference them by numeric ID or URL-encoded path. These decisions reduce runtime errors in production runs.

Configuration reference

Connector settings are stored in integration configuration and reused across operations. Keep tokens in secure storage and rotate them according to your organization policy.

• url (required): Base URL for GitLab, such as https://gitlab.com or your self-managed domain.
• private_token (required): GitLab personal access token sent as PRIVATE-TOKEN.
• timeout_seconds (optional): Request timeout for connector calls.

Create issues or merge requests

The send operation is the primary write path and is commonly used to create issues and merge requests from workflow triggers. Keep payloads concise and include enough context for engineering teams to act quickly.

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

type GitLabIssue = {
  id?: number;
  iid?: number;
  title?: string;
  state?: string;
};

async function createGitLabIssue(
  integrationId: string,
  projectId: string
): Promise<GitLabIssue> {
  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/${encodeURIComponent(projectId)}/issues`,
        method: "POST",
        data: {
          title: "Production alert: sync latency above threshold",
          description: "Triggered from ProcessFlow monitoring automation.",
          labels: "ops,priority::high",
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as {
    success?: boolean;
    data?: { data?: GitLabIssue; response?: GitLabIssue };
  };
  const issue = payload.data?.data ?? payload.data?.response;
  if (!issue) throw new Error("Missing GitLab issue payload");
  return issue;
}

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": "Production alert: sync latency above threshold",
      "description": "Triggered from ProcessFlow monitoring automation.",
      "labels": "ops,priority::high"
    }
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "data": {
      "id": 123456,
      "iid": 42,
      "title": "Production alert: sync latency above threshold",
      "state": "opened"
    },
    "response": {
      "id": 123456,
      "iid": 42,
      "title": "Production alert: sync latency above threshold",
      "state": "opened"
    }
  }
}

Read project and issue data

Use the receive operation to retrieve projects, issues, or merge requests for status checks and reporting workflows. For larger projects, always paginate with per_page and page to keep runtimes predictable.

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

type IssueSummary = { id?: number; iid?: number; title?: string; state?: string };

async function listOpenIssues(
  integrationId: string,
  projectId: string
): Promise<IssueSummary[]> {
  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/${encodeURIComponent(projectId)}/issues`,
        query: {
          state: "opened",
          per_page: 20,
          page: 1,
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as {
    success?: boolean;
    data?: { data?: IssueSummary[] };
  };
  if (!Array.isArray(payload.data?.data)) throw new Error("Missing GitLab receive payload");
  return payload.data.data;
}

Validate connectivity and reliability

Run test after token rotation, GitLab upgrades, or permission changes to detect authentication drift early. The test operation validates url and private_token (including minimum token length); other operations rely on GitLab API responses for auth errors. Most failures come from invalid scope, missing project access, or rate-limit pressure in high-frequency workflows. Use retry with backoff for transient failures and track execution IDs for faster troubleshooting.

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": "test"
  }'

{
  "success": true,
  "data": {
    "message": "GitLab connection test successful",
    "details": {
      "base_url": "https://gitlab.com",
      "user_id": 12345,
      "username": "automation-bot"
    }
  }
}

Additional references

For endpoint and scope details, use GitLab API documentation and GitLab personal access token guidance. Keeping request payloads and token scopes documented alongside your workflows makes future maintenance easier.