GitHub App Guide¶

This guide walks you through creating a GitHub App for Tinkero and configuring it to receive webhooks.

Table of Contents¶

Overview
Creating the GitHub App
Configuring Permissions
Setting Up Webhooks
Generating Private Key
Installing the App
Configuring Tinkero
Validation
Troubleshooting

Overview¶

Tinkero uses a GitHub App for:

Webhook delivery: Receiving push events from repositories
Repository access: Cloning private repositories for builds
Deployment status: Creating and updating GitHub Deployments

Why a GitHub App?¶

Feature	GitHub App	Personal Access Token
Fine-grained permissions	Yes	Limited
Per-repository access	Yes	All or nothing
Webhook validation	Built-in secret	Manual setup
Token expiration	Auto-refreshed	Manual rotation
Rate limits	Higher	Standard

Creating the GitHub App¶

Step 1: Navigate to GitHub App Settings¶

Go to GitHub.com and log in
Click your profile picture (top right)
Go to Settings > Developer settings > GitHub Apps
Click New GitHub App

Or go directly to: https://github.com/settings/apps/new

Step 2: Basic Information¶

Fill in the following fields:

Field	Value	Notes
GitHub App name	`Tinkero Deploy`	Must be unique across GitHub
Description	`Automatic static site deployments`	Optional
Homepage URL	`https://lair.nntin.xyz/tinkero`	Your Tinkero domain

Step 3: Identifying and Authorizing Users¶

For Tinkero's use case, you can skip most of these settings:

Setting	Value
Callback URL	Leave empty
Request user authorization (OAuth)	Unchecked
Enable Device Flow	Unchecked

Step 4: Post Installation¶

Setting	Value
Setup URL	Leave empty
Redirect on update	Unchecked

Configuring Permissions¶

Navigate to the Permissions & events section and configure:

Repository Permissions¶

Permission	Access	Purpose
Contents	Read-only	Clone repositories for builds
Deployments	Read and write	Create deployment statuses
Metadata	Read-only	Basic repository information (auto-granted)

Account Permissions¶

No account permissions required. Leave all as No access.

Check the following events:

Event	Purpose
Push	Trigger deployments on code push

Setting Up Webhooks¶

Webhook Configuration¶

In the Webhook section:

Field	Value
Active	Checked
Webhook URL	`https://lair.nntin.xyz/tinkero/webhook`
Webhook secret	Generate a secure random string

Generating a Webhook Secret¶

You can use any method to generate a secure random string:

# Using openssl
openssl rand -hex 32

# Using /dev/urandom
head -c 32 /dev/urandom | base64 | tr -d '=' | tr '+/' '-_'

# Using Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Important: Save this secret - you'll need it when running tinkero config.

SSL/TLS Verification¶

Setting	Value
SSL verification	Enable SSL verification (default)

Only disable SSL verification for testing. Production should always use verified SSL.

Generating Private Key¶

After creating the app, you need to generate a private key for authentication.

Step 1: Find the App ID¶

After creating the app, note the App ID displayed at the top of the app settings page:

App ID: 123456

Step 2: Generate Private Key¶

Scroll to the bottom of the app settings page
Find the Private keys section
Click Generate a private key

Step 3: Download the Key¶

Your browser will download a .pem file (e.g., my-app.2024-01-08.private-key.pem).

Step 4: Store the Key Securely¶

# Move to a secure location
sudo mv ~/Downloads/my-app.*.private-key.pem /srv/tinkero/github-app-key.pem

# Set restrictive permissions
sudo chmod 600 /srv/tinkero/github-app-key.pem
sudo chown root:root /srv/tinkero/github-app-key.pem

Security Notes: - Never commit the private key to git - Keep a secure backup - If compromised, revoke and regenerate immediately

Installing the App¶

After creating the app, install it on the repositories you want to deploy.

Step 1: Access Install Page¶

From the app settings page: 1. Click Install App in the left sidebar 2. Or go to: https://github.com/apps/YOUR-APP-NAME/installations/new

Step 2: Select Account¶

Choose the GitHub account or organization where your repositories are located.

Step 3: Select Repositories¶

You can either:

