0
# GitHub Integration
1

2
GitHub API integration utilities providing authentication, configuration, and Octokit setup with enhanced reliability features. These utilities handle the low-level GitHub API interactions used by all plugin lifecycle functions.
3

4
## Capabilities
5

6
### Semantic Release Octokit
7

8
Pre-configured Octokit instance with retry, throttling, and pagination plugins for robust GitHub API interactions.
9

10
```javascript { .api }
11
/**
12
 * Enhanced Octokit class with semantic-release optimizations
13
 * Includes retry logic, rate limiting, and pagination support
14
 */
15
class SemanticReleaseOctokit extends Octokit {
16
  // Inherited from Octokit with added plugins:
17
  // - @octokit/plugin-retry
18
  // - @octokit/plugin-throttling  
19
  // - @octokit/plugin-paginate-rest
20
}
21
```
22

23
**Built-in Features:**
24
- **Automatic Retries**: Retries failed requests with exponential backoff
25
- **Rate Limit Handling**: Automatically waits when rate limits are hit
26
- **Request Throttling**: Prevents overwhelming the GitHub API
27
- **Pagination Support**: Automatically handles paginated responses
28
- **Custom User Agent**: Identifies requests as coming from semantic-release/github
29

30
**Default Configuration:**
31
- Maximum 3 retries for failed requests
32
- Exponential backoff starting at 1 second
33
- Automatic rate limit detection and waiting
34
- Custom user agent: `@semantic-release/github v{version}`
35

36
**Usage Example:**
37

38
```javascript
39
import { SemanticReleaseOctokit } from "@semantic-release/github/lib/octokit.js";
40

41
const octokit = new SemanticReleaseOctokit({
42
  auth: process.env.GITHUB_TOKEN,
43
  baseUrl: "https://api.github.com" // Optional for GitHub Enterprise
44
});
45

46
// Automatic retry and rate limiting
47
const { data: releases } = await octokit.request("GET /repos/{owner}/{repo}/releases", {
48
  owner: "semantic-release",
49
  repo: "github"
50
});
51

52
// Automatic pagination
53
const allIssues = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
54
  owner: "semantic-release",
55
  repo: "github",
56
  state: "all"
57
});
58
```
59

60
### Octokit Options Conversion
61

62
Converts plugin configuration options into Octokit constructor options with proper authentication and proxy setup.
63

64
```javascript { .api }
65
/**
66
 * Converts plugin options to Octokit constructor options
67
 * @param options - GitHub connection and authentication options
68
 * @returns Octokit-compatible options object
69
 */
70
function toOctokitOptions(options: GitHubOptions): OctokitOptions;
71

72
interface GitHubOptions {
73
  /** GitHub personal access token or GitHub App token */
74
  githubToken: string;
75
  /** GitHub server URL (for GitHub Enterprise) */
76
  githubUrl?: string;
77
  /** API path prefix relative to githubUrl */
78
  githubApiPathPrefix?: string;
79
  /** Full GitHub API URL (overrides githubUrl + prefix) */
80
  githubApiUrl?: string;
81
  /** HTTP proxy configuration or false to disable */
82
  proxy?: ProxyConfig | false;
83
}
84

85
interface OctokitOptions {
86
  /** Authentication token */
87
  auth: string;
88
  /** GitHub API base URL */
89
  baseUrl?: string;
90
  /** Request configuration including proxy agent */
91
  request: {
92
    agent?: HttpProxyAgent | HttpsProxyAgent;
93
  };
94
}
95

96
interface ProxyConfig {
97
  /** Proxy host */
98
  host: string;
99
  /** Proxy port */
100
  port: number;
101
  /** Additional proxy headers */
102
  headers?: Record<string, string>;
103
}
104
```
105

106
**URL Resolution Logic:**
107
1. If `githubApiUrl` is provided, use it directly as `baseUrl`
108
2. If `githubUrl` is provided, combine with `githubApiPathPrefix` (default: "")
109
3. Otherwise, use GitHub.com (default Octokit behavior)
110

111
**Proxy Support:**
112
- Automatically detects HTTP vs HTTPS based on API URL protocol
113
- Uses `HttpProxyAgent` for HTTP endpoints
114
- Uses `HttpsProxyAgent` for HTTPS endpoints
115
- Supports proxy authentication and custom headers
116

117
**Usage Examples:**
118

