Installing the GitHub App

The Velumi GitHub App gives Velumi read access to your repositories at build time. You install it once per GitHub account (personal or organization) and choose which repos it can see.

Where to start

From the Velumi dashboard, go to your organization's Integrations page:

Organization → Integrations → Install GitHub App

A popup opens on GitHub. Choose:

Where to install — your personal GitHub account, or a GitHub organization you administer
Repository access — all current and future repos, or only specific ones

After completing the flow on GitHub, the popup closes and your installation appears in Velumi.

Personal vs organization install

Personal account — grants Velumi access to repos owned by your GitHub user
GitHub organization — grants Velumi access to repos owned by a GitHub organization; requires you to be an owner of that GitHub organization

You can install on multiple accounts — for example, your personal account and your company's GitHub organization. Each installation is listed separately in the Velumi dashboard.

All members of your Velumi organization can deploy from repositories granted through a shared installation. Access is organization-wide, not limited to the person who installed the App.

All repos vs select repos

All repositories — Velumi sees all current and future repos automatically. Easiest option for most teams.
Only select repositories — Velumi only sees the repos you explicitly grant. You need to return to GitHub and grant access whenever you want to deploy a new repo.

Either way, Velumi only ever reads your code at build time. It cannot push, create branches, open issues, or modify your repositories in any way.

Private npm packages from GitHub

If your project depends on private npm packages hosted on GitHub (via GitHub Packages or a private registry backed by GitHub), Velumi needs a GitHub App installation for every GitHub organization that owns those packages — not just the org that owns the source repo.

During a deploy, Velumi mints a fresh access token for each installation on your Velumi org and makes them available to the build so npm install / pnpm install can authenticate against private packages across multiple orgs.

Example: Your project source lives in acme-corp/website, but package.json references @design-system/tokens from a private package owned by acme-design. Install the Velumi GitHub App on both acme-corp and acme-design.

Installing on additional orgs is done the same way — Organization → Integrations → Add Another Installation.

After installing

Back in Velumi, the Integrations page lists your installations. From there you can:

Manage on GitHub — change scope, add or remove repos
Remove — disconnect the installation from Velumi