dev: improve dx

Author: sgtoj

.dockerignore

@@ -0,0 +1,5 @@
+.local/
+.env
+dist/
+tmp/
+.git/

Dockerfile

@@ -0,0 +1,11 @@
+FROM golang:1.24 AS builder
+
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o /server ./cmd/server
+
+FROM gcr.io/distroless/static-debian12
+COPY --from=builder /server /server
+ENTRYPOINT ["/server"]

Makefile

@@ -43,3 +43,15 @@ test-verify:
 test-verify-verbose:
 	go run ./cmd/verify -verbose
 
+.PHONY: server-up
+server-up:
+	docker compose up -d --build
+
+.PHONY: server-logs
+server-logs:
+	docker compose logs -f server
+
+.PHONY: server-stop
+server-stop:
+	docker compose down --rmi local --remove-orphans
+

compose.yaml

@@ -0,0 +1,10 @@
+services:
+  server:
+    build: .
+    container_name: github-ops-server
+    env_file: .env
+    ports:
+      - "${APP_PORT:-8080}:${APP_PORT:-8080}"
+    volumes:
+      - ./.local:/.local:ro
+    restart: unless-stopped

docs/github-app-setup.md

@@ -1,6 +1,7 @@
 # GitHub App Setup
 
-This guide walks through creating and installing a GitHub App for github-ops-app.
+This guide walks through creating and installing a GitHub App for
+github-ops-app.
 
 ## Prerequisites
 
@@ -9,39 +10,50 @@ This guide walks through creating and installing a GitHub App for github-ops-app
 ## Step 1: Create the GitHub App
 
 1. Navigate to your organization's settings:
+
    - Go to `https://github.com/organizations/YOUR_ORG/settings/apps`
-   - Or: **Organization** → **Settings** → **Developer settings** → **GitHub Apps**
+   - Or: **Organization** → **Settings** → **Developer settings** → **GitHub
+     Apps**
 
 2. Click **New GitHub App**
 
 3. Fill in the basic information:
 
