0
# Configuration
1

2
Configuration resolution system that merges plugin options with environment variables and applies sensible defaults. The configuration system provides flexibility while maintaining backwards compatibility and security best practices.
3

4
## Capabilities
5

6
### Resolve Configuration
7

8
Main configuration resolution function that processes plugin options and environment variables into a unified configuration object.
9

10
```javascript { .api }
11
/**
12
 * Resolves plugin configuration with environment variable fallbacks
13
 * @param pluginConfig - Raw plugin configuration from semantic-release
14
 * @param context - Contains environment variables and semantic-release context
15
 * @returns Fully resolved configuration with defaults applied
16
 */
17
function resolveConfig(
18
  pluginConfig: PluginConfig,
19
  context: { env: NodeJS.ProcessEnv }
20
): ResolvedConfig;
21
```
22

23
**Resolution Priority (highest to lowest):**
24
1. Explicit plugin configuration values
25
2. Environment variables
26
3. Built-in defaults
27

28
**Usage Example:**
29

30
```javascript
31
import resolveConfig from "@semantic-release/github/lib/resolve-config.js";
32

33
const config = resolveConfig(
34
  {
35
    assets: ["dist/*.js"],
36
    successComment: "Released in ${nextRelease.version}",
37
    labels: ["automated-release"]
38
  },
39
  {
40
    env: {
41
      GITHUB_TOKEN: "ghp_xxxxxxxxxxxx",
42
      GH_URL: "https://github.company.com",
43
      HTTP_PROXY: "http://proxy:8080"
44
    }
45
  }
46
);
47

48
// Result includes resolved values with environment variable fallbacks
49
console.log(config.githubToken); // "ghp_xxxxxxxxxxxx"
50
console.log(config.githubUrl);   // "https://github.company.com"  
51
console.log(config.proxy);       // "http://proxy:8080"
52
```
53

54
### Plugin Configuration Options
55

56
Complete plugin configuration interface with all available options and their types.
57

58
```javascript { .api }
59
interface PluginConfig {
60
  /** GitHub server URL (for GitHub Enterprise) */
61
  githubUrl?: string;
62
  
63
  /** Full GitHub API URL (overrides githubUrl + prefix) */
64
  githubApiUrl?: string;
65
  
66
  /** GitHub API path prefix relative to githubUrl */
67
  githubApiPathPrefix?: string;
68
  
69
  /** HTTP proxy configuration or false to disable */
70
  proxy?: ProxyConfig | false;
71
  
72
  /** Files to upload as release assets */
73
  assets?: AssetConfig[];
74
  
75
  /** Comment template for successful releases, or false to disable */
76
  successComment?: string | false;
77
  
78
  /** Condition for when to add success comments */
79
  successCommentCondition?: string | false;
80
  
81
  /** Title for failure issues, or false to disable */
82
  failTitle?: string | false;
83
  
84
  /** Comment template for failure issues, or false to disable */
85
  failComment?: string | false;
86
  
87
  /** Condition for when to create failure issues */
88
  failCommentCondition?: string | false;
89
  
90
  /** Labels to add to failure issues, or false to disable */
91
  labels?: string[] | false;
92
  
93
  /** Users to assign to failure issues */
94
  assignees?: string[];
95
  
96
  /** Labels to add to resolved issues/PRs, or false to disable */
97
  releasedLabels?: string[] | false;
98
  
99
  /** Where to add release information in existing releases */
100
  addReleases?: "top" | "bottom" | false;
101
  
102
  /** Whether to create draft releases */
103
  draftRelease?: boolean;
104
  
105
  /** Template for release names */
106
  releaseNameTemplate?: string;
107
  
108
  /** Template for release body content */
109
  releaseBodyTemplate?: string;
110
  
111
  /** GitHub discussion category for releases, or false to disable */
112
  discussionCategoryName?: string | false;
113
}
114

115
type AssetConfig = string | {
116
  path: string | string[];
117
  name?: string;
118
  label?: string;
119
};
120

121
interface ProxyConfig {
122
  host: string;
123
  port: number;
124
  secureProxy?: boolean;
125
  headers?: Record<string, string>;
126
}
127
```
128

