GitHub Connection

Venelx clones your repo, reads commit metadata, and receives webhooks through a GitHub App OAuth flow. This page explains how connecting works, why you rarely need to think about tokens, and what to do when GitHub starts rejecting them.

How connecting works

1. In the dashboard, go to Account → GitHub and click Connect GitHub.
2. You're redirected to GitHub, where you authorize the Venelx GitHub App and choose which repositories it can access (all repos, or a selected set).
3. GitHub redirects back to the API callback (https://api.venelx.com/api/github/callback), and Venelx stores the resulting user token plus a refresh token against your account.

From then on, builds and project imports use this connected identity automatically.

Token lifecycle — renewed silently

GitHub App user tokens expire after 8 hours. You don't have to re-authorize:

• Venelx stores the OAuth refresh token returned at connect time.
• Before an expiring token is used — and on a background sweeper that runs every 30 minutes (GITHUB_TOKEN_SWEEP_INTERVAL_MINUTES) — the API exchanges the refresh token for a fresh user token and saves it.
• This is invisible to you: builds keep cloning, webhooks keep flowing.

reconnect_required

If the stored refresh token itself stops working — you revoked the app on GitHub, uninstalled it from the org, changed credentials, or GitHub invalidated the grant — the API can no longer renew the token. The account flips to reconnect_required:

• The dashboard shows a one-click Reconnect CTA (banner / Account → GitHub).
• Clicking it replays the same OAuth flow and stores a fresh token + refresh token.
• Until you reconnect, operations that need GitHub (new builds, repo listing) fail with a token error.

Credential priority

When Venelx needs a GitHub credential (cloning on a worker, API-side repo calls), it resolves one in this order:

1. Project env — GITHUB_TOKEN (or GH_TOKEN / GITHUB_PAT / GIT_TOKEN) set on the project.
2. Connected account — the OAuth user token from your connected GitHub account (auto-refreshed as above).
3. Team secret — a token stored as a team-level secret.
4. Server env — GITHUB_TOKEN on the API/worker process (last resort).

GITHUB_USER (any level) sets the git username paired with those tokens — default x-access-token.

The first match wins, so a project-level PAT overrides the connected account for that project only, and the connected account overrides team/server fallbacks everywhere else. The MCP github_access tool reports which source a project resolves to and whether it works.

Troubleshooting — "GitHub token rejected (HTTP 401)"

A 401 from GitHub means the credential Venelx presented was refused. Common causes and fixes:

Quick diagnosis without the dashboard:

• MCP: the github_access tool returns githubAccess {ok, reason, message} plus the auth source label for a project.
• trigger_build surfaces skipReason: github_token_invalid when a build can't start because of GitHub auth.

GITHUB_* environment variables

Server-side variables (on the API; OAuth client fields also on a local worker that runs OAuth-dependent steps):