0
# @semantic-release/github
1

2
@semantic-release/github is a semantic-release plugin that integrates with GitHub's release system to automate the publishing of GitHub releases and provide intelligent commenting on pull requests and issues. It implements the complete semantic-release plugin lifecycle with GitHub-specific functionality including release creation, asset uploads, issue/PR commenting, and error handling.
3

4
## Package Information
5

6
- **Package Name**: @semantic-release/github
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install @semantic-release/github -D`
10

11
## Core Imports
12

13
```javascript
14
import { verifyConditions, publish, addChannel, success, fail } from "@semantic-release/github";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { verifyConditions, publish, addChannel, success, fail } = require("@semantic-release/github");
21
```
22

23
## Basic Usage
24

25
```javascript
26
// semantic-release configuration
27
{
28
  "plugins": [
29
    "@semantic-release/commit-analyzer",
30
    "@semantic-release/release-notes-generator",
31
    [
32
      "@semantic-release/github",
33
      {
34
        "assets": [
35
          { "path": "dist/asset.min.css", "label": "CSS distribution" },
36
          { "path": "dist/asset.min.js", "label": "JS distribution" }
37
        ],
38
        "successComment": "🎉 This issue has been resolved in version ${nextRelease.version}",
39
        "failTitle": "Release failed 🚨",
40
        "labels": ["semantic-release", "automated"],
41
        "assignees": ["maintainer"]
42
      }
43
    ]
44
  ]
45
}
46
```
47

48
## Architecture
49

50
@semantic-release/github is built around several key components:
51

52
- **Plugin Lifecycle**: Implements the five semantic-release plugin hooks (verifyConditions, publish, addChannel, success, fail)
53
- **GitHub Integration**: Uses Octokit with retry, throttling, and pagination for robust GitHub API interactions  
54
- **Configuration System**: Flexible configuration with environment variable fallbacks and validation
55
- **Asset Management**: Supports glob patterns and metadata for release asset uploads
56
- **Template System**: Lodash templates for customizable comments and release content
57
- **Error Handling**: Comprehensive error types with detailed documentation links
58

59
## Capabilities
60

61
### Plugin Lifecycle Functions
62

63
Core semantic-release plugin interface functions that handle the complete release workflow from validation to post-release actions.
64

65
```javascript { .api }
66
async function verifyConditions(
67
  pluginConfig: PluginConfig,
68
  context: Context,
69
  options?: { Octokit?: typeof Octokit }
70
): Promise<void>;
71

72
async function publish(
73
  pluginConfig: PluginConfig,
74
  context: Context,
75
  options?: { Octokit?: typeof Octokit }
76
): Promise<ReleaseResult>;
77

78
async function addChannel(
79
  pluginConfig: PluginConfig,
80
  context: Context,
81
  options?: { Octokit?: typeof Octokit }
82
): Promise<ReleaseResult>;
83

84
async function success(
85
  pluginConfig: PluginConfig,
86
  context: Context,
87
  options?: { Octokit?: typeof Octokit }
88
): Promise<void>;
89

90
async function fail(
91
  pluginConfig: PluginConfig,
92
  context: Context,
93
  options?: { Octokit?: typeof Octokit }
94
): Promise<void>;
95
```
96

97
[Plugin Lifecycle](./plugin-lifecycle.md)
98

99
### GitHub Integration
100

101
GitHub API integration utilities for authentication, configuration, and Octokit setup with enhanced reliability.
102

103
```javascript { .api }
104
class SemanticReleaseOctokit extends Octokit {
105
  // Pre-configured with retry, throttling, and pagination plugins
106
}
107

108
function toOctokitOptions(options: GitHubOptions): OctokitOptions;
109

110
interface GitHubOptions {
111
  githubToken: string;
112
  githubUrl?: string;
113
  githubApiPathPrefix?: string;
114
  githubApiUrl?: string;
115
  proxy?: ProxyConfig | false;
116
}
117
```
118

119
[GitHub Integration](./github-integration.md)
120

121
### Configuration Management
122

123
Configuration resolution system that merges plugin options with environment variables and applies sensible defaults.
124

125
```javascript { .api }
126
function resolveConfig(
127
  pluginConfig: PluginConfig,
128
  context: { env: NodeJS.ProcessEnv }
129
): ResolvedConfig;
130

131
interface PluginConfig {
132
  githubUrl?: string;
133
  githubApiUrl?: string;
134
  githubApiPathPrefix?: string;
135
  proxy?: ProxyConfig | false;
136
  assets?: AssetConfig[];
137
  successComment?: string | false;
138
  successCommentCondition?: string | false;
139
  failTitle?: string | false;
140
  failComment?: string | false;
141
  failCommentCondition?: string | false;
142
  labels?: string[] | false;
143
  assignees?: string[];
144
  releasedLabels?: string[] | false;
145
  addReleases?: "top" | "bottom" | false;
146
  draftRelease?: boolean;
147
  releaseNameTemplate?: string;
148
  releaseBodyTemplate?: string;
149
  discussionCategoryName?: string | false;
150
}
151
```
152

153
[Configuration](./configuration.md)
154

155
### Asset Management
156

157
File asset handling system supporting glob patterns, metadata, and upload management for GitHub releases.
158

159
```javascript { .api }
160
async function globAssets(
161
  context: { cwd: string },
162
  assets: AssetConfig[]
163
): Promise<ResolvedAsset[]>;
164

165
type AssetConfig = string | {
166
  path: string | string[];
167
  name?: string;
168
  label?: string;
169
};
170

171
interface ResolvedAsset {
172
  path: string;
173
  name?: string;
174
  label?: string;
175
}
176
```
177

178
[Asset Management](./asset-management.md)
179

180
### Utility Functions
181

182
Helper functions for URL parsing, templating, error handling, and GitHub-specific operations.
183

184
```javascript { .api }
185
function parseGitHubUrl(repositoryUrl: string): { owner?: string; repo?: string };
186

187
function getSuccessComment(successComment: string, context: Context): string;
188

189
function getFailComment(failComment: string, context: Context): string;
190

191
function getReleaseLinks(releases: Release[]): string;
192

193
async function findSRIssues(
194
  octokit: Octokit,
195
  params: { owner: string; repo: string }
196
): Promise<Issue[]>;
197

198
function getError(code: string, context?: any): SemanticReleaseError;
199
```
200

201
[Utilities](./utilities.md)
202

203
## Types
204

205
```javascript { .api }
206
interface Context {
207
  env: NodeJS.ProcessEnv;
208
  options: { repositoryUrl: string; publish?: any[] };
209
  branch: { name: string };
210
  nextRelease?: {
211
    gitTag: string;
212
    name: string;
213
    version: string;
214
    notes: string;
215
    channel?: string;
216
  };
217
  commits?: Commit[];
218
  releases?: Release[];
219
  logger: Logger;
220
}
221

222
interface ReleaseResult {
223
  url: string;
224
  name: string;
225
  id: number;
226
  discussion_url?: string;
227
}
228

229
interface ProxyConfig {
230
  host: string;
231
  port: number;
232
  headers?: Record<string, string>;
233
}
234

235
interface Logger {
236
  log(message: string, ...args: any[]): void;
237
  warn(message: string, ...args: any[]): void;
238
  error(message: string, ...args: any[]): void;
239
}
240

241
interface SemanticReleaseError extends Error {
242
  name: string;
243
  message: string;
244
  details: string;
245
  code: string;
246
}
247
```