Connect GitHub source without storing repository tokens.

When to use it

Create a GitHub App when source context should work for private repos.

Logister can show the default stacktrace without any GitHub access. The GitHub App adds source-aware context after a project is explicitly connected to one or more repositories: code excerpts for stack frames, repository and branch links, CODEOWNERS hints, GitHub issue creation when write permission is granted, and deployment context when events or CI include commit metadata.

The App model avoids long-lived personal access tokens. GitHub issues short-lived installation tokens for the repositories where the App is installed, and Logister stores only App configuration, installation metadata, repository metadata, project-to-installation links, and your project-to-repository mappings.

Before you start

Make sure GitHub can reach your Logister instance.

• A public HTTPS URL for the Logister web process, set with LOGISTER_PUBLIC_URL.
• Project owner or project admin access to the Logister project where repositories will be mapped.
• GitHub owner or admin access to create a GitHub App and install it on the target organization or repositories.
• A secret store for the App ID, private key, webhook secret, and install URL or slug.
• The runtime paths your application reports in stack frames, such as /app or /workspace/service.

For local development, GitHub cannot post webhooks to plain localhost. Use a temporary HTTPS tunnel such as ngrok, Cloudflare Tunnel, or Smee, set LOGISTER_PUBLIC_URL to that URL, and update the GitHub App URLs while testing.

Create the app

Register the GitHub App with Logister's setup and webhook URLs.

1. In GitHub, open your user or organization settings, then go to Developer settings, GitHub Apps, and create a new GitHub App.
2. Name it for your instance, for example Logister Acme.
3. Set the Homepage URL to your Logister public URL, for example https://logister.example.com.
4. Set the Setup URL to the value shown in Project settings, Integrations, Source repositories, GitHub setup callback. It should look like https://logister.example.com/github/setup.
5. Keep webhooks active and set the Webhook URL to the value shown in the same Logister settings card. It should look like https://logister.example.com/github/webhooks.
6. Create a long random webhook secret. Put the same value in GitHub and LOGISTER_GITHUB_WEBHOOK_SECRET.
7. Generate a private key for the App. Store the PEM in your secret manager as LOGISTER_GITHUB_APP_PRIVATE_KEY.
8. Copy the App ID into LOGISTER_GITHUB_APP_ID.
9. Save the App, then copy the App slug or installation URL for Logister config.

GitHub's registration screen may also offer a callback URL for OAuth user flows. Logister uses the GitHub App setup URL and webhooks for repository installation, so the setup URL and webhook URL are the important fields.

Permissions

Start with read access and add issue writing only when the workflow needs it.

GitHub Apps start with no permissions. Give the App the smallest set that matches the features your teams will use.

Configure Logister

Put the GitHub App values in your deployment environment.

Set these on the Rails web process and the Sidekiq worker, then restart both. The web process handles setup callbacks and webhooks; workers and request paths may need the same configuration when they resolve source context.

LOGISTER_GITHUB_APP_ID=123456
LOGISTER_GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
LOGISTER_GITHUB_WEBHOOK_SECRET=replace-with-a-long-random-secret
LOGISTER_GITHUB_APP_SLUG=logister-acme
# Or set the install URL directly when you do not want Logister to derive it from the slug:
# LOGISTER_GITHUB_APP_INSTALL_URL=https://github.com/apps/logister-acme/installations/new

# Optional. Keep these defaults for github.com.
# LOGISTER_GITHUB_API_URL=https://api.github.com
# LOGISTER_GITHUB_WEB_URL=https://github.com
# LOGISTER_GITHUB_API_VERSION=2026-03-10
# LOGISTER_GITHUB_STATELESS_S2S_TOKEN=enabled

Install and sync

Use project settings to install or link the App and pull repository metadata.

1. Restart Logister after setting the environment variables.
2. Open Project settings, Integrations, then Source repositories.
3. Check the GitHub App access card. App ID, private key, webhook secret, and install URL should all show as configured.
4. Click Install GitHub App when the target GitHub account does not have an installation yet.
5. Choose all repositories or selected repositories in GitHub, then finish the installation.
6. After GitHub redirects back to Logister, confirm that the installation appears under Linked installations and repositories appear under Available repositories.
7. If the installation already exists, use Available installations, then click Link to project.
8. Use Sync repositories after repository access or App permissions change.

Installing or linking the App makes repositories available to the project. It does not connect a source repository mapping by itself. Click Connect next to each repository Logister should use for this project, then review its runtime path prefix, source root, and default branch under Connected repositories.

Project scope

Installations are reusable; repository mappings belong to one project.

A GitHub App installation is scoped to a GitHub account or organization. In Logister, a project owner or project admin links that installation to a specific project. Project admins can manage linked installations and repositories for projects they administer, even when another user originally installed the App.

One GitHub installation can be linked to multiple Logister projects. Each project still chooses its own connected repositories and path mappings, so a shared organization installation can support separate backend, worker, mobile, and front-end projects without sharing source lookup settings between them.

Map repositories

Tell Logister how stack frame paths line up with files in GitHub.

After repositories sync, connect one or more source repository mappings from Project settings, Integrations, Source repositories. Connected repositories appear separately from available repositories so each project can keep its own path mapping.

For best results, SDKs and direct HTTP clients should send repository, commit_sha, branch, release, and environment on error events. Exact commit metadata gives Logister a better source ref than guessing from the default branch.

Deployment context

Send deployments when CI knows what changed.

The GitHub App gives Logister access to repository files. Deployment records tell Logister what commit, PR, release tag, and environment were deployed. Together they make error pages more useful: source excerpts point to the right code, PR or release links can be shown from metadata, and Logister can explain when a group started after a deployment.

CI can POST a deployment envelope to /api/v1/deployments with repository, commit_sha, branch, release, environment, pull_request_number, release_tag, and GitHub URLs. The GitHub App does not need write permission for deployment indexing.

Troubleshooting

Most setup failures are URL, secret, or permission mismatches.

For GitHub's side of the setup, see GitHub's docs for registering a GitHub App, choosing permissions, and using webhooks with GitHub Apps.