0
# GitLab Integration
1

2
The GitLab plugin provides comprehensive GitLab integration including release creation, asset uploads, and repository operations. It supports authentication, release notes generation, and asset management for both GitLab.com and self-hosted GitLab instances.
3

4
## Capabilities
5

6
### GitLab Plugin Class
7

8
Main GitLab integration plugin for releases and repository operations.
9

10
```javascript { .api }
11
/**
12
 * GitLab integration plugin for releases and repository operations
13
 * Handles GitLab releases, asset uploads, and repository integration
14
 */
15
class GitLab extends Plugin {
16
  /** Initialize GitLab plugin with authentication and repository validation */
17
  init(): Promise<void>;
18
  
19
  /** Authentication and validation */
20
  isAuthenticated(): Promise<boolean>;
21
  isCollaborator(): Promise<boolean>;
22
  
23
  /** Get latest version from GitLab releases */
24
  getLatestVersion(): Promise<string>;
25
  
26
  /** Get changelog from GitLab commits and merge requests */
27
  getChangelog(): Promise<string>;
28
  
29
  /** Pre-release hook for milestone validation */
30
  beforeRelease(): Promise<void>;
31
  
32
  /**
33
   * Create GitLab release
34
   * @returns Promise resolving to boolean indicating success
35
   */
36
  release(): Promise<boolean>;
37
  
38
  /** Log release URL after successful release */
39
  afterRelease(): void;
40
  
41
  /** Release management */
42
  createRelease(): Promise<boolean>;
43
  checkReleaseMilestones(): Promise<void>;
44
  getReleaseMilestones(): string[];
45
  
46
  /** Asset management */
47
  uploadAsset(filePath: string): Promise<any>;
48
  uploadAssets(): Promise<void>;
49
  
50
  /** Repository information */
51
  getWebUrl(): string;
52
  
53
  /** API utilities */
54
  request(endpoint: string, options?: any): Promise<any>;
55
}
56
```
57

58
### Release Operations
59

60
Methods for creating and managing GitLab releases.
61

62
```javascript { .api }
63
/**
64
 * Create GitLab release with notes and assets
65
 * @param options - Release creation options
66
 * @returns Promise resolving to GitLab release object
67
 */
68
createRelease(options: CreateReleaseOptions): Promise<GitLabRelease>;
69

70
/**
71
 * Upload assets to GitLab package registry or generic packages
72
 * @param assets - Array of asset file paths or glob patterns
73
 * @returns Promise that resolves when all assets are uploaded
74
 */
75
uploadAssets(assets: string[]): Promise<void>;
76

77
/**
78
 * Get GitLab release by tag name
79
 * @param tag - Git tag name
80
 * @returns Promise resolving to release object or null if not found
81
 */
82
getReleaseByTag(tag: string): Promise<GitLabRelease | null>;
83

84
/**
85
 * Update existing GitLab release
86
 * @param releaseId - GitLab release ID
87
 * @param options - Update options
88
 * @returns Promise resolving to updated release object
89
 */
90
updateRelease(releaseId: number, options: UpdateReleaseOptions): Promise<GitLabRelease>;
91

92
interface CreateReleaseOptions {
93
  /** Release tag name */
94
  tag_name: string;
95
  /** Release name/title */
96
  name?: string;
97
  /** Release description/body */
98
  description?: string;
99
  /** Commit SHA or branch for release */
100
  ref?: string;
101
  /** Release milestones */
102
  milestones?: string[];
103
  /** Released date */
104
  released_at?: string;
105
}
106

107
interface UpdateReleaseOptions {
108
  /** Updated release name */
109
  name?: string;
110
  /** Updated release description */
111
  description?: string;
112
  /** Updated milestones */
113
  milestones?: string[];
114
}
115

116
interface GitLabRelease {
117
  /** Release tag name */
118
  tag_name: string;
119
  /** Release name */
120
  name: string;
121
  /** Release description */
122
  description: string;
123
  /** Release date */
124
  released_at: string;
125
  /** Release links */
126
  _links: {
127
    /** Web URL for the release */
128
    self: string;
129
  };
130
  /** Associated milestones */
131
  milestones: GitLabMilestone[];
132
  /** Release assets */
133
  assets: {
134
    /** Asset count */
135
    count: number;
136
    /** Asset sources */
137
    sources: GitLabAssetSource[];
138
    /** Asset links */
139
    links: GitLabAssetLink[];
140
  };
141
}
142

143
interface GitLabMilestone {
144
  /** Milestone ID */
145
  id: number;
146
  /** Milestone title */
147
  title: string;
148
  /** Milestone description */
149
  description: string;
150
  /** Milestone state */
151
  state: string;
152
  /** Milestone web URL */
153
  web_url: string;
154
}
155

156
interface GitLabAssetSource {
157
  /** Source format (zip, tar.gz, tar.bz2, tar) */
158
  format: string;
159
  /** Source download URL */
160
  url: string;
161
}
162

163
interface GitLabAssetLink {
164
  /** Asset link ID */
165
  id: number;
166
  /** Asset name */
167
  name: string;
168
  /** Asset URL */
169
  url: string;
170
  /** Asset type */
171
  link_type: string;
172
}
173
```
174

