Skip to content

GitHub App Setup

Create and connect a GitHub App to SkillMeat for higher API rate limits, fine-grained repository permissions, and server-to-server authentication without tying tokens to personal accounts.

GitHub App vs. Personal Access Token

SkillMeat supports two types of GitHub authentication. Choose based on your deployment scenario:

Feature GitHub App Personal Access Token (PAT)
Rate limit 5,000 req/hr per installation 5,000 req/hr per token
Token ownership Organization or GitHub user Tied to personal account
Permission model Fine-grained by repository Coarse scopes (repo, read:user)
Token rotation Easier (app-level key rotation) Tied to person; harder to rotate
Best for Teams, organizations, service accounts Individual developers, quick setup
Setup complexity 10 minutes (create app, install, register) 5 minutes (create token, paste)

Choose GitHub App if: - You're running SkillMeat for a team or organization - You want fine-grained per-repository access - You need higher rate limits - You want to avoid tying tokens to personal accounts - You want easier token rotation and key management

Choose PAT if: - You're a single developer using SkillMeat locally - You want the quickest setup - You're running a short-lived demo - See GitHub Authentication Guide for PAT setup

Prerequisites

  • GitHub account or organization admin access (to create the GitHub App)
  • A reachable URL for your SkillMeat instance (IP address or hostname — HTTPS not required for the App creation itself)

For demo/self-hosted setups, you can use a plain HTTP IP address like http://16.59.188.76 (GitHub does not callback to your instance for GitHub App token acquisition).

Step 1: Create the GitHub App

Navigate to your GitHub account or organization settings:

  1. Go to Settings → Developer settings → GitHub Apps (or in your organization, Settings → Developer settings → GitHub Apps)
  2. Click New GitHub App

Fill in the form as follows:

Field Value Notes
GitHub App name e.g., SkillMeat Demo or SkillMeat Prod Must be globally unique on GitHub (includes all orgs)
Homepage URL Your SkillMeat instance URL, e.g., http://16.59.188.76 or https://skillmeat.mycompany.com GitHub displays this; not used for callbacks
Callback URL Leave blank SkillMeat uses server-to-server tokens; no OAuth callback needed
Setup URL Leave blank Optional post-install redirect; unused by SkillMeat
Webhook → Active Uncheck SkillMeat does not process webhooks yet; leaving this on causes spurious retries
Request user authorization (OAuth) during installation Uncheck SkillMeat does not use the OAuth user-login flow

Permission Configuration

Scroll down to Permissions and set the minimum required for SkillMeat's current features:

Repository Permissions: - Contents: Read-only (required for reading code and files) - Metadata: Read-only (auto-required by GitHub; used for repo information) - Pull requests: Read-only (optional now, recommended for future PR-aware workflows)

Organization Permissions: - None required

Account Permissions: - None required

Installation Scope

Under "Where can this GitHub App be installed?":

  • Only on this account — for demos or single-org setups (recommended for testing)
  • Any account — if you want others to install this app (not needed for most demos)

Click Create GitHub App.

Step 2: Collect the App Credentials

You now have a GitHub App. Collect three values:

App ID

On the app's settings page, scroll to the top. The App ID is displayed under the app name. Copy this value — you'll need it as GITHUB_APP_ID.

Example: 12345

Private Key

On the same page, scroll down to Private keys and click Generate a private key. A .pem file downloads immediately. Save this file securely.

The private key file looks like:

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA1234567890...
...
-----END RSA PRIVATE KEY-----

You'll pass the contents of this file to SkillMeat as GITHUB_APP_PRIVATE_KEY.

Installation ID

Now you must install the GitHub App on the user account or organization where you want to scan repositories.

  1. On the GitHub App's settings page, scroll down and look for an Install App link (or go to your own GitHub Apps list and click Install).
  2. Select the account/org to install on.
  3. Grant repository access:
  4. All repositories — SkillMeat can access all repos (default; recommended)
  5. Only select repositories — choose specific repos (more restrictive)
  6. Click Install.

