docs(core): add comprehensive readme with full API documentation
This commit is contained in:
278
readme.md
278
readme.md
@@ -4,25 +4,291 @@ A TypeScript client for the GitLab API, providing easy access to projects, group
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
```bash
|
||||
npm install @apiclient.xyz/gitlab
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
All examples below use ESM imports and async/await.
|
||||
|
||||
### Creating a Client
|
||||
|
||||
```typescript
|
||||
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();
|
||||
|
||||
// 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();
|
||||
|
||||
// Manage CI/CD variables
|
||||
await client.createProjectVariable(123, 'SECRET_KEY', 'secret-value');
|
||||
// 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
|
||||
|
||||
```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
|
||||
|
||||
Reference in New Issue
Block a user