GitHub Integration

Oore integrates with GitHub using a GitHub App, providing:

• Webhook events for push, pull request, and installation events
• Installation tokens for cloning private repositories
• Commit status updates for build results
• Automatic sync when the app is installed on new repositories

Setup via CLI (Recommended)

The CLI provides a streamlined setup experience that automates the entire GitHub App creation and installation process.

Prerequisites

Before starting, ensure:

• Your Oore server is running and accessible
• You have an ENCRYPTION_KEY configured (required to store credentials securely)
• You have OORE_ADMIN_TOKEN set in your environment or .env file

Automated Setup Flow

1. Run the setup command

   oore github setup

   The CLI will automatically open your browser to GitHub’s app creation page and show a progress spinner while waiting.

   Tip

   The CLI reads OORE_ADMIN_TOKEN from your environment or .env file automatically. You can also pass it explicitly with --admin-token YOUR_TOKEN if needed.

2. Create the app on GitHub

   • Review the pre-filled app configuration
   • Choose where to create the app (personal account or organization)
   • Click “Create GitHub App”
   • The browser will show a success message and redirect to the installation page

3. Install the app

   • Select which repositories to grant access (all or specific ones)
   • Click “Install”
   • Repositories sync automatically via webhooks

4. Verify in your terminal

   Once you complete the installation, the CLI displays:

   ✓ GitHub App configured successfully!
   
     Name: Oore CI
     App ID: 123456
   
     Complete the installation in your browser to select repositories.
     Repositories will sync automatically via webhooks.

That’s it! The entire flow happens in a single browser tab, and repositories sync automatically when you install the app.

---

How It Works

The setup process uses GitHub’s App Manifest flow:

CLI                    oored                    GitHub
 │                       │                        │
 │  github setup         │                        │
 ├──────────────────────▶│                        │
 │                       │ Generate manifest      │
 │  Opens browser        │                        │
 │───────────────────────┼───────────────────────▶│
 │                       │                        │
 │  Polls status         │                        │ User creates app
 │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│                        │
 │                       │                        │
 │                       │◀──── Callback ─────────┤
 │                       │  Exchange code         │
 │                       │  Store credentials     │
 │                       │                        │
 │  Success!             │  Browser redirects ───▶│ Install app
 │◀──────────────────────┤                        │
 │                       │                        │
 │                       │◀── Installation hook ──┤
 │                       │  Auto-sync repos       │

Once configured:

• Credentials are stored encrypted in the database (AES-256-GCM)
• No environment variables needed for GitHub config
• Private key, webhook secret, and app details are managed automatically
• Installation and repository changes sync via webhooks

---

Webhook Processing

When GitHub sends webhooks:

GitHub                          oored                      Build
  │                               │                          │
  │  POST /webhooks/github        │                          │
  ├──────────────────────────────▶│                          │
  │                               │ 1. Verify signature      │
  │                               │ 2. Store event           │
  │                               │ 3. Queue for processing  │
  │        {"status":"ok"}        │                          │
  │◀──────────────────────────────┤                          │
  │                               │ 4. Process background    │
  │                               │ 5. Create build          │
  │                               │ 6. Execute               │
  │                               ├─────────────────────────▶│

Supported Events

Event	Trigger
push	Code pushed to any branch
pull_request.opened	New pull request
pull_request.synchronize	PR updated with new commits
installation	App installed or modified
installation_repositories	Repositories added/removed from installation

Automatic Sync

When you install the GitHub App or modify repository access, Oore automatically syncs:

• New installations are added to the database
• Repository lists are updated
• Removed repositories are cleaned up

No manual oore github sync required for normal operations.

Signature Verification

GitHub signs webhooks using HMAC-SHA256. The X-Hub-Signature-256 header contains:

sha256=<hex-encoded-signature>

Oore verifies this signature using the webhook secret stored during setup.

---

CLI Commands Reference

Command	Description
oore github setup	Start GitHub App creation (opens browser, polls for completion)
oore github callback <URL>	Manual callback completion (fallback if browser automation fails)
oore github status	Show current GitHub App configuration
oore github installations	List all installations
oore github sync	Manually sync installations and repositories
oore github remove --force	Remove GitHub App credentials

All commands require authentication. Set OORE_ADMIN_TOKEN in your environment or .env file, or pass --admin-token explicitly.

---

Manual Sync (When Needed)

In most cases, webhooks handle synchronization automatically. Manual sync is useful when:

• Recovering from server downtime
• Debugging installation issues
• Webhooks were missed

oore github sync

Output:

Syncing GitHub installations and repositories...

Sync completed
  Installations synced: 1
  Repositories synced:  3

---

Manual Sync (When Needed)

In most cases, webhooks handle synchronization automatically. Manual sync is useful when:

• Recovering from server downtime
• Debugging installation issues
• Webhooks were missed

oore github sync --admin-token YOUR_TOKEN

Output:

Syncing GitHub installations and repositories...

Sync completed
  Installations synced: 1
  Repositories synced:  3

---

Troubleshooting

”ENCRYPTION_NOT_CONFIGURED” Error

The manifest flow requires an encryption key to securely store credentials.

Add to /etc/oore/oore.env:

ENCRYPTION_KEY=$(openssl rand -hex 32)

Then restart the server.

”ALREADY_CONFIGURED” Error

A GitHub App is already configured. To replace it:

oore github remove --force
oore github setup

Browser Doesn’t Open

If the CLI can’t open your browser automatically, it will print the URL:

! Could not open browser automatically: <error>

Please open this URL manually:
  https://your-server.com/setup/github/create?state=abc123...

Open the URL manually and complete the setup. The CLI will detect completion via polling.

Webhooks Not Received

1. Check URL accessibility: Your server must be publicly accessible (not localhost)
2. Check HTTPS: GitHub requires HTTPS for webhooks
3. Check firewall: Ensure the port is open
4. View deliveries: Go to your GitHub App settings → Advanced → Recent Deliveries

Invalid Signature Errors

1. Run oore github sync to refresh credentials
2. Check that the webhook URL matches your server’s OORE_BASE_URL
3. Reinstall the GitHub App if issues persist

Installation Not Syncing

If installations don’t appear after installing the app:

1. Check that webhooks are being received (server logs)
2. Run oore github sync to force a sync
3. Verify the app has the correct webhook URL configured

---

Complete Example

# 1. Ensure OORE_ADMIN_TOKEN is set (in .env or environment)
echo "OORE_ADMIN_TOKEN=your-secure-token" >> .env

# 2. Run setup (opens browser automatically)
oore github setup

# 3. Complete app creation and installation in browser
#    - Create the app
#    - Select repositories to install
#    - Done!

# 4. Verify setup
oore github status
oore github installations

# 5. Push code to trigger a build
git push origin main

# 6. Check builds
oore build list