After installation, you'll be redirected to the installation settings page. The URL contains the Installation ID:

https://github.com/settings/installations/67890

In this example, 67890 is your GITHUB_APP_INSTALLATION_ID.

If you lose this URL, navigate to your GitHub App's settings page and click Install App, then select the installed account/org — the settings page URL will show the ID again.

Step 3: Connect to SkillMeat

You now have three credentials: - GITHUB_APP_ID (example: 12345) - GITHUB_APP_INSTALLATION_ID (example: 67890) - GITHUB_APP_PRIVATE_KEY (the .pem file contents)

Choose one of three setup methods:

  1. Start SkillMeat: skillmeat web dev
  2. Navigate to Settings → GitHub → GitHub Apps (or similar path in your instance)
  3. Click Add GitHub App
  4. Upload the .pem file (private key)
  5. Enter your App ID (12345)
  6. Enter your Installation ID (67890)
  7. Click Save
  8. Click Test to verify the connection

SkillMeat stores the private key encrypted in its database.

If the test succeeds, SkillMeat can now acquire installation tokens and authenticate GitHub API requests.

Option B: Environment Variables

Set these before starting SkillMeat:

export GITHUB_APP_ID=12345
export GITHUB_APP_INSTALLATION_ID=67890
export GITHUB_APP_PRIVATE_KEY="$(cat /path/to/private-key.pem)"

If using a shell that doesn't support $(...) syntax, you can set the key with literal escaped newlines:

export GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIB...\n-----END RSA PRIVATE KEY-----"

Or in a .env file:

GITHUB_APP_ID=12345
GITHUB_APP_INSTALLATION_ID=67890
GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA1234567890...
-----END RSA PRIVATE KEY-----

Then start SkillMeat (which loads .env automatically):

skillmeat web dev

Option C: REST API

If SkillMeat is already running and you have an authentication token:

# Register the GitHub App credential
curl -X POST http://localhost:8080/api/v1/github-apps \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": 12345,
    "installation_id": 67890,
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIB...\n-----END RSA PRIVATE KEY-----"
  }'

# Response includes credential ID
# {
#   "id": "gh-app-cred-123",
#   "app_id": 12345,
#   "installation_id": 67890,
#   "created_at": "2026-05-13T10:30:00Z"
# }

To test the credential:

curl -X POST http://localhost:8080/api/v1/github-apps/gh-app-cred-123/test \
  -H "Authorization: Bearer YOUR_TOKEN"

# On success: { "valid": true, "message": "Successfully acquired installation token" }
# On failure: { "valid": false, "message": "..." }

To list registered credentials:

curl http://localhost:8080/api/v1/github-apps \
  -H "Authorization: Bearer YOUR_TOKEN"

To delete a credential:

curl -X DELETE http://localhost:8080/api/v1/github-apps/gh-app-cred-123 \
  -H "Authorization: Bearer YOUR_TOKEN"

How Token Resolution Works

When SkillMeat makes a GitHub API request, it tries authentication methods in this order:

  1. GitHub App installation token — if a GitHub App is registered, acquire a fresh token (~55-minute cache, auto-refresh)
  2. Personal Access Token (PAT) — if configured in Settings or environment (GITHUB_TOKEN, SKILLMEAT_GITHUB_TOKEN)
  3. Unauthenticated — if no credentials are configured, use the public API rate limit (60 req/hr)

If a GitHub App is configured, SkillMeat always prefers it over PATs.

Current Limitations

  • No webhook processing yet — GitHub will deliver webhooks if configured, but SkillMeat ignores them. Leave webhooks disabled (Webhook → Active: unchecked).
  • GitHub.com only — GitHub Enterprise Server (self-hosted) base URLs are not yet supported.
  • One installation per credential — to access multiple organizations, register multiple GitHub Apps or multiple installation credentials.
  • No in-app App creation wizard — you must create the App in GitHub's settings; SkillMeat only consumes the credentials.
  • No expiration alerts — private keys may expire; track expiration dates manually and regenerate when needed.

