0
# Release It!
1

2
Release It! is a comprehensive CLI tool and JavaScript library for automating software release workflows. It provides a complete solution for version management, Git operations, changelog generation, and publishing to various platforms including npm, GitHub, and GitLab. The tool features a powerful plugin system, configurable hooks, and supports both interactive and automated CI/CD environments.
3

4
## Package Information
5

6
- **Package Name**: release-it
7
- **Package Type**: npm
8
- **Language**: JavaScript/Node.js
9
- **Installation**: `npm install -D release-it` or `npm install -g release-it`
10

11
## Core Imports
12

13
```javascript
14
import runTasks from "release-it";
15
import { Config, Plugin } from "release-it";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const runTasks = require("release-it");
22
const { Config, Plugin } = require("release-it");
23
```
24

25
## Basic Usage
26

27
### CLI Usage
28

29
```bash
30
# Basic release with prompts
31
npx release-it
32

33
# Specify version increment
34
npx release-it minor
35

36
# Dry run mode
37
npx release-it --dry-run
38

39
# CI mode (non-interactive)
40
npx release-it --ci
41

42
# Configuration file
43
npx release-it --config .release-it.json
44
```
45

46
### Programmatic Usage
47

48
```javascript
49
import runTasks from "release-it";
50

51
// Basic programmatic release
52
const result = await runTasks({
53
  increment: "patch",
54
  "dry-run": false
55
});
56

57
console.log(result.version); // "1.2.3"
58
```
59

60
## Architecture
61

62
Release It! is built around several key architectural components:
63

64
- **Main Orchestrator**: Core `runTasks` function that manages the complete release workflow
65
- **Plugin System**: Extensible architecture with built-in plugins for Git, npm, GitHub, GitLab, and version management
66
- **Configuration Management**: Hierarchical configuration system supporting local files, package.json, and CLI arguments
67
- **Lifecycle Hooks**: Comprehensive hook system for executing custom commands at any stage
68
- **Interactive/CI Modes**: Dual operation modes supporting both interactive prompts and automated CI/CD workflows
69
- **Context System**: Shared context across plugins for maintaining state and templates
70

71
## Capabilities
72

73
### Core Release Orchestration
74

75
Main entry point for executing complete release workflows with plugin coordination and lifecycle management.
76

77
```javascript { .api }
78
/**
79
 * Execute complete release workflow with plugin orchestration
80
 * @param options - Release configuration options
81
 * @param dependencies - Optional dependency injection container
82
 * @returns Promise resolving to release results
83
 */
84
function runTasks(
85
  options: ReleaseOptions,
86
  dependencies?: DependencyContainer
87
): Promise<ReleaseResult>;
88

89
interface ReleaseResult {
90
  name: string;
91
  changelog: string;
92
  latestVersion: string;
93
  version: string;
94
}
95

96
interface ReleaseOptions {
97
  increment?: string | boolean;
98
  "dry-run"?: boolean;
99
  verbose?: boolean | number;
100
  ci?: boolean;
101
  "only-version"?: boolean;
102
  "release-version"?: boolean;
103
  changelog?: boolean;
104
  config?: string | boolean;
105
  [key: string]: any;
106
}
107

108
interface DependencyContainer {
109
  config?: Config;
110
  log?: Logger;
111
  shell?: Shell;
112
  spinner?: Spinner;
113
  prompt?: Prompt;
114
}
115

116
interface Logger {
117
  log(message: string): void;
118
  info(message: string): void;
119
  warn(message: string): void;
120
  error(message: string): void;
121
  obtrusive(message: string): void;
122
  preview(options: { title: string; text: string }): void;
123
}
124

125
interface Shell {
126
  exec(command: string, options?: ExecOptions, context?: any): Promise<string>;
127
}
128

129
interface Spinner {
130
  show(options: SpinnerOptions): Promise<any>;
131
}
132

133
interface Prompt {
134
  register(prompts: any, namespace: string): void;
135
  show(options: PromptOptions): Promise<any>;
136
}
137

138
interface ExecOptions {
139
  external?: boolean;
140
  write?: boolean;
141
}
142

143
interface SpinnerOptions {
144
  task: () => Promise<any>;
145
  label: string;
146
  context?: any;
147
  external?: boolean;
148
}
149

150
interface PromptOptions {
151
  type?: string;
152
  name?: string;
153
  message?: string;
154
  choices?: any[];
155
  default?: any;
156
  namespace?: string;
157
}
158
```
159

