0
# Configuration Management
1

2
Release It!'s configuration system provides hierarchical configuration loading, validation, and context management. Configuration can be specified through CLI arguments, configuration files, package.json, and environment variables.
3

4
## Capabilities
5

6
### Configuration Class
7

8
Main configuration management class with loading, merging, and context operations.
9

10
```javascript { .api }
11
/**
12
 * Configuration management class
13
 * Handles loading, merging, and validation of configuration options
14
 */
15
class Config {
16
  /**
17
   * Create new configuration instance
18
   * @param config - Initial configuration object
19
   */
20
  constructor(config?: any);
21
  
22
  /**
23
   * Initialize configuration by loading from files and applying defaults
24
   * Must be called before using other methods
25
   */
26
  init(): Promise<void>;
27
  
28
  /**
29
   * Get configuration context with optional nested path
30
   * @param path - Optional dot-notation path to nested value
31
   * @returns Configuration value or entire context
32
   */
33
  getContext(path?: string): any;
34
  
35
  /**
36
   * Set context options by merging with existing context
37
   * @param options - Options to merge into context
38
   */
39
  setContext(options: any): void;
40
  
41
  /**
42
   * Set CI mode flag
43
   * @param value - CI mode boolean, defaults to true
44
   */
45
  setCI(value?: boolean): void;
46
  
47
  /** Get default configuration object */
48
  get defaultConfig(): any;
49
  
50
  /** Check if running in dry-run mode */
51
  get isDryRun(): boolean;
52
  
53
  /** Check if version should be incremented */
54
  get isIncrement(): boolean;
55
  
56
  /** Check if verbose output is enabled */
57
  get isVerbose(): boolean;
58
  
59
  /** Get verbosity level (0, 1, or 2) */
60
  get verbosityLevel(): number;
61
  
62
  /** Check if debug mode is enabled */
63
  get isDebug(): boolean;
64
  
65
  /** Check if running in CI environment */
66
  get isCI(): boolean;
67
  
68
  /** Check if only prompting for version */
69
  get isPromptOnlyVersion(): boolean;
70
  
71
  /** Check if only printing release version */
72
  get isReleaseVersion(): boolean;
73
  
74
  /** Check if only printing changelog */
75
  get isChangelog(): boolean;
76
  
77
  /** Get resolved configuration options */
78
  get options(): any;
79
  
80
  /** Get loaded local configuration */
81
  get localConfig(): any;
82
}
83
```
84

85
### Configuration File Formats
86

87
Release It! supports multiple configuration file formats and locations.
88

89
```javascript { .api }
90
interface ConfigurationOptions {
91
  /** Git plugin configuration */
92
  git?: GitOptions;
93
  /** npm plugin configuration */
94
  npm?: NpmOptions;
95
  /** GitHub plugin configuration */
96
  github?: GitHubOptions;
97
  /** GitLab plugin configuration */
98
  gitlab?: GitLabOptions;
99
  /** Version plugin configuration */
100
  version?: VersionOptions;
101
  /** Hook commands configuration */
102
  hooks?: HooksOptions;
103
  /** Plugin loading and configuration */
104
  plugins?: PluginConfig;
105
}
106

107
interface GitOptions {
108
  /** Enable/disable Git plugin */
109
  disabled?: boolean;
110
  /** Require clean working directory */
111
  requireCleanWorkingDir?: boolean;
112
  /** Required branch pattern */
113
  requireBranch?: string | string[];
114
  /** Require upstream branch */
115
  requireUpstream?: boolean;
116
  /** Require commits since last tag */
117
  requireCommits?: boolean;
118
  /** Include untracked files when staging */
119
  addUntrackedFiles?: boolean;
120
  /** Enable commit creation */
121
  commit?: boolean;
122
  /** Commit message template */
123
  commitMessage?: string;
124
  /** Additional commit arguments */
125
  commitArgs?: string[];
126
  /** Enable tag creation */
127
  tag?: boolean;
128
  /** Tag annotation template */
129
  tagAnnotation?: string;
130
  /** Additional tag arguments */
131
  tagArgs?: string[];
132
  /** Enable push to remote */
133
  push?: boolean;
134
  /** Push repository or URL */
135
  pushRepo?: string;
136
  /** Additional push arguments */
137
  pushArgs?: string[];
138
}
139

140
interface NpmOptions {
141
  /** Enable/disable npm plugin */
142
  disabled?: boolean;
143
  /** Skip registry and authentication checks */
144
  skipChecks?: boolean;
145
  /** Ignore version in package.json */
146
  ignoreVersion?: boolean;
147
  /** Enable/disable publishing */
148
  publish?: boolean;
149
  /** npm tag for published version */
150
  tag?: string;
151
  /** One-time password for 2FA */
152
  otp?: string;
153
  /** Registry timeout in seconds */
154
  timeout?: number;
155
  /** Additional npm version arguments */
156
  versionArgs?: string[];
157
  /** Allow same version in npm version */
158
  allowSameVersion?: boolean;
159
  /** Path to publish (defaults to current directory) */
160
  publishPath?: string;
161
  /** Additional npm publish arguments */
162
  publishArgs?: string[];
163
}
164
```
165

