0
# Probot
1
2
Probot is a comprehensive Node.js framework for building GitHub Apps that automate and improve your workflow. Built in TypeScript, it provides a high-level API for handling GitHub webhook events, managing GitHub App authentication, and interacting with the GitHub API through a unified context system.
3
4
## Package Information
5
6
- **Package Name**: probot
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install probot`
10
11
## Core Imports
12
13
```typescript
14
import { Probot, Context, run, createProbot } from "probot";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { Probot, Context, run, createProbot } = require("probot");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { Probot } from "probot";
27
28
export default (app: Probot) => {
29
// Handle issues being opened
30
app.on("issues.opened", async (context) => {
31
const issueComment = context.issue({
32
body: "Thanks for opening this issue!",
33
});
34
return context.octokit.issues.createComment(issueComment);
35
});
36
37
// Handle all events
38
app.onAny(async (context) => {
39
context.log.info({ event: context.name, action: context.payload.action });
40
});
41
42
// Handle errors
43
app.onError(async (error) => {
44
app.log.error(error);
45
});
46
};
47
```
48
49
## Architecture
50
51
Probot is built around several key components:
52
53
- **Event-Driven Architecture**: Uses GitHub webhooks to trigger application logic based on repository events
54
- **Context System**: Provides rich context objects containing event payloads, authenticated Octokit instances, and helper methods
55
- **Authentication Management**: Handles GitHub App authentication, installation tokens, and JWT generation automatically
56
- **HTTP Server**: Built-in server for receiving webhooks, serving web interfaces, and handling OAuth flows
57
- **Middleware System**: Extensible request/response handling with built-in logging, error handling, and static file serving
58
- **Configuration Management**: Environment-based configuration with support for development and production deployments
59
60
## Capabilities
61
62
### Core Framework
63
64
The main Probot class and application lifecycle management for building GitHub Apps with event handling, authentication, and server setup.
65
66
```typescript { .api }
67
class Probot {
68
constructor(options: Options);
69
static defaults(defaults: Options): typeof Probot;
70
static get version(): string;
71
72
get log(): Logger;
73
get version(): string;
74
get webhooks(): ProbotWebhooks;
75
get webhookPath(): string;
76
77
async auth(installationId?: number): Promise<ProbotOctokit>;
78
async getNodeMiddleware(options?: { log?: Logger; path?: string }): Promise<ReturnType<typeof createNodeMiddleware>>;
79
async load(appFn: ApplicationFunction | ApplicationFunction[], options?: ApplicationFunctionOptions): Promise<void>;
80
async ready(): Promise<this>;
81
async receive(event: WebhookEvent): Promise<void>;
82
83
on: ProbotWebhooks["on"];
84
onAny: ProbotWebhooks["onAny"];
85
onError: ProbotWebhooks["onError"];
86
}
87
```
88
89
[Core Framework](./core-framework.md)
90
91
### Context and Event Handling
92
93
Rich context objects for webhook events with GitHub API integration and repository-specific helper methods.
94
95
```typescript { .api }
96
class Context<Event extends WebhookEvents = WebhookEvents> {
97
public name: WebhookEvents;
98
public id: string;
99
public payload: WebhookPayload;
100
public octokit: ProbotOctokit;
101
public log: Logger;
102
103
get isBot(): boolean;
104
105
repo<T>(object?: T): RepoResultType<Event> & T;
106
issue<T>(object?: T): RepoResultType<Event> & { issue_number: number } & T;
107
pullRequest<T>(object?: T): RepoResultType<Event> & { pull_number: number } & T;
108
async config<T>(fileName: string, defaultConfig?: T, deepMergeOptions?: MergeOptions): Promise<T | null>;
109
}
110
```
111
112
[Context and Event Handling](./context-events.md)
113
114
### HTTP Server and Middleware
115
116
Built-in HTTP server for webhooks, web interfaces, and custom request handling with middleware support.
117
118
```typescript { .api }
119
class Server {
120
constructor(options: ServerOptions);
121
122
get port(): number;
123
get host(): string;
124
static get version(): string;
125
get version(): string;
126
127
addHandler(handler: Handler): void;
128
async loadHandlerFactory(appFn: HandlerFactory): Promise<void>;
129
async load(appFn: ApplicationFunction): Promise<void>;
130
async start(): Promise<HttpServer>;
131
async stop(): Promise<void>;
132
}
133
```
134
135
[HTTP Server and Middleware](./server-middleware.md)
136
137
### GitHub API Integration
138
139
Enhanced Octokit client with Probot-specific plugins, authentication, and configuration for seamless GitHub API access.
140
141
```typescript { .api }
142
class ProbotOctokit extends Octokit {
143
// Includes all standard Octokit functionality plus:
144
// - Automatic authentication with GitHub Apps
145
// - Request throttling and retries
146
// - Pagination support
147
// - Enterprise compatibility
148
// - Request logging
149
// - Configuration file reading
150
}
151
```
152
153
[GitHub API Integration](./github-api.md)
154
155
### Application Creation and Deployment
156
157
Factory functions and utilities for creating, configuring, and running Probot applications in various environments.
158
159
```typescript { .api }
160
function createProbot(options?: CreateProbotOptions): Probot;
161
function createNodeMiddleware(appFn: ApplicationFunction, options?: MiddlewareOptions): Promise<NodeMiddleware>;
162
function run(appFnOrArgv: ApplicationFunction | string[], additionalOptions?: Partial<Options>): Promise<Server>;
163
```
164
165
[Application Creation and Deployment](./app-creation.md)
166
167
## Core Types
168
169
```typescript { .api }
170
interface Options {
171
privateKey?: string;
172
githubToken?: string;
173
appId?: number | string;
174
Octokit?: typeof ProbotOctokit;
175
log?: Logger;
176
redisConfig?: RedisOptions | string;
177
secret?: string;
178
logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
179
logFormat?: "json" | "pretty";
180
logLevelInString?: boolean;
181
logMessageKey?: string;
182
sentryDsn?: string;
183
port?: number;
184
host?: string;
185
server?: Server;
186
baseUrl?: string;
187
request?: RequestRequestOptions;
188
webhookPath?: string;
189
webhookProxy?: string;
190
}
191
192
type ApplicationFunction = (
193
app: Probot,
194
options: ApplicationFunctionOptions
195
) => void | Promise<void>;
196
197
type ApplicationFunctionOptions = {
198
cwd: string;
199
addHandler: (handler: Handler) => void;
200
[key: string]: unknown;
201
};
202
203
type Handler = (
204
req: IncomingMessage,
205
res: ServerResponse
206
) => void | boolean | Promise<void | boolean>;
207
208
type ProbotWebhooks = Webhooks<Omit<Context, keyof WebhookEvent>>;
209
210
type StripUndefined<T> = {
211
[K in keyof T]-?: Exclude<T[K], undefined>;
212
};
213
214
type OctokitOptions = NonNullable<
215
ConstructorParameters<typeof ProbotOctokit>[0]
216
>;
217
218
type PackageJson = {
219
name?: string;
220
version?: string;
221
description?: string;
222
homepage?: string;
223
repository?: string;
224
engines?: { [key: string]: string };
225
};
226
227
type Env = NodeJS.ProcessEnv;
228
```