-    | Field                 | Value                                           |
-    |-----------------------|-------------------------------------------------|
-    | GitHub App name       | `github-ops-app` (must be unique across GitHub) |
-    | Homepage URL          | Your organization's URL or repo URL             |
-    | Webhook > Webhook URL | Leave blank for now                             |
-    | Webhook > Secret      | Generate a strong secret (save this for later)  |
-    | Webhook > Active      | **Uncheck** to disable webhooks initially       |
-
-    > **Note**: Disable webhooks during creation since you may not know your
-    > endpoint URL until after deployment. You'll configure webhooks and
-    > subscribe to events in [Step 7](#step-7-configure-webhook-and-events).
-
-4. Under **Permissions**, set the following:
-   - Repository Permissions
-     - Contents: Read
-       - Read branch protection rules
-     - Pull requests: Read
-       - Access PR details for compliance
-   - Organization Permissions
-     - Administration: Read
-       - Read organization settings
-     - Members: Read/Write
-       - Manage team membership
-
-4. Under Set installation scope:
-   - Where can this GitHub App be installed?: Only on this account
+   | Field                 | Value                                           |
+   | --------------------- | ----------------------------------------------- |
+   | GitHub App name       | `github-ops-app` (must be unique across GitHub) |
+   | Homepage URL          | Your organization's URL or repo URL             |
+   | Webhook > Webhook URL | Leave blank for now                             |
+   | Webhook > Secret      | Generate a strong secret (save this for later)  |
+   | Webhook > Active      | **Uncheck** to disable webhooks initially       |
+
+   > **Note**: Disable webhooks during creation since you may not know your
+   > endpoint URL until after deployment. You'll configure webhooks and
+   > subscribe to events in [Step 7](#step-7-configure-webhook-and-events).
+
+### Configure Permissions
+
+Under **Permissions**, set the following:
+
+### Repository Permissions
+
+| Permission    | Access | Purpose                          |
+| ------------- | ------ | -------------------------------- |
+| Contents      | Read   | Read branch protection rules     |
+| Pull requests | Read   | Access PR details for compliance |
+
+#### Organization Permissions
+
+| Permission     | Access     | Purpose                    |
+| -------------- | ---------- | -------------------------- |
+| Members        | Read/Write | Manage team membership     |
+| Administration | Read       | Read organization settings |
+
+4. Set installation scope:
+
+   | Setting                                 | Value                |
+   | --------------------------------------- | -------------------- |
+   | Where can this GitHub App be installed? | Only on this account |
 
 5. Click **Create GitHub App**
 
@@ -73,13 +85,15 @@ On the app's settings page, find and save:
 ## Step 5: Get Installation ID
 
 After installation, you'll be redirected to a URL like:
+
 ```
 https://github.com/organizations/YOUR_ORG/settings/installations/12345678
 ```
 
 The number at the end (`12345678`) is your **Installation ID**.
 
 Alternatively, use the GitHub API:
+
 ```bash
 # List installations (requires app JWT authentication)
 curl -H "Authorization: Bearer YOUR_JWT" \
@@ -115,25 +129,40 @@ After deploying your server, configure and enable webhooks:
 
 1. Go to your GitHub App settings:
    `https://github.com/organizations/YOUR_ORG/settings/apps/YOUR_APP`
-2. On the **General** tab, under **Webhook**:
-   - Set **Webhook URL** to your endpoint:
-     - Lambda: `https://xxx.execute-api.region.amazonaws.com/webhooks`
-     - Server: `https://your-domain.com/webhooks`
-   - Check **Active** to enable webhooks
-   - Click **Save changes**
-3. Go to the **Permissions & events** tab
-4. Scroll to **Subscribe to events** and check:
+
+2. Set **Webhook URL** to your endpoint:
+
+   - Lambda: `https://xxx.execute-api.region.amazonaws.com/webhooks`
+   - Server: `https://your-domain.com/webhooks`
+
+3. Check **Active** to enable webhooks
+
+4. Click **Save changes**
+
+5. Under **Subscribe to events**, check:
+
    - [x] **Pull request** - PR open, close, merge events
    - [x] **Team** - Team creation, deletion, changes
    - [x] **Membership** - Team membership changes
-5. Click **Save changes**
+
+6. Click **Save changes**
+
+## Using the App Manifest (Alternative)
+
+For automated setup, use the manifest at `assets/github/manifest.json`:
+
+1. Go to `https://github.com/settings/apps/new`
+2. Append `?manifest=` with URL-encoded manifest JSON
+3. Or use the manifest creation API
+
+The manifest pre-configures all required permissions and events.
 
 ## Verification
 
 Test your setup:
 
-1. **Webhook delivery**: Check **Settings** → **Developer settings** →
-   **GitHub Apps** → your app → **Advanced** → **Recent Deliveries**
+1. **Webhook delivery**: Check **Settings** → **Developer settings** → **GitHub
+   Apps** → your app → **Advanced** → **Recent Deliveries**
 
 2. **Create a test PR**: Open and merge a PR to a monitored branch to verify
    webhook reception

docs/okta-setup.md

@@ -11,14 +11,18 @@ github-ops-app to sync Okta groups with GitHub teams.
 ## Step 1: Create API Services Application
 
 1. Log in to your **Okta Admin Console**
+
 2. Navigate to **Applications** → **Applications**
+
 3. Click **Create App Integration**
+
 4. Select **API Services** and click **Next**
 
    > API Services apps use OAuth 2.0 client credentials flow with no user
    > context, ideal for server-to-server integrations.
 
 5. Enter application name: `github-ops-app` (or similar)
+
 6. Click **Save**
 
 ## Step 2: Configure Client Authentication
@@ -64,12 +68,13 @@ On the **General** tab, find and save:
 ## Step 5: Grant API Scopes
 
 1. Go to the **Okta API Scopes** tab
+
 2. Grant the following scopes:
 
-   | Scope              | Purpose                       |
-   |--------------------|-------------------------------|
-   | `okta.groups.read` | Read group names and members  |
-   | `okta.users.read`  | Read user profiles            |
+   | Scope              | Purpose                      |
+   | ------------------ | ---------------------------- |
+   | `okta.groups.read` | Read group names and members |
+   | `okta.users.read`  | Read user profiles           |
 
 3. Click **Grant** for each scope
 
@@ -82,22 +87,26 @@ API Services applications require an admin role to access Okta APIs. Without
 this, API calls will fail with permission errors even if scopes are granted.
 
 1. Go to the **Admin roles** tab for your application
+
 2. Click **Edit assignments**
+
 3. Select one of the following roles:
 
-   | Role                | Access Level                                  |
-   |---------------------|-----------------------------------------------|
-   | **Read Only Admin** | Read access to all resources (recommended)    |
-   | **Group Admin**     | Full access to groups only                    |
+   | Role                | Access Level                               |
+   | ------------------- | ------------------------------------------ |
+   | **Read Only Admin** | Read access to all resources (recommended) |
+   | **Group Admin**     | Full access to groups only                 |
 
 4. If using **Group Admin**, optionally restrict to specific groups:
-   - Under **Edit constraints for Group Administrator**, select specific
-     groups or group types the app can access
+
+   - Under **Edit constraints for Group Administrator**, select specific groups
+     or group types the app can access
+
 5. Click **Save changes**
 
-> **Note**: Read Only Admin is recommended for sync operations since it
-> provides sufficient access without write permissions. Group Admin is an
-> alternative if you need to limit the app's scope to group resources only.
+> **Note**: Read Only Admin is recommended for sync operations since it provides
+> sufficient access without write permissions. Group Admin is an alternative if
+> you need to limit the app's scope to group resources only.
 
 ## Step 7: Identify Your Okta Domain
 
@@ -113,12 +122,12 @@ Use the domain without `https://` prefix for `APP_OKTA_DOMAIN`.
 The app needs to map Okta users to GitHub usernames. Determine which Okta user
 profile field contains GitHub usernames:
 
-| Common Fields      | Description                              |
-|--------------------|------------------------------------------|
-| `login`            | Okta username (often email)              |
-| `email`            | User's email address                     |
-| `githubUsername`   | Custom field (recommended)               |
-| `nickName`         | Sometimes used for GitHub username       |
+| Common Fields    | Description                        |
+| ---------------- | ---------------------------------- |
+| `login`          | Okta username (often email)        |
+| `email`          | User's email address               |
+| `githubUsername` | Custom field (recommended)         |
+| `nickName`       | Sometimes used for GitHub username |
 
 ### Adding a Custom GitHub Username Field (Recommended)
 
@@ -141,13 +150,14 @@ rules:
 
 **Example naming conventions:**
 
-| Pattern              | Example Groups                               |
-|----------------------|----------------------------------------------|
-| `github-{team}`      | `github-engineering`, `github-platform`      |
-| `gh-eng-{team}`      | `gh-eng-frontend`, `gh-eng-backend`          |
-| `Team - {name}`      | `Team - Platform`, `Team - Security`         |
+| Pattern         | Example Groups                          |
+| --------------- | --------------------------------------- |
+| `github-{team}` | `github-engineering`, `github-platform` |
+| `gh-eng-{team}` | `gh-eng-frontend`, `gh-eng-backend`     |
+| `Team - {name}` | `Team - Platform`, `Team - Security`    |
 
 Groups can be:
+
 - Okta groups (manually managed)
 - Groups synced from Active Directory
 - Groups from other identity providers
@@ -192,18 +202,18 @@ APP_OKTA_SYNC_RULES='[
 
 ### Rule Fields
 
-| Field                   | Description                                          |
-|-------------------------|------------------------------------------------------|
-| `name`                  | Rule identifier (for logging)                        |
-| `enabled`               | Enable/disable rule (default: `true`)                |
-| `okta_group_pattern`    | Regex to match Okta groups                           |
-| `okta_group_name`       | Exact Okta group name (alternative to pattern)       |
-| `github_team_prefix`    | Prefix for generated GitHub team names               |
-| `github_team_name`      | Exact GitHub team name (overrides pattern)           |
-| `strip_prefix`          | Remove this prefix from Okta group name              |
-| `sync_members`          | Sync members between Okta and GitHub (default: `true`)|
-| `create_team_if_missing`| Auto-create GitHub teams if they don't exist         |
-| `team_privacy`          | GitHub team visibility: `secret` or `closed`         |
+| Field                    | Description                                            |
+| ------------------------ | ------------------------------------------------------ |
+| `name`                   | Rule identifier (for logging)                          |
+| `enabled`                | Enable/disable rule (default: `true`)                  |
+| `okta_group_pattern`     | Regex to match Okta groups                             |
+| `okta_group_name`        | Exact Okta group name (alternative to pattern)         |
+| `github_team_prefix`     | Prefix for generated GitHub team names                 |
+| `github_team_name`       | Exact GitHub team name (overrides pattern)             |
+| `strip_prefix`           | Remove this prefix from Okta group name                |
+| `sync_members`           | Sync members between Okta and GitHub (default: `true`) |
+| `create_team_if_missing` | Auto-create GitHub teams if they don't exist           |
+| `team_privacy`           | GitHub team visibility: `secret` or `closed`           |
 
 See the [main README](../README.md#okta-sync-rules) for additional examples.
 
@@ -221,6 +231,7 @@ Test your Okta configuration:
 ```
 
 Trigger a sync and verify:
+
 1. POST to `/scheduled/okta-sync` endpoint
 2. Check logs for groups discovered and teams synced
 3. Verify GitHub team memberships match Okta groups
@@ -249,6 +260,7 @@ Trigger a sync and verify:
 ### Rate limiting
 
 Okta has API rate limits. If you hit limits:
+
 - Reduce sync frequency
 - The app handles rate limit responses gracefully