0
# Core Framework
1

2
The Probot class is the main entry point for building GitHub Apps, providing event handling, authentication management, and application lifecycle control.
3

4
## Capabilities
5

6
### Probot Class
7

8
The main class for creating and configuring GitHub App instances.
9

10
```typescript { .api }
11
/**
12
 * Main Probot class for building GitHub Apps
13
 */
14
class Probot {
15
  /**
16
   * Create a new Probot instance
17
   * @param options - Configuration options for the Probot instance
18
   */
19
  constructor(options: Options = {});
20
  
21
  /**
22
   * Create a new Probot class with default options
23
   * @param defaults - Default options to merge with constructor options
24
   * @returns Extended Probot constructor with defaults
25
   */
26
  static defaults<S extends Constructor>(
27
    this: S,
28
    defaults: Options
29
  ): ExtendedConstructor & S;
30
  
31
  /**
32
   * Get the Probot framework version
33
   * @returns Version string
34
   */
35
  static get version(): string;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { Probot } from "probot";
43

44
// Basic initialization
45
const app = new Probot({
46
  appId: process.env.APP_ID,
47
  privateKey: process.env.PRIVATE_KEY,
48
  secret: process.env.WEBHOOK_SECRET,
49
});
50

51
// Using defaults
52
const ProbotWithDefaults = Probot.defaults({
53
  logLevel: "debug",
54
  secret: "development",
55
});
56
const app = new ProbotWithDefaults({ appId: 123 });
57
```
58

59
### Instance Properties
60

61
Access to key Probot instance properties and state.
62

63
```typescript { .api }
64
/**
65
 * Pino logger instance scoped to this Probot instance
66
 */
67
get log(): Logger;
68

69
/**
70
 * Probot framework version string
71
 */
72
get version(): string;
73

74
/**
75
 * Webhooks event emitter instance for handling GitHub events
76
 */
77
get webhooks(): ProbotWebhooks;
78

79
/**
80
 * URL path where webhooks are received (e.g., "/api/github/webhooks")
81
 */
82
get webhookPath(): string;
83
```
84

85
### Authentication
86

87
Methods for managing GitHub App authentication and getting authenticated API clients.
88

89
```typescript { .api }
90
/**
91
 * Get an authenticated Octokit instance for a specific installation
92
 * @param installationId - GitHub App installation ID (optional for app-level auth)
93
 * @returns Authenticated Octokit instance
94
 */
95
async auth(installationId?: number): Promise<ProbotOctokit>;
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
// App-level authentication (for app management)
102
const appOctokit = await app.auth();
103
const installations = await appOctokit.apps.listInstallations();
104

105
// Installation-level authentication (for repository access)
106
const installationOctokit = await app.auth(12345);
107
const repos = await installationOctokit.apps.listReposAccessibleToInstallation();
108
```
109

110
### Application Loading
111

112
Methods for loading and registering application functions.
113

114
```typescript { .api }
115
/**
116
 * Load one or more application functions
117
 * @param appFn - Application function(s) to load
118
 * @param options - Options passed to application functions
119
 */
120
async load(
121
  appFn: ApplicationFunction | ApplicationFunction[], 
122
  options?: ApplicationFunctionOptions
123
): Promise<void>;
124

125
/**
126
 * Wait for Probot initialization to complete
127
 * @returns Promise that resolves when Probot is ready
128
 */
129
async ready(): Promise<this>;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
// Load a single app function
136
await app.load((app) => {
137
  app.on("issues.opened", async (context) => {
138
    // Handle issue opened
139
  });
140
});
141

142
// Load multiple app functions
143
await app.load([appFunction1, appFunction2], {
144
  cwd: process.cwd(),
145
  addHandler: (handler) => server.addHandler(handler),
146
});
147

148
// Ensure app is ready before proceeding
149
await app.ready();
150
```
151

152
### Event Handling
153

154
Core event handling methods for registering webhook event listeners.
155

156
```typescript { .api }
157
/**
158
 * Register event handler(s) for specific GitHub webhook events
159
 * Supports single event name, array of event names, or wildcard patterns
160
 */
161
on: ProbotWebhooks["on"];
162

163
/**
164
 * Register handler for all GitHub webhook events
165
 * Useful for logging, analytics, or cross-cutting concerns
166
 */
167
onAny: ProbotWebhooks["onAny"];
168

169
/**
170
 * Register error handler for webhook processing errors
171
 * Called when event handlers throw exceptions
172
 */
173
onError: ProbotWebhooks["onError"];
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
// Single event handler
180
app.on("issues.opened", async (context) => {
181
  await context.octokit.issues.createComment(
182
    context.issue({ body: "Welcome!" })
183
  );
184
});
185

186
// Multiple event handler
187
app.on(["issues.opened", "issues.reopened"], async (context) => {
188
  // Handle both opened and reopened issues
189
});
190

191
// Wildcard event handler
192
app.on("issues", async (context) => {
193
  // Handle all issue events (opened, closed, edited, etc.)
194
});
195

196
// Global event handler
197
app.onAny(async (context) => {
198
  context.log.info(`Event: ${context.name}`);
199
});
200

201
// Error handler
202
app.onError(async (error) => {
203
  app.log.error("Webhook processing failed:", error);
204
});
205
```
206

