0
# GitHub Integration
1

2
The GitHub plugin provides comprehensive GitHub integration including release creation, asset uploads, and repository operations. It supports authentication, release notes generation, and asset management.
3

4
## Capabilities
5

6
### GitHub Plugin Class
7

8
Main GitHub integration plugin for release and repository operations.
9

10
```javascript { .api }
11
/**
12
 * GitHub integration plugin for releases and repository operations
13
 * Handles GitHub releases, asset uploads, and repository integration
14
 */
15
class GitHub extends Plugin {
16
  /** Initialize GitHub plugin with authentication and repository validation */
17
  init(): Promise<void>;
18
  
19
  /** Authentication and validation */
20
  isAuthenticated(): Promise<boolean>;
21
  isCollaborator(): Promise<boolean>;
22
  
23
  /** Get latest version from GitHub releases */
24
  getLatestVersion(): Promise<string>;
25
  
26
  /** Get changelog from GitHub commits and pull requests */
27
  getChangelog(): Promise<string>;
28
  
29
  /**
30
   * Create GitHub release
31
   * @returns Promise resolving to boolean indicating success
32
   */
33
  release(): Promise<boolean>;
34
  
35
  /** Log release URL after successful release */
36
  afterRelease(): void;
37
  
38
  /** Release management */
39
  createRelease(): Promise<Release>;
40
  updateRelease(): Promise<boolean>;
41
  getLatestRelease(): Promise<Release>;
42
  createWebRelease(): Promise<void>;
43
  generateWebUrl(): Promise<string>;
44
  
45
  /** Asset management */
46
  uploadAsset(filePath: string): Promise<any>;
47
  uploadAssets(): Promise<void>;
48
  
49
  /** Repository information */
50
  getWebUrl(): string;
51
  getReleaseUrlFallback(tagName: string): string;
52
  
53
  /** Comments and interaction */
54
  commentOnResolvedItems(): Promise<void>;
55
  getCommits(): Promise<any[]>;
56
  renderReleaseNotes(releaseNotes: any): Promise<string>;
57
  
58
  /** Client and utilities */
59
  get client(): any;
60
  retry(fn: () => Promise<any>): Promise<any>;
61
  handleError(err: any, bail: boolean): void;
62
  getOctokitReleaseOptions(options?: any): Promise<any>;
63
}
64
```
65

66
### Release Operations
67

68
Methods for creating and managing GitHub releases.
69

70
```javascript { .api }
71
/**
72
 * Create GitHub release with notes and assets
73
 * @param options - Release creation options
74
 * @returns Promise resolving to GitHub release object
75
 */
76
createRelease(options: CreateReleaseOptions): Promise<GitHubRelease>;
77

78
/**
79
 * Upload assets to existing GitHub release
80
 * @param releaseId - GitHub release ID
81
 * @param assets - Array of asset file paths or glob patterns
82
 * @returns Promise that resolves when all assets are uploaded
83
 */
84
uploadAssets(releaseId: number, assets: string[]): Promise<void>;
85

86
/**
87
 * Get GitHub release by tag name
88
 * @param tag - Git tag name
89
 * @returns Promise resolving to release object or null if not found
90
 */
91
getReleaseByTag(tag: string): Promise<GitHubRelease | null>;
92

93
/**
94
 * Update existing GitHub release
95
 * @param releaseId - GitHub release ID
96
 * @param options - Update options
97
 * @returns Promise resolving to updated release object
98
 */
99
updateRelease(releaseId: number, options: UpdateReleaseOptions): Promise<GitHubRelease>;
100

101
interface CreateReleaseOptions extends ReleaseOptions {
102
  /** Release tag name */
103
  tag_name: string;
104
  /** Release name/title */
105
  name?: string;
106
  /** Release description/body */
107
  body?: string;
108
  /** Whether this is a draft release */
109
  draft?: boolean;
110
  /** Whether this is a pre-release */
111
  prerelease?: boolean;
112
  /** Commit SHA or branch name for release */
113
  target_commitish?: string;
114
}
115

116
interface UpdateReleaseOptions {
117
  /** Updated release name */
118
  name?: string;
119
  /** Updated release body */
120
  body?: string;
121
  /** Updated draft status */
122
  draft?: boolean;
123
  /** Updated pre-release status */
124
  prerelease?: boolean;
125
}
126

127
interface GitHubRelease {
128
  /** Release ID */
129
  id: number;
130
  /** Release tag name */
131
  tag_name: string;
132
  /** Release name */
133
  name: string;
134
  /** Release body/description */
135
  body: string;
136
  /** Draft status */
137
  draft: boolean;
138
  /** Pre-release status */
139
  prerelease: boolean;
140
  /** Release HTML URL */
141
  html_url: string;
142
  /** Upload URL for assets */
143
  upload_url: string;
144
  /** Array of release assets */
145
  assets: GitHubAsset[];
146
}
147

148
interface GitHubAsset {
149
  /** Asset ID */
150
  id: number;
151
  /** Asset name */
152
  name: string;
153
  /** Asset download URL */
154
  browser_download_url: string;
155
  /** Asset size in bytes */
156
  size: number;
157
  /** Asset content type */
158
  content_type: string;
159
}
160
```
161