Troubleshooting

Test Returns 401/403 Unauthorized

Cause: Wrong App ID, wrong Installation ID, or the App is not installed on the target account.

Fix: 1. Re-check your App ID (top of app settings page) 2. Re-check your Installation ID (from the installation URL: https://github.com/settings/installations/INSTALLATION_ID) 3. Verify the App is installed on the account/org where you want to access repos: - Go to your GitHub App's settings page - Scroll to Install App and click it - Confirm the account/org is listed as installed - If not, install it

Test Returns Success but GitHub API Calls Return 404

Cause: App is installed but doesn't have access to the specific repository.

Fix: 1. Go to the installation settings page (URL: https://github.com/settings/installations/INSTALLATION_ID) 2. Under Repository access, ensure the repositories you want to access are listed - If set to All repositories, any new repos are automatically included - If set to Only select repositories, add the missing repo to the list 3. Click Save and retry SkillMeat

Private Key Parse Error

Cause: PEM-formatted key was corrupted during copy-paste, or has missing newlines.

Fix: 1. Return to the GitHub App settings page 2. Scroll to Private keys and click Generate a private key (regenerates a fresh key) 3. Download the .pem file 4. Use Option A (Web UI file upload) or Option B (cat` file into the environment variable) — avoid manual copy-paste

Token Refresh Not Happening (Cached Token Used)

Cause: SkillMeat caches installation tokens for ~55 minutes. If you recently changed permissions or rotated the app key, the old token is still in use.

Fix: 1. Clear the SkillMeat token cache:

curl -X POST http://localhost:8080/api/v1/cache/refresh \
  -H "Authorization: Bearer YOUR_TOKEN"
  1. Retry the operation — a fresh token will be acquired

Examples

Demo Instance Using GitHub App

Deploy a demo instance on a VM with a GitHub App:

# On VM: 16.59.188.76

# 1. Create app on github.com; get credentials (as described above)
# 2. Set environment variables
export GITHUB_APP_ID=12345
export GITHUB_APP_INSTALLATION_ID=67890
export GITHUB_APP_PRIVATE_KEY="$(cat ~/private-key.pem)"

# 3. Start SkillMeat
skillmeat web dev

# 4. Verify it works
curl http://16.59.188.76:8080/api/v1/artifacts  # Should list artifacts (if auth is not enforced)

Team Deployment with Organization App

For a team using an organization's GitHub App:

  1. Create the GitHub App in the org's Settings → Developer settings → GitHub Apps
  2. Install the app on the organization
  3. Have each team member register the shared credentials in SkillMeat's Settings UI
  4. The same App ID and Installation ID are used by all team members

Each SkillMeat instance acquiring a token gets its own temporary installation token, valid for ~1 hour.

CI/CD Pipeline Using GitHub App

Use a GitHub App in a CI/CD workflow (GitHub Actions example):

name: Sync SkillMeat Artifacts

on:
  schedule:
    - cron: "0 */6 * * *"  # Every 6 hours

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Configure GitHub App
        run: |
          export GITHUB_APP_ID=${{ secrets.GITHUB_APP_ID }}
          export GITHUB_APP_INSTALLATION_ID=${{ secrets.GITHUB_APP_INSTALLATION_ID }}
          export GITHUB_APP_PRIVATE_KEY="${{ secrets.GITHUB_APP_PRIVATE_KEY }}"

      - name: Sync artifacts
        run: |
          skillmeat sync pull

Store the credentials as GitHub Actions secrets:

  1. Go to your repo → Settings → Secrets and variables → Actions
  2. Add three secrets:
  3. GITHUB_APP_ID = 12345
  4. GITHUB_APP_INSTALLATION_ID = 67890
  5. GITHUB_APP_PRIVATE_KEY = (paste the entire .pem file content)

See Also