@apiclient.xyz/gitlab

A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.

Install

npm install @apiclient.xyz/gitlab

Usage

All examples below use ESM imports and async/await.

Creating a Client

import { GitLabClient } from '@apiclient.xyz/gitlab';

const client = new GitLabClient('https://gitlab.example.com', 'your-private-token');

The constructor accepts the base URL of your GitLab instance and a personal access token (or project/group token) used for authentication via the PRIVATE-TOKEN header.

Testing the Connection

const result = await client.testConnection();

if (result.ok) {
  console.log('Connected successfully.');
} else {
  console.error('Connection failed:', result.error);
}

Listing Projects

Retrieve projects you are a member of, ordered by most recently updated.

// First page, default 50 per page
const projects = await client.getProjects();

// Search with pagination
const filtered = await client.getProjects({
  search: 'my-service',
  page: 1,
  perPage: 20,
});

for (const project of filtered) {
  console.log(`${project.id} - ${project.path_with_namespace}`);
}

Listing Groups

const groups = await client.getGroups();

// Search groups by name
const matchingGroups = await client.getGroups({ search: 'platform' });

for (const group of matchingGroups) {
  console.log(`${group.id} - ${group.full_path}`);
}

Managing Project Variables

const projectId = 42;

// List all variables
const vars = await client.getProjectVariables(projectId);

// Create a variable
await client.createProjectVariable(projectId, 'DATABASE_URL', 'postgres://...', {
  protected: true,
  masked: true,
  environment_scope: 'production',
});

// Update a variable
await client.updateProjectVariable(projectId, 'DATABASE_URL', 'postgres://new-host/...', {
  protected: true,
});

// Delete a variable
await client.deleteProjectVariable(projectId, 'DATABASE_URL');

Managing Group Variables

The group variable API mirrors the project variable API.

const groupId = 7;

// List all variables
const groupVars = await client.getGroupVariables(groupId);

// Create a variable
await client.createGroupVariable(groupId, 'NPM_TOKEN', 'tok-xxx', {
  protected: false,
  masked: true,
  environment_scope: '*',
});

// Update a variable
await client.updateGroupVariable(groupId, 'NPM_TOKEN', 'tok-yyy', {
  masked: true,
});

// Delete a variable
await client.deleteGroupVariable(groupId, 'NPM_TOKEN');

Working with Pipelines

const projectId = 42;

// List recent pipelines
const pipelines = await client.getPipelines(projectId, { page: 1, perPage: 10 });

for (const pipeline of pipelines) {
  console.log(`Pipeline #${pipeline.id} [${pipeline.status}] on ${pipeline.ref}`);
}

// Get jobs for a specific pipeline
const jobs = await client.getPipelineJobs(projectId, pipelines[0].id);
for (const job of jobs) {
  console.log(`  Job "${job.name}" (${job.stage}): ${job.status}`);
}

// Read the raw log output of a job
const log = await client.getJobLog(projectId, jobs[0].id);
console.log(log);

// Retry a failed pipeline
await client.retryPipeline(projectId, pipelines[0].id);

// Cancel a running pipeline
await client.cancelPipeline(projectId, pipelines[0].id);

API Reference

GitLabClient

Method	Signature	Returns	Description
constructor	(baseUrl: string, token: string)	GitLabClient	Create a new client instance.
testConnection	()	Promise<ITestConnectionResult>	Verify the token and connectivity.
getProjects	(opts?: IListOptions)	Promise<IGitLabProject[]>	List projects you are a member of.
getGroups	(opts?: IListOptions)	Promise<IGitLabGroup[]>	List accessible groups.
getProjectVariables	(projectId: number | string)	Promise<IGitLabVariable[]>	List all CI/CD variables for a project.
createProjectVariable	(projectId: number | string, key: string, value: string, opts?: IVariableOptions)	Promise<IGitLabVariable>	Create a CI/CD variable on a project.
updateProjectVariable	(projectId: number | string, key: string, value: string, opts?: IVariableOptions)	Promise<IGitLabVariable>	Update an existing project variable.
deleteProjectVariable	(projectId: number | string, key: string)	Promise<void>	Delete a project variable.
getGroupVariables	(groupId: number | string)	Promise<IGitLabVariable[]>	List all CI/CD variables for a group.
createGroupVariable	(groupId: number | string, key: string, value: string, opts?: IVariableOptions)	Promise<IGitLabVariable>	Create a CI/CD variable on a group.
updateGroupVariable	(groupId: number | string, key: string, value: string, opts?: IVariableOptions)	Promise<IGitLabVariable>	Update an existing group variable.
deleteGroupVariable	(groupId: number | string, key: string)	Promise<void>	Delete a group variable.
getPipelines	(projectId: number | string, opts?: IListOptions)	Promise<IGitLabPipeline[]>	List pipelines for a project, newest first.
getPipelineJobs	(projectId: number | string, pipelineId: number)	Promise<IGitLabJob[]>	Get all jobs for a pipeline.
getJobLog	(projectId: number | string, jobId: number)	Promise<string>	Retrieve the raw trace/log of a job.
retryPipeline	(projectId: number | string, pipelineId: number)	Promise<void>	Retry all failed jobs in a pipeline.
cancelPipeline	(projectId: number | string, pipelineId: number)	Promise<void>	Cancel a running pipeline.

Types

IListOptions

Pagination and search options used by getProjects, getGroups, and getPipelines.

interface IListOptions {
  search?: string;   // Filter results by keyword
  page?: number;     // Page number (default: 1)
  perPage?: number;  // Items per page (default: 50 for projects/groups, 30 for pipelines)
}

IVariableOptions

Options when creating or updating CI/CD variables.

interface IVariableOptions {
  protected?: boolean;         // Only expose to protected branches/tags (default: false)
  masked?: boolean;            // Mask the value in job logs (default: false)
  environment_scope?: string;  // Environment scope (default: '*' for all environments)
}

ITestConnectionResult

interface ITestConnectionResult {
  ok: boolean;
  error?: string;  // Present when ok is false
}

IGitLabProject

interface IGitLabProject {
  id: number;
  name: string;
  path_with_namespace: string;
  description: string;
  default_branch: string;
  web_url: string;
  visibility: string;
  topics: string[];
  last_activity_at: string;
}

IGitLabGroup

interface IGitLabGroup {
  id: number;
  name: string;
  full_path: string;
  description: string;
  web_url: string;
  visibility: string;
}

IGitLabVariable

interface IGitLabVariable {
  key: string;
  value: string;
  variable_type: string;
  protected: boolean;
  masked: boolean;
  environment_scope: string;
}

IGitLabPipeline

interface IGitLabPipeline {
  id: number;
  project_id: number;
  status: string;
  ref: string;
  sha: string;
  web_url: string;
  duration: number;
  created_at: string;
  source: string;
}

IGitLabJob

interface IGitLabJob {
  id: number;
  name: string;
  stage: string;
  status: string;
  duration: number;
}

IGitLabUser

Returned internally by testConnection to verify credentials.

interface IGitLabUser {
  id: number;
  username: string;
  name: string;
  email: string;
  avatar_url: string;
  web_url: string;
  state: string;
}

License

MIT