119
```javascript
120
import { toOctokitOptions, SemanticReleaseOctokit } from "@semantic-release/github/lib/octokit.js";
121

122
// GitHub.com with proxy
123
const options = toOctokitOptions({
124
  githubToken: "ghp_xxxxxxxxxxxx",
125
  proxy: {
126
    host: "proxy.company.com",
127
    port: 8080,
128
    headers: { "Proxy-Authorization": "Basic xyz" }
129
  }
130
});
131

132
const octokit = new SemanticReleaseOctokit(options);
133

134
// GitHub Enterprise
135
const enterpriseOptions = toOctokitOptions({
136
  githubToken: "ghs_xxxxxxxxxxxx",
137
  githubUrl: "https://github.company.com",
138
  githubApiPathPrefix: "/api/v3"
139
});
140

141
// Direct API URL (overrides githubUrl)
142
const directApiOptions = toOctokitOptions({
143
  githubToken: "ghp_xxxxxxxxxxxx", 
144
  githubApiUrl: "https://api.github.company.com"
145
});
146
```
147

148
### Authentication Methods
149

150
The plugin supports multiple GitHub authentication methods:
151

152
**Personal Access Tokens:**
153
```javascript
154
// Environment variable
155
process.env.GITHUB_TOKEN = "ghp_xxxxxxxxxxxx";
156

157
// Plugin configuration
158
{
159
  "githubToken": "ghp_xxxxxxxxxxxx" // Not recommended in config files
160
}
161
```
162

163
**GitHub App Tokens:**
164
```javascript
165
// Typically provided by CI systems
166
process.env.GITHUB_TOKEN = "ghs_xxxxxxxxxxxx";
167
```
168

169
**GitHub Actions Token:**
170
```javascript
171
// Automatic in GitHub Actions
172
process.env.GITHUB_TOKEN = "${{ secrets.GITHUB_TOKEN }}";
173
```
174

175
### Error Handling
176

177
GitHub integration includes comprehensive error handling for common API issues:
178

179
```javascript { .api }
180
// Common error scenarios handled automatically:
181

182
// Rate limiting - automatically waits and retries
183
// HTTP 403 with rate limit headers
184

185
// Authentication errors - thrown immediately  
186
// HTTP 401 with invalid token
187

188
// Repository access errors - thrown immediately
189
// HTTP 404 for missing repo or insufficient permissions
190

191
// Network errors - retried with backoff
192
// Connection timeouts, DNS failures, etc.
193

194
// Server errors - retried with backoff  
195
// HTTP 5xx responses from GitHub
196
```
197

198
**Manual Error Handling:**
199

200
```javascript
201
import { SemanticReleaseOctokit } from "@semantic-release/github/lib/octokit.js";
202

203
try {
204
  const octokit = new SemanticReleaseOctokit({ auth: token });
205
  const response = await octokit.request("GET /repos/{owner}/{repo}", {
206
    owner: "semantic-release",
207
    repo: "github"
208
  });
209
} catch (error) {
210
  if (error.status === 401) {
211
    console.error("Invalid or expired GitHub token");
212
  } else if (error.status === 404) {
213
    console.error("Repository not found or insufficient permissions");
214
  } else if (error.status === 403) {
215
    console.error("Rate limit exceeded or forbidden");
216
  } else {
217
    console.error("Unexpected GitHub API error:", error.message);
218
  }
219
}
220
```
221

222
### GitHub Enterprise Support
223

224
Full support for GitHub Enterprise installations with flexible endpoint configuration:
225

226
```javascript
227
// Method 1: Separate URL and prefix
228
const options = toOctokitOptions({
229
  githubToken: token,
230
  githubUrl: "https://github.company.com",
231
  githubApiPathPrefix: "/api/v3"
232
});
233
// Results in baseUrl: "https://github.company.com/api/v3"
234

235
// Method 2: Direct API URL
236
const options = toOctokitOptions({
237
  githubToken: token,
238
  githubApiUrl: "https://github-api.company.com/v3"
239
});
240
// Results in baseUrl: "https://github-api.company.com/v3"
241

242
// Environment variable support
243
process.env.GITHUB_URL = "https://github.company.com";
244
process.env.GITHUB_PREFIX = "/api/v3";
245
process.env.GITHUB_API_URL = "https://github-api.company.com/v3";
246
```
247

248
### Performance Optimizations
249

250
The GitHub integration includes several performance optimizations:
251

252
- **Connection Pooling**: Reuses HTTP connections for multiple requests
253
- **Request Batching**: Groups related API calls when possible  
254
- **Conditional Requests**: Uses ETags and If-Modified-Since headers
255
- **Parallel Requests**: Makes independent API calls concurrently
256
- **Lazy Loading**: Only loads required Octokit plugins
257
- **Memory Management**: Properly disposes of large response objects