166
### Configuration File Locations
167

168
Configuration files are searched in the following order:
169

170
1. CLI `--config` option
171
2. `.release-it.json`
172
3. `.release-it.js` 
173
4. `.release-it.yaml`
174
5. `.release-it.yml`
175
6. `package.json` (`release-it` property)
176

177
**Usage Examples:**
178

179
```javascript
180
import { Config } from "release-it";
181

182
// Create and initialize configuration
183
const config = new Config({
184
  increment: "minor",
185
  "dry-run": true
186
});
187

188
await config.init();
189

190
// Get configuration values
191
const isDryRun = config.isDryRun;
192
const gitOptions = config.getContext("git");
193
const commitMessage = config.getContext("git.commitMessage");
194

195
// Set context for templates
196
config.setContext({
197
  version: "1.2.0",
198
  changelog: "Bug fixes and improvements"
199
});
200

201
// Enable CI mode
202
config.setCI(true);
203
```
204

205
### Configuration File Examples
206

207
**JSON Configuration (`.release-it.json`):**
208

209
```json
210
{
211
  "git": {
212
    "requireCleanWorkingDir": true,
213
    "commitMessage": "Release ${version}",
214
    "tagAnnotation": "Release ${version}\\n\\n${changelog}",
215
    "push": true
216
  },
217
  "npm": {
218
    "publish": true,
219
    "skipChecks": false
220
  },
221
  "github": {
222
    "release": true,
223
    "assets": ["dist/*.zip"]
224
  },
225
  "hooks": {
226
    "before:init": "npm test",
227
    "after:release": "npm run deploy"
228
  }
229
}
230
```
231

232
**Package.json Configuration:**
233

234
```json
235
{
236
  "name": "my-package",
237
  "version": "1.0.0",
238
  "release-it": {
239
    "git": {
240
      "commitMessage": "chore: release v${version}"
241
    },
242
    "npm": {
243
      "publish": false
244
    }
245
  }
246
}
247
```
248

249
**JavaScript Configuration (`.release-it.js`):**
250

251
```javascript
252
module.exports = {
253
  git: {
254
    requireCleanWorkingDir: false,
255
    commitMessage: "Release ${version}",
256
    push: true
257
  },
258
  npm: {
259
    publish: true
260
  },
261
  hooks: {
262
    "before:init": ["npm test", "npm run lint"],
263
    "after:release": "echo Successfully released ${version}"
264
  }
265
};
266
```
267

268
### Environment Variables
269

270
Configuration can be influenced by environment variables:
271

272
- `CI=true` - Enables CI mode automatically
273
- `NODE_DEBUG=release-it` - Enables debug output
274
- Various npm environment variables for authentication
275

276
### Configuration Inheritance
277

278
Release It! supports configuration inheritance through the `extends` property:
279

280
```json
281
{
282
  "extends": "@company/release-config",
283
  "git": {
284
    "push": false
285
  }
286
}
287
```