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

In the dashboard, go to Account → GitHub and click Connect GitHub.
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).
GitHub redirects back to Venelx, 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 job that runs every 30 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.

Reconnecting takes seconds and does not change project settings, env vars, or signing — it only re-establishes the OAuth grant.

Credential priority

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

Project env: a token set on the project. Accepted names are GITHUB_TOKEN, GH_TOKEN, GITHUB_PAT, GIT_TOKEN, GITHUB_ACCESS_TOKEN, or any key whose name matches GITHUB_*TOKEN.
Connected account: the OAuth user token from your connected GitHub account (auto-refreshed as above).
Team secret: a token stored as a team-level secret.
Platform default: a fallback token configured by the Venelx platform (last resort).

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

A project-level token is tried first, but Venelx first checks that it can actually reach the repository. If that check fails, it falls back to your connected account, so a stale project token does not block builds. The connected account then takes priority over team and platform fallbacks. 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:

Cause	Why it happens	Fix
Expired token	GitHub App user tokens live 8h; if renewal also failed, the account is stale	Use the Reconnect CTA in the dashboard (one click)
Revoked / uninstalled app	The OAuth grant was revoked on GitHub, or the app was uninstalled from the org	Reconnect, and re-install the app for the org/repos when prompted
SSO-unauthorized PAT	A personal access token used against a SAML-SSO org must be explicitly authorized for that org	On GitHub → the PAT → Configure SSO → authorize for your organization
Wrong scopes	Classic PATs need `repo` (contents read) for private repos; fine-grained PATs need Contents: read on the repo	Re-mint the PAT with the right scopes and update the project env / team secret
Token typo / rotation	The stored PAT no longer exists (rotated, deleted)	Set a fresh token in the project env or team secret

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.

Environment variables

Tokens you set on a project (see credential priority) are regular project environment variables. GITHUB_USER sets the git username paired with them (default x-access-token).

← Guides iOS Signing →