160
[Core Orchestration](./core-orchestration.md)
161

162
### Configuration Management
163

164
Comprehensive configuration system with hierarchical loading, validation, and context management.
165

166
```javascript { .api }
167
class Config {
168
  constructor(config?: any);
169
  
170
  /** Initialize configuration from files and defaults */
171
  init(): Promise<void>;
172
  
173
  /** Get configuration context with optional path */
174
  getContext(path?: string): any;
175
  
176
  /** Set context options */
177
  setContext(options: any): void;
178
  
179
  /** Set CI mode */
180
  setCI(value?: boolean): void;
181
  
182
  /** Configuration properties (read-only) */
183
  get isDryRun(): boolean;
184
  get isIncrement(): boolean;
185
  get isVerbose(): boolean;
186
  get verbosityLevel(): number;
187
  get isDebug(): boolean;
188
  get isCI(): boolean;
189
  get isPromptOnlyVersion(): boolean;
190
  get isReleaseVersion(): boolean;
191
  get isChangelog(): boolean;
192
  get options(): any;
193
  get localConfig(): any;
194
  get defaultConfig(): any;
195
}
196
```
197

198
[Configuration](./configuration.md)
199

200
### Plugin System
201

202
Extensible plugin architecture for implementing release functionality with lifecycle hooks.
203

204
```javascript { .api }
205
class Plugin {
206
  constructor(options: PluginOptions);
207
  
208
  /** Static methods */
209
  static isEnabled(): boolean;
210
  static disablePlugin(): null;
211
  
212
  /** Plugin lifecycle hooks */
213
  init(): Promise<void>;
214
  getName(): string | Promise<string>;
215
  getLatestVersion(): string | Promise<string>;
216
  getChangelog(latestVersion?: string): string | Promise<string>;
217
  getIncrement(incrementBase: IncrementBase): string | Promise<string>;
218
  getIncrementedVersionCI(incrementBase: IncrementBase): string | Promise<string>;
219
  getIncrementedVersion(incrementBase: IncrementBase): string | Promise<string>;
220
  beforeBump(): Promise<void>;
221
  bump(version: string): Promise<boolean>;
222
  beforeRelease(): Promise<void>;
223
  release(): Promise<boolean>;
224
  afterRelease(): Promise<void>;
225
  
226
  /** Context management */
227
  getContext(path?: string): any;
228
  setContext(context: any): void;
229
  
230
  /** Plugin utilities */
231
  exec(command: string, options?: { options?: any; context?: any }): Promise<string>;
232
  step(options: StepOptions): Promise<any>;
233
  registerPrompts(prompts: any): void;
234
  showPrompt(options: PromptOptions): Promise<any>;
235
  
236
  /** Plugin configuration */
237
  getInitialOptions(options: any, namespace: string): any;
238
}
239

240
interface PluginOptions {
241
  namespace: string;
242
  options?: any;
243
  container?: DependencyContainer;
244
}
245

246
interface IncrementBase {
247
  latestVersion: string;
248
  increment: string;
249
  isPreRelease: boolean;
250
  preReleaseId: string;
251
  preReleaseBase: string;
252
}
253

254
interface StepOptions {
255
  task?: () => Promise<any>;
256
  label?: string;
257
  prompt?: string;
258
  type?: string;
259
  choices?: any[];
260
  transformer?: (value: any) => any;
261
  context?: any;
262
}
263
```
264

