GitHub connection & repos

Most GitHub problems fall into one of four buckets: Alaf Server can't read your repos, a private repo won't import, a public repo that should need no login keeps asking you to connect, or pushes aren't triggering deployments. This page walks each one from the exact message you'll see to the fix.

Alaf Server can reach GitHub three ways — the Alaf Server GitHub App, an OAuth account, or the local gh CLI — and it manages the push webhooks that power auto-deploy. If you haven't connected yet, start with Deploy from GitHub; the connection card itself lives in Settings → General.

Alaf Server can't read your repositories

What it means (plain words): Alaf Server has no usable credential for your account. Either you were never connected, or a token that used to work has expired or been revoked (you signed out of gh, rotated a personal access token, or removed the App). Alaf Server isn't broken — it just has nothing to authenticate with.

How to fix:

1. Go to Settings → General and look at the GitHub card. If it doesn't show your login, press Connect GitHub and approve the window that pops up.
2. If it does show a login but repos still won't load, press Disconnect, then Connect GitHub again to mint a fresh token.
3. On a self-hosted instance using the CLI fallback, run gh auth login in the terminal on the machine running Alaf Server, then reload the page.

A private repo won't import

What it means: GitHub only exposes a private repo to a credential that has explicit access to it. Alaf Server can see it only if the GitHub App is installed on that owner and includes that repo, or you've given it a personal access token with the right scope. A public-repo-only token, or an App install that skipped the repo, can't see it.

How to fix:

1. Install / re-scope the App. From the repo picker or Settings → General → Install GitHub App, open the GitHub install screen. When GitHub asks which repositories to grant, choose All repositories or make sure the specific private repo is ticked. A common cause is an install that granted only some repos.
2. Or add a personal access token. In the project's Source tab, paste a token into the Clone Token Override card (or set a global one in Settings → Tokens → GitHub clone credentials). The token must include the repo scope — public_repo alone only reaches public repos.
3. Reload the picker; the repo should now appear.

A public repo keeps asking me to connect

What it means: A public github.com repo can be read and deployed with zero credentials — Alaf Server probes it anonymously first. That probe fails closed: if the repo doesn't come back as clearly public, Alaf Server falls back to asking for a credential. The usual reasons are that the repo isn't actually public, the owner/repo is mistyped, or it isn't on github.com.

How to fix:

1. Open the repo in a private/incognito browser window (logged out). If you can't see it, it's private — use the private-repo fix above.
2. Double-check the owner/repo spelling. Both https://github.com/owner/repo and git@github.com:owner/repo.git forms are understood, but only github.com — GitLab and GitHub Enterprise hosts always need a credential.
3. If you just made it public, wait a minute and retry. Alaf Server caches the "public" verdict for about ten minutes, and a transient network error during the probe makes it ask for a credential that one time.

Auto-deploy isn't triggering (webhooks not firing)

What it means: Auto-deploy is a webhook — GitHub sends Alaf Server a message the instant you push. If the message never arrives, is rejected, or arrives for a branch/project that isn't set to auto-deploy, nothing happens. Work through the checks below in order.

How to fix:

1. Turn auto-deploy on. Open the project's Source tab. If the Auto Deploy card says Disabled ("Deployments must be started manually"), toggle it on. This is also what registers the webhook on the repo.
2. Check the webhook is reachable. If the Source tab shows the "Enable auto-deploy" banner — "Auto-deploy needs a direct webhook endpoint. Expose this Alaf Server API on a public URL or configure a verified webhook domain for direct delivery." — then your instance is on localhost or a private network and GitHub literally can't reach it. Put Alaf Server behind a public URL, or pick a verified custom domain for direct delivery.
3. Push the branch you actually deploy. Alaf Server only redeploys when the pushed branch matches the project's deploy branch. A push to any other branch is ignored (the logs read "No local auto-deploy projects matched"). Confirm the branch in the Source tab.
4. Fix a rejected signature. Red 401 deliveries with "Invalid signature", "Missing x-hub-signature-256 header", or "No webhook secret configured — signature cannot be verified" mean the hook's signing secret doesn't match. Toggle Auto Deploy off and on to re-register the webhook — that mints a fresh per-project secret on both sides.

Still stuck?