0
# Core Release Orchestration
1

2
The core orchestration system manages the complete release workflow, coordinating plugins, managing lifecycle hooks, and maintaining shared context across all release operations.
3

4
## Capabilities
5

6
### Main Release Function
7

8
The primary function for executing release workflows with full plugin coordination.
9

10
```javascript { .api }
11
/**
12
 * Execute complete release workflow with plugin orchestration
13
 * @param options - Release configuration options including increment, mode flags, and plugin settings
14
 * @param dependencies - Optional dependency injection container for testing and customization
15
 * @returns Promise resolving to release results including version information and changelog
16
 */
17
function runTasks(
18
  options: ReleaseOptions,
19
  dependencies?: DependencyContainer
20
): Promise<ReleaseResult>;
21

22
interface ReleaseOptions {
23
  /** Version increment: 'major', 'minor', 'patch', 'prerelease', or explicit version */
24
  increment?: string | boolean;
25
  /** Dry run mode - show operations without executing */
26
  "dry-run"?: boolean;
27
  /** Verbose output level (boolean or number 1-2) */
28
  verbose?: boolean | number;
29
  /** CI mode - non-interactive operation */
30
  ci?: boolean;
31
  /** Prompt only for version selection */
32
  "only-version"?: boolean;
33
  /** Print release version and exit */
34
  "release-version"?: boolean;
35
  /** Print changelog and exit */
36
  changelog?: boolean;
37
  /** Configuration file path or false to disable */
38
  config?: string | boolean;
39
  /** Configuration directory */
40
  configDir?: string;
41
  /** Extend configuration */
42
  extends?: string | false;
43
  /** Plugin-specific options */
44
  git?: GitOptions;
45
  npm?: NpmOptions;
46
  github?: GitHubOptions;
47
  gitlab?: GitLabOptions;
48
  hooks?: HooksOptions;
49
  [key: string]: any;
50
}
51

52
interface ReleaseResult {
53
  /** Package or project name */
54
  name: string;
55
  /** Generated changelog content */
56
  changelog: string;
57
  /** Previous version before release */
58
  latestVersion: string;
59
  /** New version after release */
60
  version: string;
61
}
62

63
interface DependencyContainer {
64
  /** Configuration instance */
65
  config?: Config;
66
  /** Logger instance */
67
  log?: Logger;
68
  /** Shell execution instance */
69
  shell?: Shell;
70
  /** Progress spinner instance */
71
  spinner?: Spinner;
72
  /** Interactive prompt instance */
73
  prompt?: Prompt;
74
}
75
```
76

77
### Hook System
78

79
Execute custom commands at specific points in the release workflow.
80

81
```javascript { .api }
82
interface HooksOptions {
83
  /** Commands to run before any operation */
84
  "before:init"?: string | string[];
85
  /** Commands to run after initialization */
86
  "after:init"?: string | string[];
87
  /** Commands to run before version bump */
88
  "before:bump"?: string | string[];
89
  /** Commands to run after version bump */
90
  "after:bump"?: string | string[];
91
  /** Commands to run before release */
92
  "before:release"?: string | string[];
93
  /** Commands to run after release */
94
  "after:release"?: string | string[];
95
  /** Commands to run before git operations */
96
  "before:git:init"?: string | string[];
97
  "before:git:bump"?: string | string[];
98
  "before:git:release"?: string | string[];
99
  /** Commands to run after git operations */
100
  "after:git:init"?: string | string[];
101
  "after:git:bump"?: string | string[];
102
  "after:git:release"?: string | string[];
103
  /** Commands to run before npm operations */
104
  "before:npm:init"?: string | string[];
105
  "before:npm:bump"?: string | string[];
106
  "before:npm:release"?: string | string[];
107
  /** Commands to run after npm operations */
108
  "after:npm:init"?: string | string[];
109
  "after:npm:bump"?: string | string[];
110
  "after:npm:release"?: string | string[];
111
  /** Commands to run before GitHub operations */
112
  "before:github:init"?: string | string[];
113
  "before:github:release"?: string | string[];
114
  /** Commands to run after GitHub operations */
115
  "after:github:init"?: string | string[];
116
  "after:github:release"?: string | string[];
117
}
118
```
119

120
**Usage Examples:**
121

122
```javascript
123
import runTasks from "release-it";
124

125
// Basic programmatic release
126
const result = await runTasks({
127
  increment: "minor",
128
  "dry-run": false,
129
  ci: true
130
});
131

132
console.log(`Released ${result.name} v${result.version}`);
133

134
// Release with custom hooks
135
const result = await runTasks({
136
  increment: "patch",
137
  hooks: {
138
    "before:bump": "npm test",
139
    "after:release": ["npm run build", "npm run deploy"]
140
  }
141
});
142

143
// Release with dependency injection for testing
144
const mockContainer = {
145
  shell: mockShell,
146
  log: mockLogger
147
};
148

149
const result = await runTasks(
150
  { increment: "patch", "dry-run": true },
151
  mockContainer
152
);
153
```
154

155
### Version Increment Options
156

157
Release It! supports semantic versioning increments and custom version specification.
158

159
```javascript { .api }
160
type VersionIncrement = 
161
  | "major"        // 1.0.0 -> 2.0.0
162
  | "minor"        // 1.0.0 -> 1.1.0  
163
  | "patch"        // 1.0.0 -> 1.0.1
164
  | "prerelease"   // 1.0.0 -> 1.0.1-0
165
  | "premajor"     // 1.0.0 -> 2.0.0-0
166
  | "preminor"     // 1.0.0 -> 1.1.0-0
167
  | "prepatch"     // 1.0.0 -> 1.0.1-0
168
  | string         // Explicit version like "2.1.0"
169
  | false;         // No version increment
170
```
171

172
### Context System
173

174
Shared context system for template variables and plugin communication.
175

176
```javascript { .api }
177
interface ReleaseContext {
178
  /** Package or project name */
179
  name?: string;
180
  /** Current version */
181
  version?: string;
182
  /** Previous version */
183
  latestVersion?: string;
184
  /** Generated changelog */
185
  changelog?: string;
186
  /** Git tag name */
187
  tagName?: string;
188
  /** Repository URL */
189
  repo?: {
190
    remote?: string;
191
    protocol?: string;
192
    host?: string;
193
    owner?: string;
194
    repository?: string;
195
    project?: string;
196
  };
197
  /** npm package information */
198
  npm?: {
199
    name?: string;
200
    tag?: string;
201
    registry?: string;
202
  };
203
  /** GitHub release information */
204
  github?: {
205
    releaseUrl?: string;
206
    releaseId?: number;
207
  };
208
}
209
```
210

211
Templates in configuration files and hooks can use context variables:
212

213
```json
214
{
215
  "git": {
216
    "commitMessage": "Release ${version}",
217
    "tagAnnotation": "Release ${version}\n\n${changelog}"
218
  },
219
  "hooks": {
220
    "after:release": "echo Released ${name} v${version}"
221
  }
222
}
223
```