Skip to main content

Connect GitHub repositories

This procedure is for a workspace administrator. The instance administrator must first configure the GitHub App.

Prerequisites​

  • Your Norn account has the administrator role in the workspace.
  • The GitHub panel under Workspace settings → Source control shows Connect GitHub.
  • Your GitHub account can install the app on the account or organization that owns the repositories. Organization policy might require an owner to approve the installation.

Install the app on GitHub​

  1. In Norn, open Workspace settings → Source control.
  2. Select Install it on repositories.
  3. On GitHub, choose the account or organization that owns the repositories.
  4. Choose Only select repositories, then select the repositories this workspace needs. Choose All repositories only when that broader access is intentional.
  5. Review the permissions and select Install. If GitHub shows Request, wait for an organization owner to approve and complete the installation.

Connect the installation to the workspace​

  1. Return to Workspace settings → Source control and select Connect GitHub.
  2. Authorize the app on GitHub.
  3. If Norn shows more than one installation, select Use this one beside the required account or organization.
  4. Confirm that the new GitHub connection appears under Connections with a Working status.

Installing and authorizing are separate GitHub operations. Installation grants repository access; authorization lets Norn list the installations available to the signed-in GitHub user. See GitHub's installation documentation.

Norn screenshot placeholder showing the available GitHub App installations

Connect a repository​

  1. Under Connect a repository, choose the GitHub App connection.
  2. Choose a repository. Norn lists only repositories granted to the installation.
  3. Optionally set Label to watch for. GitHub issues with that label are imported and kept in sync; other GitHub issues remain on GitHub.
  4. Select Connect it.
  5. Open the connected repository and route repository paths to Norn teams.
  6. Open Platform identities and map Norn members to their GitHub logins. Norn does not infer identities from similar names or email addresses.

GitHub App deliveries use the app-level webhook. Do not create repository webhooks.

Change repository access​

Change the repository selection in the app's installation settings on GitHub. Newly granted repositories appear in Norn's repository selector after reload. Removed repositories stop being reachable, but their existing Norn records are not deleted.

Troubleshooting connections​

No installation appears​

  • Confirm this exact app is installed on the repository-owning account or organization.
  • Sign in to GitHub as someone who can access the installation.
  • Complete any organization-owner approval before selecting Connect GitHub again.
  • Restart the flow if more than 10 minutes passed; connection state expires and cannot be reused.

No repository appears​

Open the installation settings on GitHub and grant the repository to the app, then reload Source control. Repositories outside the installation are not visible to Norn.

The connection is not working​

  • Confirm the installation still exists and still grants the required repositories.
  • Open the connection in Norn and select Check it now.
  • Check API and worker logs for GitHub authentication or reachability failures.

Webhook deliveries fail​

  • Confirm GitHub can reach the app webhook over HTTPS.
  • Preserve the request body and X-Hub-Signature-256 header through the reverse proxy.
  • Keep NORN_HTTP_MAX_REQUEST_BYTES at least as large as NORN_SOURCE_CONTROL_MAX_DELIVERY_BYTES.
  • Confirm the worker consumes the scm queue.
  • Do not replace the webhook secret in GitHub; Norn rejects deliveries signed with another value.