265
[Plugin System](./plugin-system.md)
266

267
### Git Operations
268

269
Comprehensive Git functionality for commits, tags, pushes, and repository management.
270

271
```javascript { .api }
272
class Git extends Plugin {
273
  /** Static methods */
274
  static isEnabled(options: any): Promise<boolean>;
275
  
276
  /** Git status and validation */
277
  isWorkingDirClean(): Promise<boolean>;
278
  hasUpstreamBranch(): Promise<boolean>;
279
  tagExists(tag: string): Promise<boolean>;
280
  isRequiredBranch(pattern: string): Promise<boolean>;
281
  
282
  /** Git operations */
283
  stage(file: string): Promise<void>;
284
  stageDir(options?: { baseDir?: string }): Promise<void>;
285
  reset(file: string): Promise<void>;
286
  status(): Promise<string>;
287
  commit(options?: CommitOptions): Promise<void>;
288
  tag(options?: TagOptions): Promise<void>;
289
  push(options?: PushOptions): Promise<void>;
290
  
291
  /** Git information */
292
  getBranchName(): Promise<string>;
293
  getLatestTagName(): Promise<string>;
294
  getCommitsSinceLatestTag(path?: string): Promise<number>;
295
  getRemoteUrl(): Promise<string>;
296
  getRemote(): Promise<string>;
297
  getRemoteForBranch(branch: string): Promise<string>;
298
  getSecondLatestTagName(latestTag: string): Promise<string>;
299
  getUpstreamArgs(pushRepo?: string): Promise<string[]>;
300
  
301
  /** Rollback functionality */
302
  enableRollback(): void;
303
  disableRollback(): void;
304
  rollback(): void;
305
  rollbackTagPush(): Promise<void>;
306
  
307
  /** Git utilities */
308
  fetch(remoteUrl: string): Promise<void>;
309
  isRemoteName(remoteUrlOrName: string): boolean;
310
}
311

312
interface CommitOptions {
313
  message?: string;
314
  args?: string[];
315
}
316

317
interface TagOptions {
318
  name?: string;
319
  annotation?: string;
320
  args?: string[];
321
}
322

323
interface PushOptions {
324
  args?: string[];
325
}
326
```
327

328
[Git Operations](./git-operations.md)
329

330
### npm Publishing
331

332
Complete npm package publishing functionality with registry validation and authentication.
333

334
```javascript { .api }
335
class npm extends Plugin {
336
  /** Static methods */
337
  static isEnabled(options: any): boolean;
338
  
339
  /** Registry operations */
340
  isRegistryUp(): Promise<boolean>;
341
  isAuthenticated(): Promise<boolean>;
342
  isCollaborator(): Promise<boolean>;
343
  
344
  /** Version management */
345
  getLatestRegistryVersion(): Promise<string | null>;
346
  resolveTag(version: string): Promise<string>;
347
  guessPreReleaseTag(): Promise<string>;
348
  getRegistryPreReleaseTags(): Promise<string[]>;
349
  
350
  /** Registry information */
351
  getPackageUrl(): string;
352
  getRegistry(): string | undefined;
353
  getPublicPath(): string;
354
  
355
  /** Publishing */
356
  publish(options?: PublishOptions): Promise<boolean | void>;
357
}
358

359
interface PublishOptions {
360
  otp?: string;
361
  otpCallback?: () => Promise<string>;
362
}
363
```
364

365
[npm Publishing](./npm-publishing.md)
366

367
### GitHub Integration
368

369
GitHub releases, asset uploads, and repository integration.
370