129
### Resolved Configuration
130

131
The complete resolved configuration object returned by `resolveConfig()`.
132

133
```javascript { .api }
134
interface ResolvedConfig {
135
  /** GitHub authentication token from GH_TOKEN or GITHUB_TOKEN */
136
  githubToken: string;
137
  
138
  /** GitHub server URL with environment variable fallback */
139
  githubUrl?: string;
140
  
141
  /** GitHub API path prefix with environment variable fallback */
142
  githubApiPathPrefix: string;
143
  
144
  /** GitHub API URL with environment variable fallback */
145
  githubApiUrl?: string;
146
  
147
  /** Resolved proxy configuration */
148
  proxy: ProxyConfig | false;
149
  
150
  /** Processed asset configurations */
151
  assets?: AssetConfig[];
152
  
153
  /** Success comment template */
154
  successComment?: string | false;
155
  
156
  /** Success comment condition */
157
  successCommentCondition?: string | false;
158
  
159
  /** Failure issue title */
160
  failTitle: string | false;
161
  
162
  /** Failure comment template */
163
  failComment?: string | false;
164
  
165
  /** Failure comment condition */
166
  failCommentCondition?: string | false;
167
  
168
  /** Issue labels */
169
  labels: string[] | false;
170
  
171
  /** Issue assignees */
172
  assignees?: string[];
173
  
174
  /** Released issue/PR labels */
175
  releasedLabels: string[] | false;
176
  
177
  /** Release information positioning */
178
  addReleases: "top" | "bottom" | false;
179
  
180
  /** Draft release flag */
181
  draftRelease: boolean;
182
  
183
  /** Release body template */
184
  releaseBodyTemplate: string;
185
  
186
  /** Release name template */
187
  releaseNameTemplate: string;
188
  
189
  /** Discussion category name */
190
  discussionCategoryName: string | false;
191
}
192
```
193

194
### Environment Variables
195

196
Complete list of supported environment variables with their purposes and fallbacks.
197

198
```javascript { .api }
199
// Authentication (required)
200
process.env.GITHUB_TOKEN  // Primary GitHub token
201
process.env.GH_TOKEN      // Alternative GitHub token
202

203
// GitHub Enterprise endpoints
204
process.env.GITHUB_URL    // GitHub server URL
205
process.env.GH_URL        // Alternative GitHub server URL
206
process.env.GITHUB_PREFIX // API path prefix
207
process.env.GH_PREFIX     // Alternative API path prefix
208
process.env.GITHUB_API_URL // Full API URL (overrides URL + prefix)
209

210
// Network configuration
211
process.env.HTTP_PROXY    // HTTP proxy URL
212
process.env.http_proxy    // Alternative HTTP proxy URL (lowercase)
213
```
214

215
**Environment Variable Examples:**
216

217
```bash
218
# GitHub.com (default)
219
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
220

221
# GitHub Enterprise with separate URL and prefix
222
export GITHUB_TOKEN="ghs_xxxxxxxxxxxx"
223
export GITHUB_URL="https://github.company.com"
224
export GITHUB_PREFIX="/api/v3"
225

226
# GitHub Enterprise with direct API URL
227
export GITHUB_TOKEN="ghs_xxxxxxxxxxxx"
228
export GITHUB_API_URL="https://api.github.company.com/v3"
229

230
# With proxy
231
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
232
export HTTP_PROXY="http://proxy.company.com:8080"
233
```
234

235
### Default Values
236

237
Built-in default values applied when no explicit configuration or environment variables are provided.
238