175
### Repository Information
176

177
Methods for retrieving GitLab repository information and URLs.
178

179
```javascript { .api }
180
/**
181
 * Get GitLab repository web URL
182
 * @returns Repository web URL string
183
 */
184
getWebUrl(): string;
185

186
/**
187
 * Get GitLab repository API URL
188
 * @returns Repository API URL string
189
 */
190
getApiUrl(): string;
191

192
/**
193
 * Get GitLab project information
194
 * @returns Promise resolving to project object
195
 */
196
getProject(): Promise<GitLabProject>;
197

198
interface GitLabProject {
199
  /** Project ID */
200
  id: number;
201
  /** Project name */
202
  name: string;
203
  /** Project path */
204
  path: string;
205
  /** Project full path */
206
  path_with_namespace: string;
207
  /** Project description */
208
  description: string;
209
  /** Project web URL */
210
  web_url: string;
211
  /** Project HTTP clone URL */
212
  http_url_to_repo: string;
213
  /** Project SSH clone URL */
214
  ssh_url_to_repo: string;
215
  /** Default branch */
216
  default_branch: string;
217
  /** Project visibility */
218
  visibility: string;
219
}
220
```
221

222
### Authentication and Configuration
223

224
GitLab plugin authentication and configuration options.
225

226
```javascript { .api }
227
interface GitLabOptions {
228
  /** Enable/disable GitLab plugin entirely */
229
  disabled?: boolean;
230
  
231
  /** Enable/disable GitLab release creation */
232
  release?: boolean;
233
  
234
  /** GitLab personal access token or CI job token for authentication */
235
  token?: string;
236
  
237
  /** Environment variable name for token (default: 'GITLAB_TOKEN') */
238
  tokenRef?: string;
239
  
240
  /** Token header type ('Private-Token' or 'Job-Token') */
241
  tokenHeader?: string;
242
  
243
  /** Release name template (supports context interpolation) */
244
  releaseName?: string;
245
  
246
  /** Release description/notes template (supports context interpolation) */
247
  releaseNotes?: string;
248
  
249
  /** Auto-generate release notes using GitLab's API */
250
  autoGenerate?: boolean;
251
  
252
  /** Asset files to upload (file paths or glob patterns) */
253
  assets?: string[];
254
  
255
  /** GitLab instance origin URL (for self-hosted GitLab) */
256
  origin?: string;
257
  
258
  /** Skip authentication and connectivity checks */
259
  skipChecks?: boolean;
260
  
261
  /** SSL/TLS security settings */
262
  secure?: boolean;
263
  
264
  /** Custom certificate authority file path */
265
  certificateAuthorityFile?: string;
266
  
267
  /** Environment variable for certificate authority file reference */
268
  certificateAuthorityFileRef?: string;
269
  
270
  /** Project milestones to associate with release */
271
  milestones?: string[];
272
  
273
  /** Use project IDs instead of paths in URLs */
274
  useIdsForUrls?: boolean;
275
  
276
  /** Use GitLab generic package repository for assets */
277
  useGenericPackageRepositoryForAssets?: boolean;
278
  
279
  /** HTTP proxy configuration */
280
  proxy?: string;
281
  
282
  /** Request timeout in milliseconds */
283
  timeout?: number;
284
  
285
  /** Number of retry attempts for failed requests */
286
  retries?: number;
287
  
288
  /** Minimum timeout between retries in milliseconds */
289
  retryMinTimeout?: number;
290
  
291
  /** Update existing release if tag already exists */
292
  update?: boolean;
293
  
294
  /** Comments configuration for issue/MR processing */
295
  comments?: {
296
    /** Submit comments on resolved issues */
297
    submit?: boolean;
298
    /** Include resolved issues in release notes */
299
    issue?: string;
300
    /** Include merged MRs in release notes */
301
    mr?: string;
302
  };
303
}
304
```
305

