0
# Plugin Lifecycle
1

2
Core semantic-release plugin interface functions that handle the complete release workflow from validation to post-release actions. These functions implement the semantic-release plugin specification and are called automatically by semantic-release during the release process.
3

4
## Capabilities
5

6
### Verify Conditions
7

8
Validates GitHub authentication, repository permissions, and plugin configuration before starting the release process.
9

10
```javascript { .api }
11
/**
12
 * Validates GitHub authentication and plugin configuration
13
 * @param pluginConfig - Plugin configuration options
14
 * @param context - semantic-release context with env, options, logger
15
 * @param options - Optional Octokit constructor override
16
 * @throws {AggregateError} When validation fails
17
 */
18
async function verifyConditions(
19
  pluginConfig: PluginConfig,
20
  context: Context,
21
  options?: { Octokit?: typeof Octokit }
22
): Promise<void>;
23
```
24

25
**Validation Checks:**
26
- GitHub token presence and validity
27
- Repository access permissions (push access required)
28
- Configuration option validation (assets, comments, labels, etc.)
29
- Repository URL format and accessibility
30
- GitHub Enterprise endpoint connectivity (if configured)
31

32
**Usage Example:**
33

34
```javascript
35
// Called automatically by semantic-release, but can be invoked directly
36
import { verifyConditions } from "@semantic-release/github";
37

38
await verifyConditions(
39
  {
40
    assets: ["dist/*.js"],
41
    successComment: "Released in ${nextRelease.version}",
42
    labels: ["semantic-release"]
43
  },
44
  {
45
    env: process.env,
46
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
47
    logger: console
48
  }
49
);
50
```
51

52
### Publish
53

54
Creates GitHub releases with optional asset uploads and discussion creation.
55

56
```javascript { .api }
57
/**
58
 * Creates GitHub releases and uploads assets
59
 * @param pluginConfig - Plugin configuration options
60
 * @param context - semantic-release context with release information
61
 * @param options - Optional Octokit constructor override
62
 * @returns Release information with URL, name, ID, and discussion URL
63
 */
64
async function publish(
65
  pluginConfig: PluginConfig,
66
  context: Context,
67
  options?: { Octokit?: typeof Octokit }
68
): Promise<ReleaseResult>;
69
```
70

71
**Features:**
72
- Creates GitHub releases with customizable names and body content
73
- Uploads file assets with glob pattern support
74
- Supports draft release creation
75
- Creates release discussions when configured
76
- Handles both prerelease and stable release types
77

78
**Usage Examples:**
79

80
```javascript
81
// Simple release without assets
82
const result = await publish(
83
  {},
84
  {
85
    env: process.env,
86
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
87
    branch: { name: "main" },
88
    nextRelease: {
89
      gitTag: "v1.0.0",
90
      name: "1.0.0",
91
      version: "1.0.0",
92
      notes: "## Changes\n- Initial release"
93
    },
94
    logger: console
95
  }
96
);
97
// Returns: { url: "https://github.com/owner/repo/releases/tag/v1.0.0", name: "GitHub release", id: 12345 }
98

99
// Release with assets and custom templates
100
const result = await publish(
101
  {
102
    assets: [
103
      { path: "dist/*.js", label: "JavaScript Distribution" },
104
      { path: "docs/*.pdf", label: "Documentation" }
105
    ],
106
    releaseNameTemplate: "${nextRelease.version} - ${nextRelease.channel || 'stable'}",
107
    releaseBodyTemplate: "## Release Notes\n${nextRelease.notes}\n\n## Assets\nSee attached files",
108
    discussionCategoryName: "Releases"
109
  },
110
  context
111
);
112
```
113

114
### Add Channel
115

116
Updates GitHub release pre-release status for channel management in semantic-release workflows.
117

118
```javascript { .api }
119
/**
120
 * Updates GitHub release pre-release status for channel management
121
 * @param pluginConfig - Plugin configuration options
122
 * @param context - semantic-release context with channel information
123
 * @param options - Optional Octokit constructor override
124
 * @returns Release information with URL and name
125
 */
126
async function addChannel(
127
  pluginConfig: PluginConfig,
128
  context: Context,
129
  options?: { Octokit?: typeof Octokit }
130
): Promise<ReleaseResult>;
131
```
132