162
### Repository Information
163

164
Methods for retrieving GitHub repository information and URLs.
165

166
```javascript { .api }
167
/**
168
 * Get GitHub repository web URL
169
 * @returns Repository web URL string
170
 */
171
getWebUrl(): string;
172

173
/**
174
 * Get GitHub repository API URL  
175
 * @returns Repository API URL string
176
 */
177
getApiUrl(): string;
178

179
/**
180
 * Get GitHub repository information
181
 * @returns Promise resolving to repository object
182
 */
183
getRepository(): Promise<GitHubRepository>;
184

185
/**
186
 * Get GitHub repository owner and name
187
 * @returns Object with owner and repository name
188
 */
189
getRepositoryInfo(): { owner: string; repo: string };
190

191
interface GitHubRepository {
192
  /** Repository ID */
193
  id: number;
194
  /** Repository name */
195
  name: string;
196
  /** Repository full name (owner/repo) */
197
  full_name: string;
198
  /** Repository description */
199
  description: string;
200
  /** Repository HTML URL */
201
  html_url: string;
202
  /** Repository clone URL */
203
  clone_url: string;
204
  /** Repository SSH URL */
205
  ssh_url: string;
206
  /** Default branch name */
207
  default_branch: string;
208
  /** Repository visibility */
209
  private: boolean;
210
}
211
```
212

213
### Asset Management
214

215
Methods for handling release assets including file uploads and validation.
216

217
```javascript { .api }
218
/**
219
 * Validate and resolve asset file paths
220
 * @param assets - Array of file paths or glob patterns
221
 * @returns Promise resolving to array of resolved file paths
222
 */
223
resolveAssets(assets: string[]): Promise<string[]>;
224

225
/**
226
 * Upload single asset file to release
227
 * @param uploadUrl - GitHub upload URL from release
228
 * @param filePath - Path to asset file
229
 * @returns Promise resolving to uploaded asset object
230
 */
231
uploadAsset(uploadUrl: string, filePath: string): Promise<GitHubAsset>;
232

233
/**
234
 * Get MIME type for asset file
235
 * @param filePath - Path to asset file
236
 * @returns MIME type string
237
 */
238
getAssetContentType(filePath: string): string;
239
```
240

241
### Authentication and Configuration
242

243
GitHub plugin authentication and configuration options.
244

245
```javascript { .api }
246
interface GitHubOptions {
247
  /** Enable/disable GitHub plugin entirely */
248
  disabled?: boolean;
249
  
250
  /** Enable/disable GitHub release creation */
251
  release?: boolean;
252
  
253
  /** GitHub personal access token for authentication */
254
  token?: string;
255
  
256
  /** Release name template (supports context interpolation) */
257
  releaseName?: string;
258
  
259
  /** Release body/notes template (supports context interpolation) */
260
  releaseNotes?: string;
261
  
262
  /** Create draft release (default: false) */
263
  draft?: boolean;
264
  
265
  /** Mark as pre-release for pre-release versions (default: auto-detect) */
266
  preRelease?: boolean;
267
  
268
  /** Auto-generate release notes using GitHub's API */
269
  autoGenerate?: boolean;
270
  
271
  /** Asset files to upload (file paths or glob patterns) */
272
  assets?: string[];
273
  
274
  /** GitHub API host (for GitHub Enterprise) */
275
  host?: string;
276
  
277
  /** GitHub API path prefix (for GitHub Enterprise) */
278
  pathPrefix?: string;
279
  
280
  /** HTTP proxy configuration */
281
  proxy?: string;
282
  
283
  /** Request timeout in milliseconds */
284
  timeout?: number;
285
  
286
  /** Number of retry attempts for failed requests */
287
  retries?: number;
288
  
289
  /** Minimum timeout between retries in milliseconds */
290
  retryMinTimeout?: number;
291
  
292
  /** Update existing release if tag already exists */
293
  update?: boolean;
294
  
295
  /** Comments configuration for issue/PR processing */
296
  comments?: {
297
    /** Submit comments on resolved issues */
298
    submit?: boolean;
299
    /** Include resolved issues in release notes */
300
    issue?: string;
301
    /** Include merged PRs in release notes */
302
    pr?: string;
303
  };
304
  
305
  /** Web configuration */
306
  web?: boolean;
307
}
308
```
309

