GuidesOnly show guides for your app
GuidesGuidesPrivate repos need the OAuth account connection, not a URL — URL linking is public-only. Here's what connecting GitHub, GitLab, or Bitbucket actually grants, how organization repos work, and what to do when a token expires.
The Git quickstart mentions two ways to link a repo: connect an account, or paste a public URL. For a private repository only one of those works — you have to connect the account. This guide explains why, exactly what the connection grants, how organization repos fit in, and how to handle a token that's expired.
| At a glance | |
|---|---|
| You need | a private repo on GitHub, GitLab, or Bitbucket |
| Plan | any |
| Time | ten minutes |
Pasting a repository URL works by fetching a repo that anyone can fetch — there are no credentials involved. A private repo, by definition, refuses that anonymous fetch. So URL linking simply can't reach a private repo; there's nothing to authenticate with.
To deploy a private repo, you connect your account over OAuth instead. That hands Falix a token scoped to your access, which is what lets it clone a repo the public can't see.
🎯 Good to know: This is also the connection that unlocks auto-deploy on push (webhooks). URL-linked public repos only get manual or scheduled pulls; the OAuth connection is what enables push-to-deploy. See Auto-deploy on push.
When you connect on the Git page, the provider shows you an authorization screen listing what Falix is asking for. The scopes requested per provider:
| Provider | Scopes requested | What that covers |
|---|---|---|
| GitHub | repo, read:user |
Read (and webhook) access to your repositories — public and private — plus your basic profile |
| GitLab | api, read_user, read_repository |
Repository read access and the API needed to deploy, plus your profile |
| Bitbucket | (set on the connected app) | Repository read + webhooks, as configured on the OAuth app |
GitHub's repo scope is the broad one — it's how a single connection can reach every repo you have access to, rather than making you re-authorize per project. You grant it once on the authorization screen; you can review or revoke it later from your GitHub settings under connected applications (and the equivalent pages on GitLab and Bitbucket).
A repo owned by an organization (not your personal account) has an extra gate: the org has to allow it.
The rule of thumb: you can deploy an org repo as long as you have access to it and the org permits the connection. Falix only ever sees what your own account can see — it inherits your access, it doesn't expand it.
OAuth tokens don't last forever, and Falix handles the common case for you:
⚠️ Heads up: If deploys suddenly fail with an authentication or permission error on a repo that used to work, suspect the connection before the code. Reconnect the account on the Git page and try again.
.env; see Keep secrets out of Git.