Skip to content

Commit e6df050

Browse files
jsamjsam
committed
chore: update gitops
1 parent 6d43eda commit e6df050

2 files changed

Lines changed: 274 additions & 0 deletions

File tree

‎EVENTS.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# GitHub Webhook Events Reference
2+
3+
This document lists all GitHub webhook events that are NOT essential for core GitOps deployment workflows. These events are available but not prioritized for implementation in this library.
4+
5+
## Collaboration & Project Management
6+
7+
### Issues & Comments
8+
- **`issues`** - Issue opened, closed, edited, assigned, etc.
9+
- **`issue_comment`** - Comment on issue or pull request
10+
- **`commit_comment`** - Comment on a commit
11+
12+
### Pull Request Reviews
13+
- **`pull_request_review`** - Pull request review submitted
14+
- **`pull_request_review_comment`** - Comment on PR diff
15+
- **`pull_request_review_thread`** - PR review thread activity
16+
17+
### Projects
18+
- **`project`** - Project (classic) created, edited, deleted
19+
- **`project_card`** - Project card moved, created, deleted
20+
- **`project_column`** - Project column created, updated, deleted
21+
- **`projects_v2`** - Project (new) activity
22+
- **`projects_v2_item`** - Project item activity
23+
- **`projects_v2_status_update`** - Project status update
24+
25+
### Discussions
26+
- **`discussion`** - Discussion created, edited, deleted, etc.
27+
- **`discussion_comment`** - Comment on a discussion
28+
29+
### Other Collaboration
30+
- **`label`** - Label created, edited, deleted
31+
- **`milestone`** - Milestone created, edited, deleted, etc.
32+
- **`gollum`** - Wiki page created or updated
33+
34+
## Repository & Organization Management
35+
36+
### Repository Events
37+
- **`repository`** - Repository created, deleted, archived, renamed, etc.
38+
- **`repository_dispatch`** - Custom webhook event triggered via API
39+
- **`repository_import`** - Repository import activity
40+
- **`public`** - Repository visibility changed to public
41+
- **`fork`** - Repository forked
42+
43+
### Team & Member Management
44+
- **`member`** - Collaborator added, removed, or permissions changed
45+
- **`membership`** - User added/removed from team
46+
- **`team`** - Team created, deleted, edited
47+
- **`team_add`** - Team added to repository
48+
- **`organization`** - Organization settings changed
49+
- **`org_block`** - User blocked/unblocked from organization
50+
51+
### Repository Settings
52+
- **`branch_protection_rule`** - Branch protection rule created, edited, deleted
53+
- **`branch_protection_configuration`** - Branch protection configuration changed
54+
- **`repository_ruleset`** - Repository ruleset activity
55+
- **`deploy_key`** - Deploy key added or removed
56+
- **`custom_property`** - Custom property changed
57+
- **`custom_property_values`** - Custom property values updated
58+
59+
## Security & Compliance
60+
61+
### Security Alerts
62+
- **`code_scanning_alert`** - Code scanning alert created, fixed, dismissed
63+
- **`secret_scanning_alert`** - Secret detected in code
64+
- **`secret_scanning_alert_location`** - Secret location detected
65+
- **`secret_scanning_scan`** - Secret scanning scan completed
66+
- **`dependabot_alert`** - Dependabot alert created, fixed, dismissed
67+
- **`repository_vulnerability_alert`** - Vulnerability alert (legacy)
68+
69+
### Security Advisory
70+
- **`security_advisory`** - Security advisory published
71+
- **`repository_advisory`** - Repository security advisory
72+
- **`security_and_analysis`** - Security and analysis settings changed
73+
74+
### Deployment Protection
75+
- **`deployment_protection_rule`** - Deployment protection rule activity
76+
- **`deployment_review`** - Deployment review requested/approved
77+
78+
## GitHub Apps & Integrations
79+
80+
### Installation
81+
- **`installation`** - GitHub App installed, uninstalled, suspended
82+
- **`installation_repositories`** - Repositories added/removed from installation
83+
- **`installation_target`** - Installation moved to different account
84+
- **`github_app_authorization`** - User authorizes/revokes GitHub App
85+
86+
### Workflow Management
87+
- **`workflow_dispatch`** - Workflow manually triggered (for workflow visibility, not deployment)
88+
- **`workflow_job`** - Individual job status (detailed monitoring, not essential for GitOps)
89+
90+
### Metadata
91+
- **`meta`** - Webhook itself is modified or deleted
92+
93+
## Community & Engagement
94+
95+
- **`star`** - Repository starred or unstarred
96+
- **`watch`** - User starts/stops watching repository
97+
- **`sponsorship`** - Sponsorship tier created, cancelled, changed
98+
99+
## Package Management
100+
101+
- **`package`** - GitHub Packages published, updated, deleted
102+
- **`registry_package`** - Container registry package activity
103+
104+
## GitHub Pages
105+
106+
- **`page_build`** - GitHub Pages site build attempt (success/failure)
107+
108+
## Marketplace
109+
110+
- **`marketplace_purchase`** - GitHub Marketplace app purchased, cancelled, changed
111+
112+
## Other Events
113+
114+
- **`merge_group`** - Merge queue activity
115+
- **`personal_access_token_request`** - PAT request in organization
116+
- **`sub_issues`** - Sub-issue activity (tasklists)
117+
- **`issue_dependencies`** - Issue dependency tracking
118+
119+
## Notes
120+
121+
**Total events: 65**
122+
123+
These events are useful for:
124+
- Building GitHub dashboards and analytics
125+
- Issue/PR automation and bots
126+
- Security monitoring and compliance
127+
- Team collaboration tools
128+
- Community engagement tracking
129+
- Project management automation
130+
131+
However, they are **not required** for the core GitOps use case of:
132+
1. Syncing manifest repositories
133+
2. Managing deployment environments
134+
3. Tracking deployment status
135+
4. Triggering deployments on code changes
136+
137+
## Using Unknown Events
138+
139+
The library handles all these events gracefully:
140+
141+
```rust
142+
match event {
143+
WebhookEvent::Push(push_event) => {
144+
// Handle GitOps sync
145+
}
146+
WebhookEvent::Unknown(event_type) => {
147+
// Log and ignore non-essential events
148+
println!("Received non-essential event: {}", event_type);
149+
}
150+
_ => {}
151+
}
152+
```
153+
154+
If you need to implement any of these events, you can:
155+
1. Add the event struct to `webhook.rs`
156+
2. Add a variant to `WebhookEvent` enum
157+
3. Add parsing logic to `WebhookVerifier::parse_event()`
158+
4. Submit a PR to the library
159+
160+
## Resources
161+
162+
- [Complete GitHub Webhook Events List](https://docs.github.com/en/webhooks/webhook-events-and-payloads)
163+
- [GitHub Webhook Event Payloads](https://docs.github.com/en/webhooks/webhook-events-and-payloads)

‎TODO.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# TODO: GitOps Essential Events
2+
3+
This file tracks webhook events essential for GitOps deployment workflows.
4+
5+
## Currently Implemented ✅
6+
7+
- [x] `push` - Push commits to a branch (triggers sync and reconciliation)
8+
- [x] `ping` - Webhook configuration test
9+
10+
## Essential for GitOps Deployment
11+
12+
### Core GitOps Events
13+
14+
- [ ] **`pull_request`** - PR workflow for preview environments
15+
- Used for: Creating preview/staging environments on PR open
16+
- Action: Deploy PR branch, run tests, create deployment preview
17+
- Key data: PR number, branch, base branch, action (opened/closed/merged)
18+
19+
- [ ] **`create`** - Branch or tag created
20+
- Used for: Tracking new branches for environment provisioning
21+
- Action: Initialize environment for new branch if needed
22+
- Key data: ref, ref_type (branch/tag), repository
23+
24+
- [ ] **`delete`** - Branch or tag deleted
25+
- Used for: Cleanup of environments when branches are deleted
26+
- Action: Tear down preview environments, cleanup resources
27+
- Key data: ref, ref_type (branch/tag), repository
28+
29+
### Deployment Tracking Events
30+
31+
- [ ] **`deployment`** - Deployment created
32+
- Used for: Tracking deployment requests
33+
- Action: Record deployment intent, prepare environment
34+
- Key data: deployment id, environment, ref, sha
35+
36+
- [ ] **`deployment_status`** - Deployment status changed
37+
- Used for: Monitoring deployment progress (pending/success/failure)
38+
- Action: Update deployment status, notify on completion
39+
- Key data: deployment id, state, environment, target_url
40+
41+
- [ ] **`release`** - Release published
42+
- Used for: Production deployments triggered by releases
43+
- Action: Deploy to production environment
44+
- Key data: tag_name, name, body, prerelease flag
45+
46+
### CI/CD Integration Events
47+
48+
- [ ] **`check_run`** - Check run activity
49+
- Used for: Waiting for CI checks before deployment
50+
- Action: Gate deployments on successful checks
51+
- Key data: status, conclusion, check suite, app
52+
53+
- [ ] **`check_suite`** - Check suite activity
54+
- Used for: Overall CI/CD pipeline status
55+
- Action: Trigger deployments when all checks pass
56+
- Key data: status, conclusion, head_branch, head_sha
57+
58+
- [ ] **`workflow_run`** - GitHub Actions workflow completed
59+
- Used for: Triggering deployments after build workflows
60+
- Action: Deploy artifacts after successful builds
61+
- Key data: conclusion, workflow name, head_branch, artifacts
62+
63+
- [ ] **`status`** - Commit status updated
64+
- Used for: Legacy CI status tracking
65+
- Action: Gate deployments based on commit status
66+
- Key data: state, context, target_url, sha
67+
68+
## Implementation Priority
69+
70+
1. **Phase 1 (Core)**: `pull_request`, `create`, `delete` - Environment lifecycle
71+
2. **Phase 2 (Deployment)**: `deployment`, `deployment_status`, `release` - Deployment tracking
72+
3. **Phase 3 (CI/CD)**: `check_run`, `check_suite`, `workflow_run`, `status` - CI integration
73+
74+
## GitOps Use Cases
75+
76+
### Use Case 1: Preview Environments
77+
```
78+
pull_request[opened] → Create preview env → Deploy PR branch
79+
pull_request[synchronize] → Update preview env → Deploy latest commit
80+
pull_request[closed] → Destroy preview env → Cleanup resources
81+
```
82+
83+
### Use Case 2: Branch-based Deployment
84+
```
85+
push[main] → Sync manifests → Deploy to staging
86+
release[published] → Sync manifests → Deploy to production
87+
delete[branch] → Cleanup → Remove environment
88+
```
89+
90+
### Use Case 3: CI-Gated Deployment
91+
```
92+
push[develop] → Wait for checks
93+
check_suite[completed, success] → Deploy to dev environment
94+
workflow_run[completed, build] → Deploy artifacts
95+
```
96+
97+
### Use Case 4: Deployment Status Tracking
98+
```
99+
deployment[created] → Start deployment
100+
deployment_status[in_progress] → Update progress
101+
deployment_status[success] → Mark complete
102+
deployment_status[failure] → Rollback
103+
```
104+
105+
## Non-GitOps Events
106+
107+
All other webhook events (issues, comments, stars, security alerts, etc.) are tracked in [EVENTS.md](./EVENTS.md) but are not essential for GitOps deployment workflows.
108+
109+
## Resources
110+
111+
- [GitHub Webhook Events Documentation](https://docs.github.com/en/webhooks/webhook-events-and-payloads)

0 commit comments

Comments
 (0)