371
```javascript { .api }
372
class GitHub extends Plugin {
373
  /** Authentication and validation */
374
  isAuthenticated(): Promise<boolean>;
375
  isCollaborator(): Promise<boolean>;
376
  
377
  /** Release management */
378
  createRelease(): Promise<Release>;
379
  updateRelease(): Promise<boolean>;
380
  getLatestRelease(): Promise<Release>;
381
  createWebRelease(): Promise<void>;
382
  generateWebUrl(): Promise<string>;
383
  
384
  /** Asset management */
385
  uploadAsset(filePath: string): Promise<any>;
386
  uploadAssets(): Promise<void>;
387
  
388
  /** Repository information */
389
  getWebUrl(): string;
390
  getChangelog(): Promise<string>;
391
  getReleaseUrlFallback(tagName: string): string;
392
  
393
  /** Comments and interaction */
394
  commentOnResolvedItems(): Promise<void>;
395
  getCommits(): Promise<any[]>;
396
  renderReleaseNotes(releaseNotes: any): Promise<string>;
397
  
398
  /** Client and utilities */
399
  get client(): any;
400
  retry(fn: () => Promise<any>): Promise<any>;
401
  handleError(err: any, bail: boolean): void;
402
  getOctokitReleaseOptions(options?: any): Promise<any>;
403
}
404

405
interface CreateReleaseOptions {
406
  name?: string;
407
  tag_name?: string;
408
  body?: string;
409
  draft?: boolean;
410
  prerelease?: boolean;
411
  make_latest?: boolean | 'legacy';
412
  discussion_category_name?: string;
413
}
414

415
interface Release {
416
  id: number;
417
  html_url: string;
418
  upload_url: string;
419
  tag_name: string;
420
  name: string;
421
  body: string;
422
  draft: boolean;
423
  prerelease: boolean;
424
}
425
```
426

427
[GitHub Integration](./github-integration.md)
428

429
### GitLab Integration
430

431
GitLab releases, asset uploads, and repository integration for both GitLab.com and self-hosted instances.
432

433
```javascript { .api }
434
class GitLab extends Plugin {
435
  /** Authentication and validation */
436
  isAuthenticated(): Promise<boolean>;
437
  isCollaborator(): Promise<boolean>;
438
  
439
  /** Release management */
440
  createRelease(): Promise<boolean>;
441
  checkReleaseMilestones(): Promise<void>;
442
  getReleaseMilestones(): string[];
443
  
444
  /** Asset management */
445
  uploadAsset(filePath: string): Promise<any>;
446
  uploadAssets(): Promise<void>;
447
  
448
  /** Repository information */
449
  getWebUrl(): string;
450
  getChangelog(): Promise<string>;
451
  
452
  /** API utilities */
453
  request(endpoint: string, options?: any): Promise<any>;
454
}
455

456
interface GitLabRelease {
457
  id: number;
458
  name: string;
459
  tag_name: string;
460
  description: string;
461
  _links: {
462
    self: string;
463
  };
464
}
465
```
466

467
[GitLab Integration](./gitlab-integration.md)
468

469
### CLI Interface
470

471
Command-line interface utilities and argument parsing.
472

473
```javascript { .api }
474
/**
475
 * Main CLI entry point
476
 * @param options - Parsed CLI options
477
 * @returns Promise resolving when CLI operation completes
478
 */
479
function cli(options: CLIOptions): Promise<any>;
480

481
/**
482
 * Parse CLI arguments into options object
483
 * @param args - Command line arguments
484
 * @returns Parsed options object
485
 */
486
function parseCliArguments(args: string[]): CLIOptions;
487

488
/** Print version information */
489
function version(): void;
490

491
/** Print help text */
492
function help(): void;
493

494
interface CLIOptions {
495
  increment?: string;
496
  "dry-run"?: boolean;
497
  verbose?: boolean | number;
498
  ci?: boolean;
499
  "only-version"?: boolean;
500
  "release-version"?: boolean;
501
  changelog?: boolean;
502
  config?: string;
503
  help?: boolean;
504
  version?: boolean;
505
  [key: string]: any;
506
}
507
```
508

509
[CLI Interface](./cli-interface.md)