306
**Usage Examples:**
307

308
```javascript
309
// Basic GitLab release configuration
310
const result = await runTasks({
311
  gitlab: {
312
    release: true,
313
    releaseName: "Release ${version}",
314
    assets: ["dist/*.zip", "docs/*.pdf"]
315
  }
316
});
317

318
// Advanced GitLab configuration with milestones
319
const result = await runTasks({
320
  gitlab: {
321
    release: true,
322
    releaseName: "🚀 ${name} v${version}",
323
    releaseNotes: "## Changes\n\n${changelog}\n\n## Installation\n\nnpm install ${name}@${version}",
324
    milestones: ["v19.0", "Release Candidate"],
325
    assets: [
326
      "dist/bundle.min.js",
327
      "dist/bundle.min.css",
328
      "docs/api.md"
329
    ],
330
    autoGenerate: true,
331
    update: true
332
  }
333
});
334

335
// Self-hosted GitLab configuration
336
const result = await runTasks({
337
  gitlab: {
338
    release: true,
339
    token: process.env.GITLAB_TOKEN,
340
    origin: "https://gitlab.internal.company.com",
341
    secure: false,  // For self-signed certificates
342
    certificateAuthorityFile: "/path/to/ca.crt"
343
  }
344
});
345

346
// GitLab CI/CD with job token
347
const result = await runTasks({
348
  gitlab: {
349
    release: true,
350
    tokenRef: "CI_JOB_TOKEN",
351
    tokenHeader: "Job-Token",
352
    useGenericPackageRepositoryForAssets: true
353
  }
354
});
355
```
356

357
### Authentication Methods
358

359
The GitLab plugin supports multiple authentication methods:
360

361
1. **Personal Access Token**: `GITLAB_TOKEN` environment variable or configuration
362
2. **Job Token**: `CI_JOB_TOKEN` for GitLab CI/CD pipelines
363
3. **Custom Token Reference**: Specify custom environment variable name
364
4. **Deploy Token**: Limited scope token for releases
365

366
### Asset Upload Options
367

368
The GitLab plugin provides two asset upload mechanisms:
369

370
1. **Release Links**: Traditional links associated with releases
371
2. **Generic Package Repository**: Upload to GitLab's package registry
372

373
### Self-hosted GitLab Support
374

375
The plugin includes comprehensive support for self-hosted GitLab instances:
376

377
- **Custom Origins**: Specify custom GitLab instance URLs
378
- **Certificate Handling**: Support for custom CA certificates and self-signed certificates
379
- **Security Options**: Configurable SSL/TLS verification
380
- **API Compatibility**: Works with various GitLab versions
381

382
### GitLab CI/CD Integration
383

384
The plugin is optimized for GitLab CI/CD environments:
385

386
- **Job Token Authentication**: Automatic CI job token detection
387
- **Pipeline Variables**: Integration with GitLab CI variables
388
- **Artifact Handling**: Upload build artifacts as release assets
389
- **Milestone Integration**: Associate releases with project milestones
390

391
### Error Handling
392

393
The GitLab plugin includes robust error handling for:
394

395
- **Authentication Issues**: Clear feedback for token problems
396
- **API Rate Limits**: Automatic retry with exponential backoff
397
- **Network Connectivity**: Timeout and retry logic for self-hosted instances
398
- **Asset Upload Failures**: Individual asset retry without affecting release creation
399
- **SSL/TLS Issues**: Detailed error messages for certificate problems
400

401
### Context Variables
402

403
The GitLab plugin provides additional context variables:
404

405
- `${releaseUrl}` - URL of created GitLab release
406
- `${projectId}` - GitLab project ID
407
- `${repo.host}` - GitLab host (for self-hosted instances)
408
- `${milestones}` - Associated milestone names
409

410
### Comparison with GitHub Plugin
411

412
Key differences from the GitHub plugin:
413

414
- **Milestones**: GitLab releases can be associated with project milestones
415
- **Generic Packages**: Alternative asset storage in package registry
416
- **Job Tokens**: CI-specific authentication method
417
- **Project IDs**: Option to use project IDs instead of paths in URLs
418
- **Self-hosted Focus**: Enhanced support for on-premise GitLab instances