Option	When to Use
All repositories	If you want to deploy all repos (not recommended)
Only select repositories	Choose specific repositories (recommended)

Step 4: Confirm Installation¶

Click Install to complete the installation.

Configuring Tinkero¶

Now configure Tinkero with your GitHub App credentials using the CLI.

Running the Config Wizard¶

# Navigate to Tinkero directory
cd /path/to/tinkero

# Run the configuration wizard
tinkero config

Configuration Walkthrough¶

🔧 GitHub App Configuration Wizard

ℹ️  This wizard will help you configure your GitHub App credentials.
ℹ️  You'll need your GitHub App ID, private key file, and webhook secret.

ℹ️  Step 1/4: Collecting GitHub App credentials...

📝 GitHub App Configuration

Enter GitHub App ID (numeric): 123456
✅ App ID: 123456

Enter path to GitHub App private key file (.pem): /srv/tinkero/github-app-key.pem
✅ Private key: /srv/tinkero/github-app-key.pem

Enter GitHub App webhook secret: your-webhook-secret-here
✅ Webhook secret configured

ℹ️  Step 2/4: Validating GitHub App credentials...
✅ Successfully validated GitHub App: Tinkero Deploy

ℹ️  Step 3/4: Updating configuration file...
✅ Configuration file updated successfully

ℹ️  Step 4/4: Restarting webhook-handler service...
✅ Webhook handler restarted successfully

Configuration Fields¶

Field	Description	Example
App ID	Numeric ID from app settings	`123456`
Private key path	Path to downloaded `.pem` file	`/srv/tinkero/github-app-key.pem`
Webhook secret	Secret you configured in the app	`abc123...`

Manual Configuration¶

If you prefer manual configuration, edit the .env file:

# Edit .env file
nano .env

# Update these values:
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY_PATH=/srv/tinkero/github-app-key.pem
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Restart the webhook handler
docker compose restart webhook-handler

Validation¶

Verify Service Health¶

tinkero health

Expected output:

✅ webhook-handler     HEALTHY

Verify Webhook Delivery¶

Go to your GitHub App settings
Click Advanced in the left sidebar
Check Recent Deliveries

Successful deliveries show a green checkmark.

Test with a Push¶

Make a change to a repository with the app installed
Add a .tinkero.yml file if not present
Push the changes
Check:
Webhook delivery in GitHub App settings
Deployment status on the commit
Tinkero logs: docker compose logs -f webhook-handler

Troubleshooting¶

Authentication Failed (401)¶

❌ Authentication failed (401 Unauthorized)

Causes: - Wrong App ID - Private key doesn't match the app - Private key was regenerated

Solutions: 1. Verify the App ID matches your GitHub App settings 2. Ensure you're using the correct private key file 3. If the key was regenerated, download the new one 4. Check the private key file is readable: ls -la /path/to/key.pem

GitHub App Not Found (404)¶

❌ GitHub App not found (404 Not Found)

Causes: - App ID is incorrect - App was deleted - App is owned by a different account

Solutions: 1. Go to https://github.com/settings/apps and verify the app exists 2. Double-check the App ID

Private Key Format Error¶

❌ Failed to generate JWT token: failed to parse private key

Causes: - Corrupted private key file - Wrong file format (not PEM) - File is empty

Solutions:

# Check the file exists and has content
cat /srv/tinkero/github-app-key.pem

# Should start with:
# -----BEGIN RSA PRIVATE KEY-----
# or
# -----BEGIN PRIVATE KEY-----

# Check file permissions
ls -la /srv/tinkero/github-app-key.pem
# Should be readable

# If corrupted, regenerate from GitHub App settings

Webhook Signature Validation Failed¶

webhook signature validation failed

Causes: - Webhook secret doesn't match - Secret was copied incorrectly (extra spaces, etc.)

Solutions: 1. Verify the secret in GitHub App settings matches .env 2. Re-enter the secret using tinkero config 3. Check for trailing whitespace:

grep GITHUB_WEBHOOK_SECRET .env

Webhooks Not Being Received¶

Causes: - App not installed on the repository - Wrong webhook URL - Firewall blocking incoming connections - SSL certificate issues