v2.5.0

changelog.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 2026-03-02 - 2.5.0 - feat(gitlab)
+add pipelines and jobs API support, including list/get/trigger/delete/retry/cancel operations, job controls, and related types and list options
+
+- Add new pipeline methods: getPipelines (with filtering, ordering and pagination), getPipeline, triggerPipeline, deletePipeline, retryPipeline, cancelPipeline, getPipelineVariables, getPipelineTestReport
+- Add new job methods: getPipelineJobs (with scope filtering and pagination), getJob, retryJob, cancelJob, playJob, eraseJob; preserve getJobLog
+- Introduce IPipelineListOptions and IJobListOptions for richer listing filters
+- Extend and add interfaces: IGitLabPipeline (additional metadata fields), IGitLabJob (expanded fields including pipeline, runner, artifacts), IGitLabPipelineVariable, IGitLabTestReport, IGitLabTestSuite, IGitLabTestCase and other minor interface reorganizations
+- Export the new interfaces from the package entry (ts/index.ts)
+
+## 2026-03-02 - 2.4.0 - feat(gitlab)
+add repository branches and tags endpoints and corresponding types
+
+- Add getRepoBranches(projectId, opts?) to list repository branches (supports pagination with page and perPage; defaults to page=1, perPage=50).
+- Add getRepoTags(projectId, opts?) to list repository tags (supports pagination with page and perPage; defaults to page=1, perPage=50).
+- Introduce IGitLabBranch and IGitLabTag interfaces and export them from ts/index.ts.
+
+## 2026-02-28 - 2.3.0 - feat(gitlab)
+add support for GitLab protected branches (list and unprotect)
+
+- Added IGitLabProtectedBranch interface
+- Added GitLabClient.getProtectedBranches(projectId) returning IGitLabProtectedBranch[]
+- Added GitLabClient.unprotectBranch(projectId, branchName) to remove branch protection
+- Exported IGitLabProtectedBranch from index.ts
+- Non-breaking API additions; recommended minor version bump
+
+## 2026-02-28 - 2.2.0 - feat(gitlabclient)
+add deleteProject method to delete a project using GitLab API DELETE /api/v4/projects/:id
+
+- Adds GitlabClient.deleteProject(projectId: number | string): Promise<void>.
+- Implements DELETE /api/v4/projects/:id and URL-encodes the projectId.
+- Non-breaking API addition — bump minor version.
+
+## 2026-02-28 - 2.1.0 - feat(gitlab)
+add group- and project-management methods to GitLab client
+
+- Adds getGroupByPath(fullPath) to fetch a group by full path
+- Adds getGroupProjects(groupId, opts?) to list projects in a group (include_subgroups=true, default perPage=50, optional search)
+- Adds getDescendantGroups(groupId, opts?) to list descendant subgroups (paginated, default perPage=50, optional search)
+- Adds createGroup(name, path, parentId?) to create groups (defaults to private visibility)
+- Adds createProject(name, opts?) to create projects with optional path, namespaceId, visibility (default private) and description
+
 ## 2026-02-24 - 2.0.3 - fix()
 no changes detected; nothing to commit
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apiclient.xyz/gitlab",
-  "version": "2.0.3",
+  "version": "2.5.0",
   "private": false,
   "description": "A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.",
   "main": "dist_ts/index.js",

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@apiclient.xyz/gitlab',
-  version: '2.0.3',
+  version: '2.5.0',
   description: 'A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.'
 }

ts/gitlab.classes.gitlabclient.ts