133
**Behavior:**
134
- Updates existing releases to change prerelease status
135
- Creates new releases if none exist for the given tag
136
- Manages channel-specific release metadata
137
- Handles both promotion (prerelease → stable) and channel additions
138

139
**Usage Example:**
140

141
```javascript
142
// Promote a prerelease to stable
143
const result = await addChannel(
144
  {},
145
  {
146
    env: process.env,
147
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
148
    branch: { name: "main" },
149
    nextRelease: {
150
      gitTag: "v1.0.0",
151
      name: "1.0.0",
152
      notes: "Promoted to stable channel"
153
    },
154
    logger: console
155
  }
156
);
157
```
158

159
### Success
160

161
Comments on resolved issues and PRs after successful releases, providing users with release information and closure.
162

163
```javascript { .api }
164
/**
165
 * Comments on resolved issues and PRs after successful release
166
 * @param pluginConfig - Plugin configuration options  
167
 * @param context - semantic-release context with commits and release info
168
 * @param options - Optional Octokit constructor override
169
 */
170
async function success(
171
  pluginConfig: PluginConfig,
172
  context: Context,
173
  options?: { Octokit?: typeof Octokit }
174
): Promise<void>;
175
```
176

177
**Features:**
178
- Comments on issues and PRs referenced in commits
179
- Adds labels to resolved issues/PRs
180
- Supports conditional commenting based on configuration
181
- Closes previously opened failure issues
182
- Handles release link generation and formatting
183

184
**Usage Example:**
185

186
```javascript
187
await success(
188
  {
189
    successComment: "🎉 This issue has been resolved in version ${nextRelease.version}",
190
    successCommentCondition: "true", // Always comment
191
    releasedLabels: ["released", "v${nextRelease.version}"],
192
    labels: false // Don't add additional labels
193
  },
194
  {
195
    env: process.env,
196
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
197
    commits: [
198
      { hash: "abc123", message: "fix: resolve issue #42" }
199
    ],
200
    nextRelease: { version: "1.0.1", gitTag: "v1.0.1" },
201
    releases: [{ url: "https://github.com/owner/repo/releases/tag/v1.0.1" }],
202
    logger: console
203
  }
204
);
205
```
206

207
### Fail
208

209
Creates or updates GitHub issues when releases fail, providing detailed error information to maintainers.
210

211
```javascript { .api }
212
/**
213
 * Creates or updates GitHub issues when release fails
214
 * @param pluginConfig - Plugin configuration options
215
 * @param context - semantic-release context with error information
216
 * @param options - Optional Octokit constructor override
217
 */
218
async function fail(
219
  pluginConfig: PluginConfig,
220
  context: Context,
221
  options?: { Octokit?: typeof Octokit }
222
): Promise<void>;
223
```
224

225
**Features:**
226
- Creates detailed failure issues with error information
227
- Updates existing failure issues with new error details
228
- Supports conditional issue creation
229
- Assigns issues to specified maintainers
230
- Adds appropriate labels for issue categorization
231

232
**Usage Example:**
233

234
```javascript
235
await fail(
236
  {
237
    failTitle: "Automated release failed 🚨",
238
    failComment: "The release failed with the following error:\n\n${errors[0].message}",
239
    failCommentCondition: "true",
240
    assignees: ["maintainer1", "maintainer2"],
241
    labels: ["bug", "release-failure"]
242
  },
243
  {
244
    env: process.env,
245
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
246
    branch: { name: "main" },
247
    errors: [
248
      new Error("GitHub token expired")
249
    ],
250
    logger: console
251
  }
252
);
253
```
254

255
## Error Handling
256

257
All plugin lifecycle functions throw `AggregateError` instances containing one or more `SemanticReleaseError` objects when validation or execution fails. Common error scenarios include:
258

259
- **Authentication Issues**: Invalid or missing GitHub tokens
260
- **Permission Problems**: Insufficient repository access rights
261
- **Configuration Errors**: Invalid plugin configuration options  
262
- **Network Issues**: GitHub API connectivity problems
263
- **Rate Limiting**: GitHub API rate limit exceeded
264

265
```javascript
266
try {
267
  await verifyConditions(config, context);
268
} catch (error) {
269
  if (error instanceof AggregateError) {
270
    error.errors.forEach(err => {
271
      console.error(`${err.code}: ${err.message}`);
272
      console.error(err.details);
273
    });
274
  }
275
}
276
```