239
```javascript { .api }
240
const DEFAULTS = {
241
  // GitHub API
242
  githubApiPathPrefix: "",        // Empty prefix for GitHub.com
243
  proxy: false,                   // No proxy by default
244
  
245
  // Release management
246
  draftRelease: false,            // Create published releases
247
  releaseBodyTemplate: "<%= nextRelease.notes %>",
248
  releaseNameTemplate: "<%= nextRelease.name %>",
249
  discussionCategoryName: false,  // No discussions by default
250
  
251
  // Issue/PR management
252
  failTitle: "The automated release is failing 🚨",
253
  labels: ["semantic-release"],   // Default failure issue labels
254
  releasedLabels: [              // Default released labels with template
255
    "released<%= nextRelease.channel ? ` on @${nextRelease.channel}` : \"\" %>"
256
  ],
257
  addReleases: false,            // Don't modify existing releases
258
  
259
  // Comments (no defaults - explicitly configured or disabled)
260
  successComment: undefined,      // Must be explicitly set
261
  failComment: undefined,         // Must be explicitly set
262
  assets: undefined,             // No assets by default
263
  assignees: undefined           // No assignees by default
264
};
265
```
266

267
### Template System
268

269
Configuration supports Lodash templates for dynamic content generation using semantic-release context.
270

271
```javascript { .api }
272
// Available template variables from semantic-release context:
273
interface TemplateContext {
274
  nextRelease: {
275
    version: string;      // "1.0.0"
276
    gitTag: string;       // "v1.0.0" 
277
    name: string;         // "1.0.0"
278
    notes: string;        // Release notes markdown
279
    channel?: string;     // Release channel name
280
  };
281
  branch: {
282
    name: string;         // "main"
283
    channel?: string;     // Channel name if different from branch
284
  };
285
  lastRelease?: {
286
    version: string;
287
    gitTag: string;
288
  };
289
  commits: Array<{
290
    hash: string;
291
    message: string;
292
  }>;
293
  errors?: Error[];       // Available in failure templates
294
}
295
```
296

297
**Template Examples:**
298

299
```javascript
300
{
301
  // Release templates
302
  releaseNameTemplate: "Release ${nextRelease.version}",
303
  releaseBodyTemplate: `
304
## What's Changed
305
${nextRelease.notes}
306

307
## Installation
308
\`npm install package@${nextRelease.version}\`
309
  `,
310
  
311
  // Comment templates  
312
  successComment: `
313
🎉 This issue has been resolved in version ${nextRelease.version}
314

315
The release is available on:
316
- [GitHub release](${releases[0].url})
317
- [npm package](https://www.npmjs.com/package/package/v/${nextRelease.version})
318
  `,
319
  
320
  failComment: `
321
❌ The automated release from \`${branch.name}\` branch failed.
322

323
**Error Details:**
324
${errors.map(error => \`- \${error.message}\`).join('\\n')}
325
  `,
326
  
327
  // Dynamic labels
328
  releasedLabels: [
329
    "released",
330
    "v${nextRelease.version}",
331
    "channel-${nextRelease.channel || 'default'}"
332
  ]
333
}
334
```
335

336
### Configuration Validation
337

338
All configuration options are validated before use, with detailed error messages for invalid values.
339

340
```javascript
341
// Validation rules applied:
342
{
343
  proxy: "String URL or Object with host/port, or false",
344
  assets: "Array of strings or objects with path property",
345
  successComment: "Non-empty string or false",
346
  failTitle: "Non-empty string or false", 
347
  failComment: "Non-empty string or false",
348
  labels: "Array of non-empty strings or false",
349
  assignees: "Array of non-empty strings",
350
  releasedLabels: "Array of non-empty strings or false",
351
  addReleases: "One of: false, 'top', 'bottom'",
352
  draftRelease: "Boolean",
353
  releaseBodyTemplate: "Non-empty string",
354
  releaseNameTemplate: "Non-empty string",
355
  discussionCategoryName: "Non-empty string or false"
356
}
357
```
358

359
**Configuration Error Handling:**
360

361
```javascript
362
import { verifyConditions } from "@semantic-release/github";
363

364
try {
365
  await verifyConditions({
366
    assets: "invalid-type", // Should be array
367
    labels: [123],          // Should be strings
368
    proxy: "not-a-url"      // Invalid proxy format
369
  }, context);
370
} catch (error) {
371
  // AggregateError with detailed validation errors
372
  error.errors.forEach(err => {
373
    console.log(err.code);    // "EINVALIDASSETS", "EINVALIDLABELS", etc.
374
    console.log(err.message); // Human-readable error message  
375
    console.log(err.details); // Detailed explanation with examples
376
  });
377
}
378
```