310
**Usage Examples:**
311

312
```javascript
313
// Basic GitHub release configuration
314
const result = await runTasks({
315
  github: {
316
    release: true,
317
    releaseName: "Release ${version}",
318
    assets: ["dist/*.zip", "docs/*.pdf"]
319
  }
320
});
321

322
// Advanced GitHub configuration with custom templates
323
const result = await runTasks({
324
  github: {
325
    release: true,
326
    releaseName: "🚀 ${name} v${version}",
327
    releaseNotes: "## Changes\n\n${changelog}\n\n## Installation\n\nnpm install ${name}@${version}",
328
    draft: false,
329
    preRelease: false,
330
    assets: [
331
      "dist/bundle.min.js",
332
      "dist/bundle.min.css",
333
      "docs/api.md"
334
    ],
335
    autoGenerate: true,
336
    update: true
337
  }
338
});
339

340
// GitHub Enterprise configuration
341
const result = await runTasks({
342
  github: {
343
    release: true,
344
    token: process.env.GITHUB_TOKEN,
345
    host: "github.internal.company.com",
346
    pathPrefix: "/api/v3",
347
    proxy: "http://proxy.company.com:8080"
348
  }
349
});
350

351
// GitHub with issue/PR comments
352
const result = await runTasks({
353
  github: {
354
    release: true,
355
    comments: {
356
      submit: true,
357
      issue: "Released in ${version}: ${releaseUrl}",
358
      pr: "🎉 Merged PR is now available in ${version}"
359
    }
360
  }
361
});
362
```
363

364
### Authentication Methods
365

366
The GitHub plugin supports multiple authentication methods:
367

368
1. **Environment Variable**: `GITHUB_TOKEN` environment variable
369
2. **Configuration**: `token` property in GitHub options
370
3. **GitHub CLI**: Automatic token discovery from `gh` CLI
371
4. **Git Credentials**: Integration with Git credential helpers
372

373
### Asset Upload Features
374

375
The GitHub plugin provides sophisticated asset management:
376

377
- **Glob Pattern Support**: Use patterns like `dist/*.zip` to match multiple files
378
- **MIME Type Detection**: Automatic content type detection for uploaded files
379
- **Progress Reporting**: Upload progress feedback for large files
380
- **Retry Logic**: Automatic retry for failed uploads with exponential backoff
381
- **Parallel Uploads**: Concurrent asset uploads for better performance
382

383
### Release Notes Generation
384

385
Release notes can be generated through multiple methods:
386

387
1. **Changelog Integration**: Use generated changelog content
388
2. **Auto-generation**: GitHub's automatic release notes API
389
3. **Custom Templates**: Template-based notes with context interpolation
390
4. **Issue/PR Integration**: Include resolved issues and merged PRs
391

392
### Context Variables
393

394
The GitHub plugin provides additional context variables:
395

396
- `${releaseUrl}` - URL of created GitHub release
397
- `${releaseId}` - GitHub release ID
398
- `${repo.owner}` - Repository owner
399
- `${repo.repository}` - Repository name
400
- `${repo.host}` - GitHub host (for GitHub Enterprise)
401

402
### Error Handling
403

404
The GitHub plugin includes comprehensive error handling:
405

406
- **Authentication Errors**: Clear feedback for token issues
407
- **Rate Limiting**: Automatic retry with backoff for rate limits
408
- **Network Issues**: Timeout and retry logic for API calls
409
- **Asset Upload Failures**: Individual asset retry without affecting others
410
- **Release Conflicts**: Handling of existing releases and updates