Connect GitHub

Helpin connects to GitHub through a GitHub App that belongs to your installation. It links tasks to repositories and lets coding agents open pull requests. You can create the App from Helpin in a couple of clicks, with no manual key copying.

Requirements

GitHub has to reach your server, so APP_BASE_URL must be a public HTTPS hostname. Helpin disables Create GitHub App and explains why when the URL uses http, localhost, a .local or single-label hostname, or a private IP address.

Evaluating locally? Finish public deployment first, or pin an App you've already created (see below).

Create the App from Helpin

A workspace owner can start from Settings → Git Connections, the Setup guide, or Settings → System status.

1. Select Create GitHub App.

2. Choose the owner:

   • A GitHub organization (recommended). Enter the organization's login.

   • Your personal account. The App can then only reach your personal repositories.

3. GitHub asks you to confirm the new App. Confirm it.

4. Helpin takes you straight to GitHub's install page. Choose repositories and select Install.

5. You return to Helpin with the installation connected to your organization.

The App takes effect immediately, without a restart.

The App is private: only the account that owns it can install it, and everyone else sees GitHub's 404 page. Create it under the organization that owns your repositories.

What the App can access

Permission	Access
Repository contents	Read and write
Pull requests	Read and write
Checks	Read
Metadata	Read

It subscribes to push, pull_request, release, and check_suite events. Webhooks arrive at /api/git/webhook, and every delivery must carry a valid X-Hub-Signature-256 signature.

Change repository access later

You can change repository access on GitHub at any time. When GitHub sends you back, Helpin verifies the installation belongs to your App and reconnects it. You must be an organization owner or admin in Helpin. An installation already connected to a different Helpin organization is refused.

Use an existing App instead

To manage the App yourself, for example through infrastructure-as-code, set these in .env and restart:

GITHUB_APP_ID=123456
GITHUB_APP_SLUG=acme-helpin
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."   # PEM, escaped PEM, or base64
GITHUB_APP_WEBHOOK_SECRET=your-webhook-secret
# Optional
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=

When GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY are set, they take precedence and the Create button is hidden. Without a webhook secret, all GitHub webhooks are rejected.

Keys and recovery

The App's private key, client secret, and webhook secret are encrypted with GIT_OAUTH_ENCRYPTION_KEY. If that key is lost, the stored App can't be read. Back it up with your data.

Helpin won't replace an App that already exists. To start over, delete the App on GitHub, and remove its row from the github_app_credentials table.