apiclient.xyz/gitlab
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(core): add comprehensive readme with full API documentation

Browse Source
This commit is contained in:
Jürgen Kunz
2026-02-24 12:57:27 +00:00
parent e7cfd5dec1
commit 413c4be172
1 changed files with 272 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
readme.md
View File

@@ -4,25 +4,291 @@ A TypeScript client for the GitLab API, providing easy access to projects, group
## Install ## Install
```sh ```bash
npm install @apiclient.xyz/gitlab npm install @apiclient.xyz/gitlab
``` ```
## Usage ## Usage
All examples below use ESM imports and async/await.
### Creating a Client
```typescript ```typescript
import { GitLabClient } from '@apiclient.xyz/gitlab'; import { GitLabClient } from '@apiclient.xyz/gitlab';
const client = new GitLabClient('https://gitlab.com', 'your-private-token'); const client = new GitLabClient('https://gitlab.example.com', 'your-private-token');
```
// Test connection 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
```typescript
const result = await client.testConnection(); const result = await client.testConnection();
// List projects 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.
```typescript
// First page, default 50 per page
const projects = await client.getProjects(); const projects = await client.getProjects();
// Manage CI/CD variables // Search with pagination
await client.createProjectVariable(123, 'SECRET_KEY', 'secret-value'); 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
```typescript
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
```typescript
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.
```typescript
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
```typescript
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`.
```typescript
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.
```typescript
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`
```typescript
interface ITestConnectionResult {
ok: boolean;
error?: string; // Present when ok is false
}
```
### `IGitLabProject`
```typescript
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`
```typescript
interface IGitLabGroup {
id: number;
name: string;
full_path: string;
description: string;
web_url: string;
visibility: string;
}
```
### `IGitLabVariable`
```typescript
interface IGitLabVariable {
key: string;
value: string;
variable_type: string;
protected: boolean;
masked: boolean;
environment_scope: string;
}
```
### `IGitLabPipeline`
```typescript
interface IGitLabPipeline {
id: number;
project_id: number;
status: string;
ref: string;
sha: string;
web_url: string;
duration: number;
created_at: string;
source: string;
}
```
### `IGitLabJob`
```typescript
interface IGitLabJob {
id: number;
name: string;
stage: string;
status: string;
duration: number;
}
```
### `IGitLabUser`
Returned internally by `testConnection` to verify credentials.
```typescript
interface IGitLabUser {
id: number;
username: string;
name: string;
email: string;
avatar_url: string;
web_url: string;
state: string;
}
``` ```
## License ## License