Configure the instance GitHub App

This procedure is for the administrator operating a self-hosted Norn instance. Create one GitHub App for the instance and provide its credentials through deployment configuration. Workspace administrators can then install the app and connect repositories.

Prerequisites

• NORN_APP_BASE_URL is the final public HTTPS origin of the instance.
• GitHub can send HTTPS requests to the instance.
• NORN_SECURITY_ENCRYPTION_KEY is configured and backed up.
• You can create a GitHub App on the GitHub account or organization that owns the repositories.

The examples use https://norn.example.com. Replace it with NORN_APP_BASE_URL.

Create the app in GitHub

In GitHub, open the settings for the account that will own the app, then select Developer settings → GitHub Apps → New GitHub App. For an organization-owned app, open the organization's settings first.

Configure these values:

GitHub setting	Value
GitHub App name	A globally unique name for this Norn instance
Homepage URL	https://norn.example.com
Callback URL	https://norn.example.com/v1/source-control/github-app/connected
Webhook	Active
Webhook URL	https://norn.example.com/v1/source-control/github-app/deliveries
Webhook secret	The secret generated below
Request user authorization (OAuth) during installation	Disabled
Installation scope	Only on this account

Leave the setup URL and post-installation redirect empty. Norn starts installation and authorization from the workspace Source control page.

Generate the webhook secret locally:

openssl rand -hex 32

Copy the command's 64-character output into GitHub's Webhook secret field. Keep the same value for NORN_SOURCE_CONTROL_GITHUB_APP_WEBHOOK_SECRET; Norn uses it to verify that webhook requests were signed by GitHub. Store it in your secret manager after creating the app. Do not save it in a configuration file or source control.

Under Repository permissions, configure:

Permission	Access
Contents	Read-only
Metadata	Read-only
Pull requests	Read and write
Issues	Read and write
Deployments	Read-only

Under Organization permissions, configure:

Permission	Access
Members	Read-only

Subscribe the app to these events:

• push
• pull_request
• pull_request_review
• issues
• issue_comment
• release
• deployment_status

Create the app, generate a client secret, and generate a private key. GitHub downloads the private key as a PEM file. GitHub's registration procedure shows the current location of each setting.

Collect the configuration values

Set these environment variables from the GitHub App settings:

Norn setting	GitHub value
NORN_SOURCE_CONTROL_GITHUB_APP_ID	App ID
NORN_SOURCE_CONTROL_GITHUB_APP_SLUG	App URL slug, such as norn-example from github.com/apps/norn-example
NORN_SOURCE_CONTROL_GITHUB_APP_CLIENT_ID	Client ID
NORN_SOURCE_CONTROL_GITHUB_APP_CLIENT_SECRET	Generated client secret
NORN_SOURCE_CONTROL_GITHUB_APP_PRIVATE_KEY	Complete downloaded PEM private key
NORN_SOURCE_CONTROL_GITHUB_APP_WEBHOOK_SECRET	Exact value entered in GitHub's Webhook secret field

All six values are required. Norn considers the app present when the App ID, private key, and webhook secret are set, but connection authorization also requires the client ID and client secret, and the app slug is required to construct its installation URL.

Treat the client secret, private key, and webhook secret as credentials. Do not put their values in a configuration file, command-line argument, source control, logs, or screenshots. Supply them through the secret-management mechanism of your deployment method. Preserve the private key's PEM header, footer, and line breaks in the environment variable.

Restart Norn after setting or changing these environment variables.

Verify the instance configuration

1. Sign in to a workspace as a workspace administrator.
2. Open Workspace settings → Source control.
3. In the GitHub panel, confirm that Connect GitHub and Install it on repositories are available.

The GitHub App is instance-wide. This check reads the configured app and stores its credentials encrypted in PostgreSQL the first time it is needed.

Instance configuration is complete. Continue with Connect GitHub repositories.

GitHub Enterprise Server

Set the REST API base URL in addition to the six app environment variables:

NORN_SOURCE_CONTROL_GITHUB_ENDPOINT=https://github.corp.example/api/v3

If the GitHub host resolves to a private address, add only the required network prefix:

NORN_SOURCE_CONTROL_GITHUB_ENDPOINT=https://github.corp.example/api/v3
NORN_SOURCE_CONTROL_ALLOWED_DESTINATIONS=10.24.8.15/32

The configured-app path has no field for a private certificate authority. The GitHub Enterprise certificate must therefore be trusted by the operating system running Norn.

Troubleshooting

The GitHub panel does not show the installation actions

• Confirm all six environment variables are present in the Norn API process.
• Confirm the private key contains the complete PEM document, including its header and footer.
• Confirm NORN_SECURITY_ENCRYPTION_KEY is a Base64-encoded 32-byte key.
• Check the API logs while a workspace administrator opens Source control. Norn persists the configured app at that point.

Connect GitHub fails

• Confirm the client ID and client secret belong to this app.
• Confirm the callback URL exactly matches <NORN_APP_BASE_URL>/v1/source-control/github-app/connected.
• Confirm the app slug matches the final segment of its github.com/apps/... URL.

Webhook deliveries are rejected

• Confirm the GitHub webhook secret exactly matches NORN_SOURCE_CONTROL_GITHUB_APP_WEBHOOK_SECRET.
• Confirm the webhook URL is <NORN_APP_BASE_URL>/v1/source-control/github-app/deliveries.
• Preserve the request body and X-Hub-Signature-256 header through the reverse proxy.