Troubleshooting GitHub

I can't find my repository in the source picker

Three things to check:

1. Is the GitHub App installed on the right account? A repo owned by a GitHub organization needs the App installed on that organization, not just your personal account. See Installing the GitHub App.
2. Does the installation have access to this repo? If you chose "Only select repositories" during install, the repo isn't included automatically. See Managing repository access.
3. Is the installation suspended? Go to Organization → Integrations. A suspended installation shows a warning badge.

Permission denied during build

Velumi can see the repo in the source picker but fails to clone it when a deployment runs. Usually one of:

• The installation was removed or suspended on GitHub after the project was set up
• The repo was transferred to a different GitHub account that hasn't installed the Velumi App
• The repo was made private and the installation no longer has access

Reinstall the Velumi GitHub App on the account that currently owns the repo, then trigger a new deployment.

Push to GitHub didn't trigger a deploy

If you have auto-deploy enabled but a push didn't start a deployment, check:

1. Is auto-deploy toggled on? Go to the environment's Source tab and confirm the Auto-deploy on push toggle is enabled.
2. Did you push to the right branch? Only pushes to the branch the environment tracks trigger a deploy. Check which branch is shown in the helper text on the Source tab.
3. Was an operation already in progress? If a deployment or other operation was running when the push arrived, the new push is queued and will deploy automatically once the current operation finishes. If no deployment starts after the queue clears, check for errors in the Deployments tab.
4. Is the source a GitHub repo? Auto-deploy is not available for archive (upload) sources.
5. Is the GitHub App installed? A suspended or removed installation won't receive push events. Check Organization → Integrations.

Private npm packages fail to install during build

If your build fails with an authentication error when installing private npm packages (e.g. 401 Unauthorized or Not found for a scoped package), the Velumi GitHub App is likely not installed on the GitHub org that owns those packages.

Velumi mints tokens for every GitHub App installation on your Velumi org at deploy time. If the package org is missing, the build runner has no credential for it.

Fix: install the Velumi GitHub App on the org that hosts the private packages — Organization → Integrations → Add Another Installation. See Private npm packages from GitHub.

I uninstalled the GitHub App by mistake

No data is lost. Reinstall the Velumi GitHub App on the same GitHub account, grant access to the same repos, and your existing projects resume working on the next deployment.