GitHub App Setup

Step-by-step guide to set up GitHub App authentication

Overview

This guide explains how to create and configure a GitHub App for Orphelix.

Setting up a GitHub App takes about 5-10 minutes and provides the most secure integration method.

Step 1: Create GitHub App

For Personal Account

1. Navigate to GitHub Settings

   Go to GitHub Settings → Developer settings → GitHub Apps

2. Click New GitHub App

   Click the “New GitHub App” button

For Organization

1. Go to Organization Settings

   Navigate to your organization → Settings → Developer settings → GitHub Apps

2. Click New GitHub App

   Click the “New GitHub App” button

Step 2: Configure Basic Settings

Fill in the following fields in the GitHub App creation form:

Field	Value	Description
GitHub App name	Orphelix (or any unique name)	Display name for the app
Homepage URL	http://localhost:3000	Your Orphelix URL
Callback URL	http://localhost:3000/api/github-app/callback	OAuth callback endpoint
Setup URL	Leave empty	Not needed
Webhook	❌ Disable “Active”	We don’t use webhooks

Make sure to uncheck the “Active” checkbox under Webhook settings - Orphelix doesn’t use webhooks.

Step 3: Set Permissions

Under Repository permissions, configure the following:

Contents

Access level: Read and write

Required for:

• Reading YAML files from repository
• Creating/updating files for PRs

Pull requests

Access level: Read and write

Required for:

• Creating pull requests
• Listing and viewing PRs
• Merging PRs (optional)

Metadata

Access level: Read-only

Automatically set by GitHub, required for all apps

Summary of Permissions

Repository permissions:
  ✅ Contents: Read and write
  ✅ Pull requests: Read and write
  ✅ Metadata: Read-only (auto)

Step 4: Create the App

1. Click Create GitHub App

   Scroll to the bottom and click “Create GitHub App”

2. Confirm creation

   You’ll be redirected to your new GitHub App’s settings page

Step 5: Install the App

1. Click Install App

   In the left sidebar, click “Install App”

2. Choose account

   Select your personal account or organization

3. Select repositories

   Choose repository access:

   • All repositories - Grant access to all current and future repos
   • Only select repositories - Choose specific repos (recommended)

   For security, select only repositories containing your Kubernetes manifests

4. Click Install

   Click “Install” to complete the installation

Step 6: Get Credentials

You need three credentials to configure Orphelix:

1. App ID

1. Go to app settings

   Navigate back to your GitHub App settings page

2. Find App ID

   Look for “App ID” near the top of the page (e.g., 123456)

3. Copy App ID

   Note this number - you’ll need it for .env.local

2. Client ID & Client Secret

1. Find Client ID

   On the app settings page, locate “Client ID”

2. Generate Client Secret

   Click “Generate a new client secret”

3. Copy immediately

   Copy the client secret immediately - it will only be shown once!

3. Private Key

1. Scroll to Private keys section

   On the app settings page, scroll down to “Private keys”

2. Generate key

   Click “Generate a private key”

3. Save .pem file

   A .pem file will download automatically

   Keep this file secure! It’s like a password for your GitHub App.

Step 7: Configure Environment Variables

Create or update .env.local in your Orphelix project root:

# GitHub App Configuration
GITHUB_APP_ID=123456
GITHUB_APP_CLIENT_ID=Iv1.abc123def456
GITHUB_APP_CLIENT_SECRET=your_client_secret_here

# Private key (convert .pem to base64)
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
...
-----END RSA PRIVATE KEY-----"

# NextAuth configuration
NEXTAUTH_SECRET=your_random_secret_here
NEXTAUTH_URL=http://localhost:3000

# Optional: OpenAI for AI-powered file matching
OPENAI_API_KEY=sk-...

Converting Private Key

macOS/Linux

# Display private key content
cat path/to/your-app.pem

# Copy the entire output including BEGIN/END lines
# Paste into .env.local as GITHUB_APP_PRIVATE_KEY value

Windows

# Open .pem file in notepad
notepad path\to\your-app.pem

# Copy entire content including BEGIN/END lines
# Paste into .env.local as GITHUB_APP_PRIVATE_KEY value

Make sure to keep the quotes around the private key value and preserve all line breaks

Generating NEXTAUTH_SECRET

# Generate a random secret (32+ characters)
openssl rand -base64 32

Step 8: Verify Installation

1. Start Orphelix

   npm run dev
   
2. Open Settings

   Navigate to Settings page in Orphelix

3. Click GitHub Integration

   Go to GitHub Integration section

4. Click Login with GitHub App

   You should see a “Login with GitHub App” button

5. Authorize

   Click the button and authorize the app

6. Select repository

   After authorization, select a repository from the dropdown

7. Test YAML editor

   Go to a deployment detail page and click “Edit YAML”

   You should see the Monaco editor with your deployment YAML!

Troubleshooting

App not showing in Settings

Possible causes:

• Environment variables not set correctly
• .env.local not loaded (restart dev server)
• NEXTAUTH_SECRET not generated

Solution:

# Check if .env.local exists
cat .env.local

# Restart dev server
npm run dev

Authorization fails

Possible causes:

• Callback URL mismatch
• Client ID/Secret incorrect

Solution:

• Verify callback URL is exactly: http://localhost:3000/api/github-app/callback
• Double-check Client ID and Secret in .env.local

Cannot read repositories

Possible causes:

• App not installed on repository
• Missing Contents permission

Solution:

• Go to GitHub Settings → Applications → Installed GitHub Apps
• Click Configure on your app
• Verify repository access

Private key errors

Possible causes:

• Private key format incorrect
• Missing BEGIN/END lines
• Extra quotes or escaping

Solution:

• Ensure private key includes -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----
• Use double quotes around the entire key
• Preserve line breaks

Production Deployment

For production, update these values:

# Production callback URL
GITHUB_APP_CALLBACK_URL=https://your-domain.com/api/github-app/callback
NEXTAUTH_URL=https://your-domain.com

# Update in GitHub App settings too!

Remember to update the Callback URL in your GitHub App settings when deploying to production!

Security Best Practices

Private Key Storage

• Never commit .env.local to git
• Store private key in secure secret manager (production)
• Rotate keys periodically

Repository Access

• Only grant access to necessary repositories
• Use “Only select repositories” instead of “All repositories”
• Review access permissions regularly

Token Management

• Tokens are stored in HTTP-only cookies
• Automatic refresh every 8 hours
• Revoke access from GitHub when not needed

Next Steps

Use YAML Editor

Learn how to edit Kubernetes manifests

Create Pull Requests

Create and manage PRs