Skip to content

Commit 13da088

Browse files
sgtojsgtoj
authored
Merge pull request #2 from cruxstack/dev
docs: improve documentation and add setups guides
2 parents e164336 + 84e1ce4 commit 13da088

File tree

4 files changed

+694
-39
lines changed

4 files changed

+694
-39
lines changed

‎README.md‎

Lines changed: 65 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ notifications. Deploy as AWS Lambda, standard HTTP server, or container.
1919

2020
### Prerequisites
2121

22-
* GitHub App ([setup guide](#github-app-setup))
2322
* Go ≥ 1.24
24-
* **Optional**: Okta API Service app for group sync
25-
* **Optional**: Slack app for notifications
23+
* GitHub App ([setup guide](docs/github-app-setup.md))
24+
* **Optional**: Okta API Service app ([setup guide](docs/okta-setup.md))
25+
* **Optional**: Slack app ([setup guide](docs/slack-setup.md))
2626

2727
### Deployment Options
2828

@@ -176,36 +176,14 @@ Map Okta groups to GitHub teams using JSON rules:
176176
Okta-synced teams and sends Slack notifications. Enabled by default when
177177
sync is enabled.
178178

179-
## Okta Setup
179+
## Integration Setup
180180

181-
Create an API Services application in Okta Admin Console:
181+
Detailed setup guides for each integration:
182182

183-
1. **Applications** → **Create App Integration** → **API Services**
184-
2. Name: `github-bot-api-service`
185-
3. **Client Credentials**:
186-
- Authentication: **Public key / Private key**
187-
- Generate and download private key (PEM format)
188-
- Note the Client ID
189-
4. **Okta API Scopes**: Grant `okta.groups.read` and `okta.users.read`
190-
191-
Use the Client ID and private key in your environment variables.
192-
193-
## GitHub App Setup
194-
195-
Create a GitHub App in your organization settings:
196-
197-
1. **Developer settings** → **GitHub Apps** → **New GitHub App**
198-
2. **Basic info**:
199-
- Name: `github-ops-app`
200-
- Webhook URL: Your API Gateway URL
201-
- Webhook secret: Generate and save for `APP_GITHUB_WEBHOOK_SECRET`
202-
3. **Permissions**:
203-
- Repository: Pull requests (Read), Contents (Read)
204-
- Organization: Members (Read & write), Administration (Read)
205-
4. **Events**: Subscribe to Pull request, Team, Membership
206-
5. Generate and download private key (`.pem` file)
207-
6. Install app to your organization
208-
7. Note: **App ID**, **Installation ID** (from install URL), **Private key**
183+
- [GitHub App Setup](docs/github-app-setup.md) - Create and install the GitHub
184+
App with required permissions
185+
- [Okta Setup](docs/okta-setup.md) - Configure API Services app for group sync
186+
- [Slack Setup](docs/slack-setup.md) - Create Slack app for notifications
209187

210188
## Development
211189

@@ -243,15 +221,63 @@ CMD ["/server"]
243221

244222
## How It Works
245223

246-
**Okta Sync**: EventBridge triggers sync → Fetch Okta groups → Apply rules →
247-
Update GitHub teams → Detect orphaned users → Send Slack reports. Automatically
248-
reconciles when external team changes are detected. Only syncs ACTIVE Okta
249-
users, skips external collaborators, and prevents mass removal during outages
250-
via safety threshold. Orphaned user detection identifies org members not in any
251-
synced teams.
224+
```
225+
┌─────────────────────────────────────────────────┐
226+
│ github-ops-app │
227+
│ │
228+
┌──────────────┐ │ ┌───────────────────────────────────────────┐ │
229+
│ GitHub │ webhooks │ │ Webhook Handler │ │
230+
│ │───────────────▶ • PR merge events │ │
231+
│ • PR merge │ │ │ • Team membership changes │ │
232+
│ • Team edit │ │ │ • Signature verification │ │
233+
└──────────────┘ │ └─────────────┬─────────────────────────────┘ │
234+
│ │ │
235+
│ ▼ │
236+
│ ┌─────────────────────────────────────────┐ │
237+
│ │ PR Compliance Check │ │
238+
┌──────────────┐ │ │ • Branch protection verification │────────┐
239+
│ Okta │ │ │ • Required checks validation │ │ │
240+
│ │ │ │ • Bypass detection │ │ │
241+
│ • Groups │◀──────────────┴─────────────────────────────────────────┘ │ │
242+
│ • Users │ │ │ │
243+
└──────────────┘ │ ┌─────────────────────────────────────────┐ │ │
244+
│ │ │ Okta Sync Engine │ │ │
245+
│ │ │ • Match groups via rules │ │ │
246+
└─────────────────────────▶ • Create/update GitHub teams │ │ │
247+
│ │ • Sync team membership │ │ │
248+
│ │ • Orphaned user detection │────────┤
249+
│ │ • Safety threshold protection │ │ │
250+
┌──────────────┐ │ └─────────────────────────────────────────┘ │ │
251+
│ GitHub │ │ │ │ │
252+
│ Teams API │◀─────────────────────────────────────────────────────────────┘ │
253+
│ │ │ │ │
254+
│ • Teams │ └─────────────────────────────────────────────────┘ │
255+
│ • Members │ │
256+
└──────────────┘ │
257+
┌──────────────┐ │
258+
│ Slack │◀─────────────────────────────────────┘
259+
│ │ Notifications
260+
│ • Alerts │ • PR violations
261+
│ • Reports │ • Sync reports
262+
└──────────────┘ • Orphaned users
263+
```
264+
265+
### Okta Sync Flow
266+
267+
1. **Trigger**: Scheduled cron/EventBridge or team membership webhook
268+
2. **Fetch**: Query Okta groups matching configured rules
269+
3. **Match**: Apply sync rules to map Okta groups → GitHub teams
270+
4. **Sync**: Add/remove GitHub team members (ACTIVE Okta users only)
271+
5. **Safety**: Abort if removal ratio exceeds threshold (default 50%)
272+
6. **Report**: Send Slack notification with changes and orphaned users
273+
274+
### PR Compliance Flow
252275

253-
**PR Compliance**: Webhook on PR merge → Verify signature → Check branch
254-
protection rules → Detect bypasses → Notify Slack if violations found.
276+
1. **Receive**: GitHub webhook on PR merge to monitored branch
277+
2. **Verify**: Validate webhook signature (HMAC-SHA256)
278+
3. **Check**: Query branch protection rules and required status checks
279+
4. **Detect**: Identify bypasses (admin override, missing reviews, failed checks)
280+
5. **Notify**: Send Slack alert with violation details
255281

256282
## Troubleshooting
257283

‎docs/github-app-setup.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# GitHub App Setup
2+
3+
This guide walks through creating and installing a GitHub App for github-ops-app.
4+
5+
## Prerequisites
6+
7+
- GitHub organization with admin access
8+
9+
## Step 1: Create the GitHub App
10+
11+
1. Navigate to your organization's settings:
12+
- Go to `https://github.com/organizations/YOUR_ORG/settings/apps`
13+
- Or: **Organization** → **Settings** → **Developer settings** → **GitHub Apps**
14+
15+
2. Click **New GitHub App**
16+
17+
3. Fill in the basic information:
18+
19+
| Field | Value |
20+
|-----------------------|-------------------------------------------------|
21+
| GitHub App name | `github-ops-app` (must be unique across GitHub) |
22+
| Homepage URL | Your organization's URL or repo URL |
23+
| Webhook > Webhook URL | Leave blank for now |
24+
| Webhook > Secret | Generate a strong secret (save this for later) |
25+
| Webhook > Active | **Uncheck** to disable webhooks initially |
26+
27+
> **Note**: Disable webhooks during creation since you may not know your
28+
> endpoint URL until after deployment. You'll configure webhooks and
29+
> subscribe to events in [Step 7](#step-7-configure-webhook-and-events).
30+
31+
4. Under **Permissions**, set the following:
32+
- Repository Permissions
33+
- Contents: Read
34+
- Read branch protection rules
35+
- Pull requests: Read
36+
- Access PR details for compliance
37+
- Organization Permissions
38+
- Administration: Read
39+
- Read organization settings
40+
- Members: Read/Write
41+
- Manage team membership
42+
43+
4. Under Set installation scope:
44+
- Where can this GitHub App be installed?: Only on this account
45+
46+
5. Click **Create GitHub App**
47+
48+
## Step 2: Generate Private Key
49+
50+
After creating the app:
51+
52+
1. Scroll to **Private keys** section
53+
2. Click **Generate a private key**
54+
3. Save the downloaded `.pem` file securely
55+
4. This file is used for `APP_GITHUB_APP_PRIVATE_KEY` or
56+
`APP_GITHUB_APP_PRIVATE_KEY_PATH`
57+
58+
## Step 3: Note Your App ID
59+
60+
On the app's settings page, find and save:
61+
62+
- **App ID** - numeric ID displayed near the top (e.g., `123456`)
63+
64+
## Step 4: Install the App
65+
66+
1. In the left sidebar, click **Install App**
67+
2. Select your organization
68+
3. Choose repository access:
69+
- **All repositories** - recommended for org-wide PR compliance
70+
- **Only select repositories** - if limiting scope
71+
4. Click **Install**
72+
73+
## Step 5: Get Installation ID
74+
75+
After installation, you'll be redirected to a URL like:
76+
```
77+
https://github.com/organizations/YOUR_ORG/settings/installations/12345678
78+
```
79+
80+
The number at the end (`12345678`) is your **Installation ID**.
81+
82+
Alternatively, use the GitHub API:
83+
```bash
84+
# List installations (requires app JWT authentication)
85+
curl -H "Authorization: Bearer YOUR_JWT" \
86+
https://api.github.com/app/installations
87+
```
88+
89+
## Step 6: Configure Environment Variables
90+
91+
Set these environment variables in your deployment:
92+
93+
```bash
94+
# Required GitHub configuration
95+
APP_GITHUB_APP_ID=123456
96+
APP_GITHUB_INSTALLATION_ID=12345678
97+
APP_GITHUB_ORG=your-org-name
98+
APP_GITHUB_WEBHOOK_SECRET=your-webhook-secret
99+
100+
# Private key (choose one method)
101+
APP_GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
102+
...
103+
-----END RSA PRIVATE KEY-----"
104+
105+
# Or use a file path
106+
APP_GITHUB_APP_PRIVATE_KEY_PATH=/path/to/private-key.pem
107+
108+
# Or use AWS SSM parameter
109+
APP_GITHUB_APP_PRIVATE_KEY=arn:aws:ssm:us-east-1:123456789:parameter/github-bot/private-key
110+
```
111+
112+
## Step 7: Configure Webhook and Events
113+
114+
After deploying your server, configure and enable webhooks:
115+
116+
1. Go to your GitHub App settings:
117+
`https://github.com/organizations/YOUR_ORG/settings/apps/YOUR_APP`
118+
2. On the **General** tab, under **Webhook**:
119+
- Set **Webhook URL** to your endpoint:
120+
- Lambda: `https://xxx.execute-api.region.amazonaws.com/webhooks`
121+
- Server: `https://your-domain.com/webhooks`
122+
- Check **Active** to enable webhooks
123+
- Click **Save changes**
124+
3. Go to the **Permissions & events** tab
125+
4. Scroll to **Subscribe to events** and check:
126+
- [x] **Pull request** - PR open, close, merge events
127+
- [x] **Team** - Team creation, deletion, changes
128+
- [x] **Membership** - Team membership changes
129+
5. Click **Save changes**
130+
131+
## Verification
132+
133+
Test your setup:
134+
135+
1. **Webhook delivery**: Check **Settings** → **Developer settings** →
136+
**GitHub Apps** → your app → **Advanced** → **Recent Deliveries**
137+
138+
2. **Create a test PR**: Open and merge a PR to a monitored branch to verify
139+
webhook reception
140+
141+
3. **Check logs**: Verify your application receives and processes the webhook
142+
143+
## Troubleshooting
144+
145+
### Webhook signature verification failed
146+
147+
- Verify `APP_GITHUB_WEBHOOK_SECRET` matches the secret in GitHub App settings
148+
- Check for whitespace or encoding issues in the secret
149+
150+
### 401 Unauthorized from GitHub API
151+
152+
- Verify the private key matches the one generated for this app
153+
- Check that the app is installed on the target organization
154+
- Ensure `APP_GITHUB_INSTALLATION_ID` is correct
155+
156+
### Missing permissions error
157+
158+
- Re-check the app's permission settings
159+
- After changing permissions, organization admins may need to re-approve
160+
161+
### Webhook not received
162+
163+
- Verify the webhook URL is accessible from the internet
164+
- Check the webhook URL doesn't have a trailing slash mismatch
165+
- Review recent deliveries in GitHub App settings for error details

0 commit comments

Comments
 (0)