207
### Manual Event Processing
208

209
Methods for manually triggering webhook event processing.
210

211
```typescript { .api }
212
/**
213
 * Manually receive and process a webhook event
214
 * @param event - GitHub webhook event object
215
 */
216
async receive(event: WebhookEvent): Promise<void>;
217
```
218

219
**Usage Examples:**
220

221
```typescript
222
// Manually trigger event processing
223
const mockEvent = {
224
  name: "issues",
225
  id: "12345",
226
  payload: {
227
    action: "opened",
228
    issue: { /* issue data */ },
229
    repository: { /* repo data */ },
230
  },
231
};
232

233
await app.receive(mockEvent);
234
```
235

236
### Middleware Integration
237

238
Get Node.js/Express compatible middleware for integrating with existing web applications.
239

240
```typescript { .api }
241
/**
242
 * Get Node.js middleware for handling webhooks and custom routes
243
 * @param options - Middleware configuration options
244
 * @returns Promise resolving to Express-compatible middleware function
245
 */
246
async getNodeMiddleware(options?: {
247
  log?: Logger;
248
  path?: string;
249
}): Promise<NodeMiddleware>;
250
```
251

252
**Usage Examples:**
253

254
```typescript
255
import express from "express";
256

257
const server = express();
258
const middleware = await app.getNodeMiddleware();
259

260
// Mount Probot middleware
261
server.use(middleware);
262

263
// Custom middleware with options
264
const customMiddleware = await app.getNodeMiddleware({
265
  log: customLogger,
266
  path: "/github/webhooks",
267
});
268

269
server.use("/api", customMiddleware);
270
server.listen(3000);
271
```
272

273
## Configuration Types
274

275
```typescript { .api }
276
interface Options {
277
  /** GitHub App private key (PEM format) */
278
  privateKey?: string;
279
  /** Personal access token (alternative to App auth) */
280
  githubToken?: string;
281
  /** GitHub App ID */
282
  appId?: number | string;
283
  /** Custom Octokit class */
284
  Octokit?: typeof ProbotOctokit;
285
  /** Custom logger instance */
286
  log?: Logger;
287
  /** Redis configuration for clustering */
288
  redisConfig?: RedisOptions | string;
289
  /** Webhook secret for payload verification */
290
  secret?: string;
291
  /** Log level verbosity */
292
  logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
293
  /** Log output format */
294
  logFormat?: "json" | "pretty";
295
  /** Use string log levels in JSON output */
296
  logLevelInString?: boolean;
297
  /** JSON log message key name */
298
  logMessageKey?: string;
299
  /** Sentry DSN for error reporting */
300
  sentryDsn?: string;
301
  /** HTTP server port */
302
  port?: number;
303
  /** HTTP server host */
304
  host?: string;
305
  /** Custom server instance */
306
  server?: Server;
307
  /** GitHub API base URL (for Enterprise) */
308
  baseUrl?: string;
309
  /** Octokit request options */
310
  request?: RequestRequestOptions;
311
  /** Webhook endpoint path */
312
  webhookPath?: string;
313
  /** Smee.io proxy URL for development */
314
  webhookProxy?: string;
315
}
316

317
type Constructor<T = any> = new (...args: any[]) => T;
318

319
type ProbotWebhooks = Webhooks<SimplifiedObject>;
320

321
interface ApplicationFunctionOptions {
322
  /** Current working directory */
323
  cwd: string;
324
  /** Function to add custom HTTP handlers */
325
  addHandler: (handler: Handler) => void;
326
  /** Additional custom options */
327
  [key: string]: unknown;
328
}
329

330
type ApplicationFunction = (
331
  app: Probot,
332
  options: ApplicationFunctionOptions
333
) => void | Promise<void>;
334

335
type NodeMiddleware = (
336
  req: IncomingMessage,
337
  res: ServerResponse,
338
  next?: (err?: Error) => void
339
) => Promise<boolean | void>;
340
```