8000 feat(github): Add repo webhook resource (#477) · sam-goodwin/alchemy@2c997d6 · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Commit 2c997d6

Browse files
zephraphzephraph
authored
feat(github): Add repo webhook resource (#477)
1 parent 54984d1 commit 2c997d6

File tree

5 files changed

+619
-1
lines changed

5 files changed

+619
-1
lines changed

‎alchemy-web/docs/providers/github/index.md

Lines changed: 11 additions & 1 deletion
8000
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,13 @@ GitHub is a web-based version control and collaboration platform that provides G
88

99
- [Comment](./comment.md) - Create and manage comments on issues and pull requests
1010
- [RepositoryEnvironment](./repository-environment.md) - Create and manage deployment environments with protection rules
11+
- [RepositoryWebhook](./repository-webhook.md) - Create and manage repository webhooks for event notifications
1112
- [Secret](./secret.md) - Create and manage GitHub Actions and Dependabot secrets
1213

1314
## Example Usage
1415

1516
```ts
16-
import { Comment, RepositoryEnvironment, GitHubSecret } from "alchemy/github";
17+
import { Comment, RepositoryEnvironment, RepositoryWebhook, GitHubSecret } from "alchemy/github";
1718

1819
// Create a repository environment
1920
const prodEnv = await RepositoryEnvironment("production", {
@@ -32,6 +33,15 @@ const prodEnv = await RepositoryEnvironment("production", {
3233
},
3334
});
3435

36+
// Create a webhook for CI/CD notifications
37+
const webhook = await RepositoryWebhook("ci-webhook", {
38+
owner: "my-org",
39+
repository: "my-repo",
40+
url: "https://ci.example.com/webhook",
41+
secret: alchemy.secret("GITHUB_WEBHOOK_SECRET"),
42+
events: ["push", "pull_request", "release"],
43+
});
44+
3545
// Create a secret for the environment
3646
const secret = await GitHubSecret("deploy-key", {
3747
owner: "my-org",

‎alchemy-web/docs/providers/github/repository-webhook.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# RepositoryWebhook
2+
3+
Manage GitHub repository webhooks with automatic lifecycle management.
4+
5+
Webhooks allow external services to be notified when certain events happen in a repository. This resource manages the full lifecycle of repository webhooks including creation, updates, and deletion.
6+
7+
## Basic Usage
8+
9+
Create a simple webhook for push events:
10+
11+
```ts
12+
import { RepositoryWebhook } from "alchemy/github";
13+
14+
const webhook = await RepositoryWebhook("my-webhook", {
15+
owner: "my-org",
16+
repository: "my-repo",
17+
url: "https://my-service.com/github-webhook",
18+
events: ["push"]
19+
});
20+
```
21+
22+
## With Secret Validation
23+
24+
Add webhook secret for payload validation:
25+
26+
```ts
27+
import { RepositoryWebhook } from "alchemy/github";
28+
import { alchemy } from "alchemy";
29+
30+
const webhook = await RepositoryWebhook("secure-webhook", {
31+
owner: "my-org",
32+
repository: "my-repo",
33+
url: "https://ci.example.com/webhook",
34+
secret: alchemy.secret("GITHUB_WEBHOOK_SECRET"),
35+
events: ["push", "pull_request", "release"],
36+
contentType: "application/json"
37+
});
38+
```
39+
40+
## Multiple Events
41+
42+
Listen to multiple GitHub events:
43+
44+
```ts
45+
import { RepositoryWebhook } from "alchemy/github";
46+
47+
const ciWebhook = await RepositoryWebhook("ci-webhook", {
48+
owner: "my-org",
49+
repository: "my-repo",
50+
url: "https://ci.example.com/webhook",
51+
events: [
52+
"push",
53+
"pull_request",
54+
"release",
55+
"issues",
56+
"issue_comment"
57+
]
58+
});
59+
```
60+
61+
## All Events
62+
63+
Create a webhook that listens to all repository events:
64+
65+
```ts
66+
import { RepositoryWebhook } from "alchemy/github";
67+
68+
const monitoringWebhook = await RepositoryWebhook("monitoring-webhook", {
69+
owner: "my-org",
70+
repository: "my-repo",
71+
url: "https://monitoring.internal.com/github",
72+
events: ["*"], // Listen to all events
73+
insecureSsl: true, // For internal services with self-signed certs
74+
contentType: "application/x-www-form-urlencoded"
75+
});
76+
```
77+
78+
## Custom SSL Configuration
79+
80+
For internal services or development environments:
81+
82+
```ts
83+
import { RepositoryWebhook } from "alchemy/github";
84+
85+
const devWebhook = await RepositoryWebhook("dev-webhook", {
86+
owner: "my-org",
87+
repository: "my-repo",
88+
url: "https://localhost:3000/webhook",
89+
insecureSsl: true, // Skip SSL verification
90+
active: false, // Create inactive webhook
91+
events: ["push", "pull_request"]
92+
});
93+
```
94+
95+
## Properties
96+
97+
| Property | Type | Required | Description |
98+
|----------|------|----------|-------------|
99+
| `owner` | string | ✅ | Repository owner (user or organization) |
100+
| `repository` | string | ✅ | Repository name |
101+
| `url` | string | ✅ | The URL to which the payloads will be delivered |
102+
| `secret` | string | | Webhook secret for payload validation |
103+
| `contentType` | `"application/json"` \| `"application/x-www-form-urlencoded"` | | The media type used to serialize the payloads (default: `"application/json"`) |
104+
| `insecureSsl` | boolean | | Determines whether the SSL certificate of the host for url will be verified (default: `false`) |
105+
| `active` | boolean | | Determines if notifications are sent when the webhook is triggered (default: `true`) |
106+
| `events` | string[] | | Determines what events the hook is triggered for (default: `["push"]`) |
107+
| `token` | string | | Optional GitHub API token (overrides environment variable) |
108+
109+
## Returns
110+
111+
| Property | Type | Description |
112+
|----------|------|-------------|
113+
| `id` | string | Resource identifier |
114+
| `webhookId` | number | The numeric ID of the webhook in GitHub |
115+
| `url` | string | The webhook URL that was configured |
116+
| `createdAt` | string | Time at which the webhook was created |
117+
| `updatedAt` | string | Time at which the webhook was last updated |
118+
| `pingUrl` | string | The ping URL for testing the webhook |
119+
| `testUrl` | string | The test URL for the webhook |
120+
121+
## GitHub Events
122+
123+
Common GitHub webhook events you can listen to:
124+
125+
- `push` - Any Git push to a Repository
126+
- `pull_request` - Pull request activity
127+
- `issues` - Issue activity
128+
- `issue_comment` - Issue comment activity
129+
- `release` - Release activity
130+
- `create` - Branch or tag created
131+
- `delete` - Branch or tag deleted
132+
- `fork` - Repository forked
133+
- `star` - Repository starred
134+
- `watch` - Repository watched
135+
- `workflow_run` - GitHub Actions workflow run
136+
- `*` - All events
137+
138+
For a complete list of available events, see the [GitHub Webhooks documentation](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads).
139+
140+
## Authentication
141+
142+
The resource requires a GitHub token with appropriate permissions:
143+
144+
```bash
145+
export GITHUB_TOKEN="ghp_your_token_here"
146+
```
147+
148+
The token must have:
149+
- `repo` scope for private repositories
150+
- `public_repo` scope for public repositories
151+
- Admin access to the repository to manage webhooks
152+
153+
## Error Handling
154+
155+
The resource handles common GitHub API errors:
156+
157+
- **403 Forbidden**: Token lacks admin rights to the repository
158+
- **422 Unprocessable Entity**: Invalid webhook configuration (bad URL, invalid events, etc.)
159+
- **404 Not Found**: Repository doesn't exist or token lacks access
160+
161+
## Updates
162+
163+
When updating a webhook, you can change:
164+
- Webhook URL
165+
- Events list
166+
- Secret
167+
- Content type
168+
- SSL verification settings
169+
- Active status
170+
171+
The webhook ID remains the same during updates.
172+
173+
## Security
174+
175+
- Always use HTTPS URLs for webhook endpoints
176+
- Use webhook secrets to validate payload authenticity
177+
- Consider using `insecureSsl: false` (default) for production
178+
- Regularly rotate webhook secrets
179+
180+
## Best Practices
181+
182+
1. **Use secrets**: Always configure webhook secrets for payload validation
183+
2. **Specific events**: Only listen to events your application needs
184+
3. **Error handling**: Implement proper error handling in your webhook receiver
185+
4. **Testing**: Use the `pingUrl` to test webhook connectivity
186+
5. **Monitoring**: Monitor webhook delivery success rates in GitHub

‎alchemy/src/github/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
export * from "./comment.ts";
22
export * from "./repository-environment.ts";
3+
export * from "./repository-webhook.ts";
34
export * from "./secret.ts";

0 commit comments

Comments
 (0)
0