@@ -6,10 +6,17 @@ import type {
   IGitLabGroup,
   IGitLabVariable,
   IVariableOptions,
+  IGitLabProtectedBranch,
+  IGitLabBranch,
+  IGitLabTag,
   IGitLabPipeline,
+  IGitLabPipelineVariable,
+  IGitLabTestReport,
   IGitLabJob,
   ITestConnectionResult,
   IListOptions,
+  IPipelineListOptions,
+  IJobListOptions,
 } from './gitlab.interfaces.js';
 
 export class GitLabClient {
@@ -125,6 +132,73 @@ export class GitLabClient {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Groups — scoped queries
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get a single group by its full path (e.g. "foss.global" or "foss.global/push.rocks")
+   */
+  public async getGroupByPath(fullPath: string): Promise<IGitLabGroup> {
+    return this.request<IGitLabGroup>(
+      'GET',
+      `/api/v4/groups/${encodeURIComponent(fullPath)}`,
+    );
+  }
+
+  /**
+   * List projects within a group (includes subgroups when include_subgroups=true)
+   */
+  public async getGroupProjects(groupId: number | string, opts?: IListOptions): Promise<IGitLabProject[]> {
+    const page = opts?.page || 1;
+    const perPage = opts?.perPage || 50;
+    let url = `/api/v4/groups/${encodeURIComponent(groupId)}/projects?include_subgroups=true&order_by=updated_at&sort=desc&page=${page}&per_page=${perPage}`;
+    if (opts?.search) {
+      url += `&search=${encodeURIComponent(opts.search)}`;
+    }
+    return this.request<IGitLabProject[]>('GET', url);
+  }
+
+  /**
+   * List all descendant groups (recursive subgroups) within a group
+   */
+  public async getDescendantGroups(groupId: number | string, opts?: IListOptions): Promise<IGitLabGroup[]> {
+    const page = opts?.page || 1;
+    const perPage = opts?.perPage || 50;
+    let url = `/api/v4/groups/${encodeURIComponent(groupId)}/descendant_groups?order_by=name&sort=asc&page=${page}&per_page=${perPage}`;
+    if (opts?.search) {
+      url += `&search=${encodeURIComponent(opts.search)}`;
+    }
+    return this.request<IGitLabGroup[]>('GET', url);
+  }
+
+  /**
+   * Create a new group. Optionally nested under a parent group.
+   */
+  public async createGroup(name: string, path: string, parentId?: number): Promise<IGitLabGroup> {
+    const body: any = { name, path, visibility: 'private' };
+    if (parentId) body.parent_id = parentId;
+    return this.request<IGitLabGroup>('POST', '/api/v4/groups', body);
+  }
+
+  /**
+   * Create a new project (repository).
+   */
+  public async createProject(name: string, opts?: {
+    path?: string;
+    namespaceId?: number;
+    visibility?: string;
+    description?: string;
+  }): Promise<IGitLabProject> {
+    return this.request<IGitLabProject>('POST', '/api/v4/projects', {
+      name,
+      path: opts?.path || name,
+      namespace_id: opts?.namespaceId,
+      visibility: opts?.visibility || 'private',
+      description: opts?.description || '',
+    });
+  }
+
   // ---------------------------------------------------------------------------
   // Projects
   // ---------------------------------------------------------------------------
@@ -265,22 +339,131 @@ export class GitLabClient {
   // Pipelines
   // ---------------------------------------------------------------------------
 
-  public async getPipelines(projectId: number | string, opts?: IListOptions): Promise<IGitLabPipeline[]> {
+  /**
+   * List pipelines for a project with optional filters.
+   * Supports status, ref, source, scope, username, date range, ordering.
+   */
+  public async getPipelines(projectId: number | string, opts?: IPipelineListOptions): Promise<IGitLabPipeline[]> {
     const page = opts?.page || 1;
     const perPage = opts?.perPage || 30;
-    return this.request<IGitLabPipeline[]>(
+    const orderBy = opts?.orderBy || 'updated_at';
+    const sort = opts?.sort || 'desc';
+    let url = `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines?page=${page}&per_page=${perPage}&order_by=${orderBy}&sort=${sort}`;
+    if (opts?.status) url += `&status=${encodeURIComponent(opts.status)}`;
+    if (opts?.ref) url += `&ref=${encodeURIComponent(opts.ref)}`;
+    if (opts?.source) url += `&source=${encodeURIComponent(opts.source)}`;
+    if (opts?.scope) url += `&scope=${encodeURIComponent(opts.scope)}`;
+    if (opts?.username) url += `&username=${encodeURIComponent(opts.username)}`;
+    if (opts?.updatedAfter) url += `&updated_after=${encodeURIComponent(opts.updatedAfter)}`;
+    if (opts?.updatedBefore) url += `&updated_before=${encodeURIComponent(opts.updatedBefore)}`;
+    return this.request<IGitLabPipeline[]>('GET', url);
+  }
+
+  /**
+   * Get a single pipeline's full details.
+   */
+  public async getPipeline(projectId: number | string, pipelineId: number): Promise<IGitLabPipeline> {
+    return this.request<IGitLabPipeline>(
       'GET',
-      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines?page=${page}&per_page=${perPage}&order_by=updated_at&sort=desc`,
+      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}`,
     );
   }
 
-  public async getPipelineJobs(projectId: number | string, pipelineId: number): Promise<IGitLabJob[]> {
-    return this.request<IGitLabJob[]>(
-      'GET',
-      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/jobs`,
+  /**
+   * Trigger a new pipeline on the given ref, optionally with variables.
+   */
+  public async triggerPipeline(
+    projectId: number | string,
+    ref: string,
+    variables?: { key: string; value: string; variable_type?: string }[],
+  ): Promise<IGitLabPipeline> {
+    const body: any = { ref };
+    if (variables && variables.length > 0) {
+      body.variables = variables;
+    }
+    return this.request<IGitLabPipeline>(
+      'POST',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/pipeline`,
+      body,
     );
   }
 
+  /**
+   * Delete a pipeline and all its jobs.
+   */
+  public async deletePipeline(projectId: number | string, pipelineId: number): Promise<void> {
+    await this.request(
+      'DELETE',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}`,
+    );
+  }
+
+  /**
+   * Get variables used in a specific pipeline run.
+   */
+  public async getPipelineVariables(projectId: number | string, pipelineId: number): Promise<IGitLabPipelineVariable[]> {
+    return this.request<IGitLabPipelineVariable[]>(
+      'GET',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/variables`,
+    );
+  }
+
+  /**
+   * Get the test report for a pipeline.
+   */
+  public async getPipelineTestReport(projectId: number | string, pipelineId: number): Promise<IGitLabTestReport> {
+    return this.request<IGitLabTestReport>(
+      'GET',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/test_report`,
+    );
+  }
+
+  public async retryPipeline(projectId: number | string, pipelineId: number): Promise<IGitLabPipeline> {
+    return this.request<IGitLabPipeline>(
+      'POST',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/retry`,
+    );
+  }
+
+  public async cancelPipeline(projectId: number | string, pipelineId: number): Promise<IGitLabPipeline> {
+    return this.request<IGitLabPipeline>(
+      'POST',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/cancel`,
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Jobs
+  // ---------------------------------------------------------------------------
+
+  /**
+   * List jobs for a pipeline with optional scope filter and pagination.
+   */
+  public async getPipelineJobs(projectId: number | string, pipelineId: number, opts?: IJobListOptions): Promise<IGitLabJob[]> {
+    const page = opts?.page || 1;
+    const perPage = opts?.perPage || 100;
+    let url = `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/jobs?page=${page}&per_page=${perPage}`;
+    if (opts?.scope && opts.scope.length > 0) {
+      for (const s of opts.scope) {
+        url += `&scope[]=${encodeURIComponent(s)}`;
+      }
+    }
+    return this.request<IGitLabJob[]>('GET', url);
+  }
+
+  /**
+   * Get a single job's full details.
+   */
+  public async getJob(projectId: number | string, jobId: number): Promise<IGitLabJob> {
+    return this.request<IGitLabJob>(
+      'GET',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/jobs/${jobId}`,
+    );
+  }
+
+  /**
+   * Get a job's raw log (trace) output.
+   */
   public async getJobLog(projectId: number | string, jobId: number): Promise<string> {
     return this.requestText(
       'GET',
@@ -288,17 +471,94 @@ export class GitLabClient {
     );
   }
 
-  public async retryPipeline(projectId: number | string, pipelineId: number): Promise<void> {
-    await this.request(
+  /**
+   * Retry a single job.
+   */
+  public async retryJob(projectId: number | string, jobId: number): Promise<IGitLabJob> {
+    return this.request<IGitLabJob>(
       'POST',
-      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/retry`,
+      `/api/v4/projects/${encodeURIComponent(projectId)}/jobs/${jobId}/retry`,
     );
   }
 
-  public async cancelPipeline(projectId: number | string, pipelineId: number): Promise<void> {
+  /**
+   * Cancel a running job.
+   */
+  public async cancelJob(projectId: number | string, jobId: number): Promise<IGitLabJob> {
+    return this.request<IGitLabJob>(
+      'POST',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/jobs/${jobId}/cancel`,
+    );
+  }
+
+  /**
+   * Trigger a manual job (play action).
+   */
+  public async playJob(projectId: number | string, jobId: number): Promise<IGitLabJob> {
+    return this.request<IGitLabJob>(
+      'POST',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/jobs/${jobId}/play`,
+    );
+  }
+
+  /**
+   * Erase a job's trace and artifacts.
+   */
+  public async eraseJob(projectId: number | string, jobId: number): Promise<void> {
     await this.request(
       'POST',
-      `/api/v4/projects/${encodeURIComponent(projectId)}/pipelines/${pipelineId}/cancel`,
+      `/api/v4/projects/${encodeURIComponent(projectId)}/jobs/${jobId}/erase`,
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Repository Branches & Tags
+  // ---------------------------------------------------------------------------
+
+  public async getRepoBranches(projectId: number | string, opts?: IListOptions): Promise<IGitLabBranch[]> {
+    const page = opts?.page || 1;
+    const perPage = opts?.perPage || 50;
+    return this.request<IGitLabBranch[]>(
+      'GET',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/repository/branches?page=${page}&per_page=${perPage}`,
+    );
+  }
+
+  public async getRepoTags(projectId: number | string, opts?: IListOptions): Promise<IGitLabTag[]> {
+    const page = opts?.page || 1;
+    const perPage = opts?.perPage || 50;
+    return this.request<IGitLabTag[]>(
+      'GET',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/repository/tags?page=${page}&per_page=${perPage}`,
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Protected Branches
+  // ---------------------------------------------------------------------------
+
+  public async getProtectedBranches(projectId: number | string): Promise<IGitLabProtectedBranch[]> {
+    return this.request<IGitLabProtectedBranch[]>(
+      'GET',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/protected_branches`,
+    );
+  }
+
+  public async unprotectBranch(projectId: number | string, branchName: string): Promise<void> {
+    await this.request(
+      'DELETE',
+      `/api/v4/projects/${encodeURIComponent(projectId)}/protected_branches/${encodeURIComponent(branchName)}`,
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Project Deletion
+  // ---------------------------------------------------------------------------
+
+  public async deleteProject(projectId: number | string): Promise<void> {
+    await this.request(
+      'DELETE',
+      `/api/v4/projects/${encodeURIComponent(projectId)}`,
     );
   }
 }

ts/gitlab.interfaces.ts

@@ -1,3 +1,52 @@
+// ---------------------------------------------------------------------------
+// Common
+// ---------------------------------------------------------------------------
+
+export interface ITestConnectionResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface IListOptions {
+  search?: string;
+  page?: number;
+  perPage?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline / Job list options
+// ---------------------------------------------------------------------------
+
+export interface IPipelineListOptions extends IListOptions {
+  /** Filter by pipeline status */
+  status?: string;
+  /** Filter by branch or tag ref */
+  ref?: string;
+  /** Filter by trigger source (push, web, trigger, schedule, api, external, pipeline, chat, merge_request_event, …) */
+  source?: string;
+  /** Filter by scope (running, pending, finished, branches, tags) */
+  scope?: string;
+  /** Filter by the user who triggered the pipeline */
+  username?: string;
+  /** Return pipelines updated after this ISO 8601 date */
+  updatedAfter?: string;
+  /** Return pipelines updated before this ISO 8601 date */
+  updatedBefore?: string;
+  /** Order by field (id, status, ref, updated_at, user_id). Default: id */
+  orderBy?: string;
+  /** Sort direction (asc, desc). Default: desc */
+  sort?: string;
+}
+
+export interface IJobListOptions extends IListOptions {
+  /** Filter by job scope(s) */
+  scope?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Users
+// ---------------------------------------------------------------------------
+
 export interface IGitLabUser {
   id: number;
   username: string;
@@ -8,6 +57,10 @@ export interface IGitLabUser {
   state: string;
 }
 
+// ---------------------------------------------------------------------------
+// Projects
+// ---------------------------------------------------------------------------
+
 export interface IGitLabProject {
   id: number;
   name: string;
@@ -20,6 +73,10 @@ export interface IGitLabProject {
   last_activity_at: string;
 }
 
+// ---------------------------------------------------------------------------
+// Groups
+// ---------------------------------------------------------------------------
+
 export interface IGitLabGroup {
   id: number;
   name: string;
@@ -29,6 +86,10 @@ export interface IGitLabGroup {
   visibility: string;
 }
 
+// ---------------------------------------------------------------------------
+// Variables
+// ---------------------------------------------------------------------------
+
 export interface IGitLabVariable {
   key: string;
   value: string;
@@ -44,33 +105,143 @@ export interface IVariableOptions {
   environment_scope?: string;
 }
 
+// ---------------------------------------------------------------------------
+// Protected Branches
+// ---------------------------------------------------------------------------
+
+export interface IGitLabProtectedBranch {
+  id: number;
+  name: string;
+  allow_force_push: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Pipelines
+// ---------------------------------------------------------------------------
+
 export interface IGitLabPipeline {
   id: number;
+  iid: number;
   project_id: number;
   status: string;
   ref: string;
   sha: string;
+  before_sha: string;
+  tag: boolean;
   web_url: string;
   duration: number;
+  queued_duration: number;
   created_at: string;
+  updated_at: string;
+  started_at: string;
+  finished_at: string;
   source: string;
+  coverage: string;
+  user: IGitLabUser;
+  detailed_status: {
+    icon: string;
+    text: string;
+    label: string;
+    group: string;
+    tooltip: string;
+    has_details: boolean;
+    details_path: string;
+    favicon: string;
+  };
+  yaml_errors: string;
 }
 
+export interface IGitLabPipelineVariable {
+  key: string;
+  value: string;
+  variable_type: string;
+}
+
+export interface IGitLabTestReport {
+  total_time: number;
+  total_count: number;
+  success_count: number;
+  failed_count: number;
+  skipped_count: number;
+  error_count: number;
+  test_suites: IGitLabTestSuite[];
+}
+
+export interface IGitLabTestSuite {
+  name: string;
+  total_time: number;
+  total_count: number;
+  success_count: number;
+  failed_count: number;
+  skipped_count: number;
+  error_count: number;
+  test_cases: IGitLabTestCase[];
+}
+
+export interface IGitLabTestCase {
+  status: string;
+  name: string;
+  classname: string;
+  execution_time: number;
+  system_output: string;
+  stack_trace: string;
+}
+
+// ---------------------------------------------------------------------------
+// Jobs
+// ---------------------------------------------------------------------------
+
 export interface IGitLabJob {
   id: number;
   name: string;
   stage: string;
   status: string;
+  ref: string;
+  tag: boolean;
+  web_url: string;
+  created_at: string;
+  started_at: string;
+  finished_at: string;
   duration: number;
+  queued_duration: number;
+  coverage: number;
+  allow_failure: boolean;
+  failure_reason: string;
+  pipeline: {
+    id: number;
+    project_id: number;
+    ref: string;
+    sha: string;
+    status: string;
+  };
+  user: IGitLabUser;
+  runner: {
+    id: number;
+    description: string;
+    active: boolean;
+    is_shared: boolean;
+  };
+  artifacts: {
+    filename: string;
+    size: number;
+  }[];
+  artifacts_expire_at: string;
 }
 
-export interface ITestConnectionResult {
-  ok: boolean;
-  error?: string;
+// ---------------------------------------------------------------------------
+// Branches & Tags
+// ---------------------------------------------------------------------------
+
+export interface IGitLabBranch {
+  name: string;
+  commit: {
+    id: string;
+  };
 }
 
-export interface IListOptions {
-  search?: string;
-  page?: number;
-  perPage?: number;
+export interface IGitLabTag {
+  name: string;
+  commit: {
+    id: string;
+  };
 }

ts/index.ts

@@ -4,10 +4,19 @@ export type {
   IGitLabProject,
   IGitLabGroup,
   IGitLabVariable,
+  IGitLabProtectedBranch,
+  IGitLabBranch,
+  IGitLabTag,
   IVariableOptions,
   IGitLabPipeline,
+  IGitLabPipelineVariable,
+  IGitLabTestReport,
+  IGitLabTestSuite,
+  IGitLabTestCase,
   IGitLabJob,
   ITestConnectionResult,
   IListOptions,
+  IPipelineListOptions,
+  IJobListOptions,
 } from './gitlab.interfaces.js';
 export { commitinfo } from './00_commitinfo_data.js';