Skip to content

Commit 08e1fa7

Browse files
sgtojsgtoj
committed
docs: improve documentation and add setups guides
1 parent e164336 commit 08e1fa7

File tree

4 files changed

+703
-39
lines changed

4 files changed

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

0 commit comments

Comments
 (0)