GitHub App Creation Guide

Overview

GitHub Apps provide fine-grained permissions and repository-level access control. This guide walks you through creating a GitHub App for Sitepins integration, including all necessary permissions and configuration steps.

Prerequisites

Before creating a GitHub App, ensure you have:

A GitHub account with admin access to the organization (if creating for an organization)
Access to GitHub Developer Settings
Understanding of the permissions your app requires

Step 1: Access GitHub Developer Settings

Navigate to GitHub Developer Settings:
- Go to GitHub Developer Settings
- Click on “GitHub Apps” in the left sidebar
- Click “New GitHub App”

Step 2: Basic App Information

Fill in the basic app information:


App name: Sitepins
Description: Content management and site generation platform
Homepage URL: https://your-domain.com

Important: The app name must be unique across all GitHub and will be part of your app’s URL.

Step 3: Repository Permissions

Configure the following repository permissions:

Repository Permissions

Permission	Access Level	Purpose
Contents	Read & Write	Read and modify repository files
Deployments	Read	Access deployment information
Commit Statuses	Read	Access commit status information
Administration	Read & Write	Manage repository settings and configuration

Step 4: Installation Configuration

Configure where users can install your app:


Where can this GitHub App be installed?
☑️ Any account
☑️ Only on this account

Recommendation: Select “Any account” to allow users from any GitHub account to install your app.

OAuth During Installation

Enable “Request user authorization (OAuth) during installation” to:

Get user-level access tokens during app installation
Access user-specific data and repositories
Handle both app-level and user-level permissions
Simplify the authentication flow for users

Note: This approach eliminates the need for a separate OAuth app since user authorization is handled during the GitHub App installation process.

Step 5: App Creation

Review your configuration
Click “Create GitHub App”
Note down the generated App ID

Step 6: Generate Private Key

Navigate to your newly created app
Click “Generate a private key”
Download the .pem file
Store it securely - this key cannot be regenerated

Step 7: Configure Environment Variables

Add these environment variables to your application:


# GitHub App Configuration
GITHUB_APP_ID=your_app_id_here
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
 
# Note: Since you're using OAuth during installation, 
# you'll get user tokens during the installation process
# No separate OAuth app credentials needed

Step 8: Update App Settings

Installation URL

Set the installation URL to redirect users after app installation:


Installation URL: http://localhost:3000/github-installed

OAuth Configuration

Since you’re using “Request user authorization (OAuth) during installation”, configure:


User authorization callback URL: http://localhost:3000/github-installed
Redirect on update: ☑️ (checked)

Step 9: Test Your App

Install the app on a test repository
Verify webhook delivery in GitHub App settings
Test basic functionality like reading repository contents
Verify permissions are working correctly

Step 10: Production Deployment

Before going live:

Update URLs to production domain
Verify webhook endpoint is accessible
Test installation flow end-to-end
Monitor webhook delivery for errors
Set up logging for debugging

Permission Reference

Required Permissions for Sitepins


Repository Permissions:
  contents: write          # File read/write operations
  deployments: read        # Deployment information access
  commit_statuses: read    # Commit status information
  administration: write    # Repository settings management

Permission Scopes Explained

Contents (Read & Write): Allows reading and modifying files in repositories
Deployments (Read): Access to deployment information and status
Commit Statuses (Read): Access to commit status information (pending, success, failure)
Administration (Read & Write): Manage repository settings, branches, protection rules, and configuration

Troubleshooting

Common Issues

Webhook Delivery Failures:
- Check endpoint accessibility
- Verify webhook secret
- Check server logs for errors
Permission Denied Errors:
- Verify app has required permissions
- Check installation scope
- Ensure user has admin access to repository
Installation Failures:
- Verify callback URLs are correct
- Check OAuth configuration
- Ensure app is public or user has access

Debugging Tips

Use GitHub’s webhook delivery testing
Check GitHub App installation logs
Monitor webhook endpoint logs
Verify environment variables are set correctly

Security Considerations

Private Key Security:
- Never commit private keys to version control
- Use environment variables or secure secret management
- Rotate keys regularly
Webhook Security:
- Always verify webhook signatures
- Use HTTPS for all endpoints
- Implement rate limiting
Permission Principle:
- Request minimum required permissions
- Regularly review and audit permissions
- Remove unused permissions

Next Steps

After creating your GitHub App:

Implement the installation flow (see GitHub App Installations guide)
Test the OAuth during installation flow with your callback URL
Test with real repositories
Monitor usage and performance
Gather user feedback and iterate