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 |
Why URL linking is public-only
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.
What connecting grants
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).
Organization repositories
A repo owned by an organization (not your personal account) has an extra gate: the org has to allow it.
- During the OAuth screen, GitHub lists the organizations you belong to and lets you grant access to each. If you don't grant the org there, its repos won't appear when you go to pick one.
- Some orgs require an owner to approve third-party app access, or have SSO you must authorize the token against. If an org's repos are missing after connecting, that approval is usually why — ask an org owner, or authorize SSO for the token, then reconnect.
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.
Tokens expire — and reconnect
OAuth tokens don't last forever, and Falix handles the common case for you:
- Automatic refresh. Connections come with a refresh token, and when the access token is past its expiry Falix refreshes it in the background before a deploy. You won't notice — deploys keep working.
- When refresh fails. If you revoked the app, changed your password in a way that killed the tokens, or the refresh itself is rejected, the connection can't heal itself. Deploys start failing to authenticate, and the fix is to reconnect on the Git page — re-run the OAuth flow and you're back.
⚠️ 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.
Keeping the connection tidy
- One connection, many servers' worth of repos. The account link is yours; you pick which repo (and branch) each server deploys from.
- Disconnect when you're done. Revoking Falix's access from the provider's connected-apps settings cuts it off cleanly — do this if you stop using a provider, or as a security step if your account was ever exposed (see Protect your account).
- Secrets still never go in the repo. Private doesn't mean safe to commit tokens — a private repo can be forked, leaked, or made public by accident. Keep secrets in your server's
.env; see Keep secrets out of Git.
Troubleshooting
- My private repo doesn't show in the URL box — it never will; URL linking is public-only. Connect the account with OAuth instead.
- My org's repos are missing after connecting — you didn't grant the org on the OAuth screen, or the org needs owner approval / SSO authorization. Sort that out, then reconnect.
- Deploys started failing to authenticate — the token likely expired and couldn't refresh (revoked or password-reset). Reconnect the account on the Git page.
- I want to remove Falix's access entirely — revoke it from the provider's connected-applications settings; the deploy connection stops immediately.