This is the one-time setup. You do these steps as an owner of the NeuroverseOS organization (only an org owner can create an org-owned app and list it on the Marketplace). Budget ~20 minutes for steps 1–4; Marketplace review (step 5) is on GitHub's side and can take days.
Throughout: the app is read-only and never writes to anyone's code. Keep that framing in the listing copy.
Go to: https://github.com/organizations/NeuroverseOS/settings/apps/new (Org → Settings → Developer settings → GitHub Apps → New GitHub App.)
Fill it in using the values from app-manifest.json:
| Field | Value |
|---|---|
| GitHub App name | Bevia (if taken, use Bevia Sensor — the name is global across GitHub) |
| Homepage URL | https://bevia.co |
| Callback URL | https://bevia.co/github/app/created (only needed if you later add "Sign in with GitHub"; fine to set now) |
| Setup URL (optional) | https://bevia.co/github/app/installed — where users land right after they install. Tick "Redirect on update." |
| Webhook → Active | UNCHECK it. Bevia is pull-not-push; the app receives no events. (With Active off, the Webhook URL field can be left blank.) |
| Permission | Access |
|---|---|
| Metadata | Read-only (mandatory, auto-selected) |
| Contents | Read-only |
| Pull requests | Read-only |
| Issues | Read-only |
Do not grant any write or admin permission. If GitHub shows a write option selected anywhere, set it back to No access.
Leave all event checkboxes unchecked — no webhook, no events.
Choose "Any account." This is required so other people/orgs can install it and so it's eligible for the Marketplace. (If you want to test privately first, pick "Only on this account," then switch to "Any account" before submitting to the Marketplace.)
Click Create GitHub App.
Faster alternative — create from the manifest. Instead of filling the form by hand, you can POST
app-manifest.jsonto GitHub's "create from manifest" endpoint. It's only worth it if you're recreating the app repeatedly; for a one-time setup, the form above is simpler. The manifest is kept in this repo as the source of truth for exactly what the app should be.
On the app's settings page right after creation, record:
- App ID (a number) — not secret, but needed.
- Client ID — not secret, but needed.
- Generate a private key → downloads a
.pemfile. This is a secret. Store it in a password manager / secret store. Never commit it to this repo (the.gitignorealready blocks*.pem). - Optionally generate a Client secret if you later add sign-in.
You'll hand the App ID + the .pem private key to the Bevia
backend when the App-based pull path is wired (see step 6). Until then,
just keep them safe.
Also upload a logo (the Bevia pawn) and set a background color — the Marketplace listing needs one.
On the app page → Install App (left sidebar) → choose NeuroverseOS → Only select repositories → pick the repos you want Bevia to read → Install.
That install creates an installation whose token lets Bevia read exactly those repos. You can add/remove repos or uninstall anytime from Org → Settings → GitHub Apps → Bevia → Configure.
This is the answer to "how do I connect it to my organization?" — it's this install step. Nothing about your code changes; you've handed Bevia a read-only, revocable key to the repos you chose.
Today Bevia's GitHub intake uses the personal OAuth connection. The
App gives the fine-grained, org-wide path. Wiring it is a backend
follow-up (see step 6). Once that ships, you'll paste the App ID and
upload the .pem in Bevia's Control Tower → Connections → GitHub, and
Bevia will mint short-lived installation tokens to pull from the repos
you selected. No further action from installers beyond step 3.
Prerequisites GitHub enforces before you can list:
- The app is public ("Any account" — step 1).
- Two-factor auth is enabled on the NeuroverseOS org and on your account.
- The org is set up as a publisher (GitHub walks you through the publisher agreement the first time).
Then:
- App page → Advanced / Marketplace → List in Marketplace (or go to https://github.com/marketplace/new and pick the Bevia app).
- Fill the listing: short + full description (lead with "a read-only continuity sensor — Bevia reads your repos, never writes"), the Bevia logo, category (Continuous integration or Utilities fit; pick the closest), and the supported languages/features.
- Pricing plan. Start with a Free plan — the app itself doesn't charge; Bevia's pricing lives in Bevia (Local $30 / Cloud $15 / Anywhere $5). A free Marketplace listing avoids GitHub's paid-app billing integration entirely and is the fastest path to approval.
- Submit for review. GitHub reviews public listings; expect back-and-forth and a few days. They mainly check the listing is accurate, the permissions match the description (our read-only scope makes this easy), and the install/uninstall flow works.
You can install and use the app on your own org (step 3) before the Marketplace listing is approved — listing only affects public discoverability. So this step never blocks you dogfooding it.
For Bevia to actually read via the App (rather than OAuth), the backend needs a small addition: exchange App ID + private key → a JWT → an installation access token, then reuse the existing GitHub read/backfill path with that token. This is a scoped change to the GitHub intake lane; it does not exist yet and is tracked separately. Nothing about creating, installing, or listing the app (steps 1–5) depends on it.
- ✅ Read commits, file contents, pull requests, issues on selected repos.
- ✅ Be installed per-org, per-repo, and uninstalled anytime.
- ❌ Write to code, comments, branches, or settings — no write permission exists.
- ❌ Receive webhooks or push events — webhook inactive, zero events.
- ❌ See repos you didn't select.