GitHub (GitHub App / OAuth App)
Easy: register a GitHub App in Developer settings in about 15 minutes, no review for any user to install it. The real decision is GitHub App (fine-grained, per-repository permissions, 1-hour installation tokens, recommended by GitHub) versus OAuth App (broad `repo` scope, blocked by default in new organizations until an owner approves). The main friction is organizational: only org owners (or repo admins, for their repos) can install a GitHub App, so members must request it.
Review: none; the GitHub Marketplace listing is optional and has its own requirements (privacy policy, support link; paid plans need a verified-publisher org and 100+ installations)
Timing: same day (no review); org installs wait on each org owner's approval.
Before you start
- for buildA GitHub account (personal, or an organization you own) to own the app. Prefer an organization so the app is not tied to one person and so paid Marketplace plans stay possible later.sourcedg1g8
- for buildHomepage URL✓ Iskaria has itsourcedg1
- for buildCallback URL for user authorization (https://app.iskaria.com/api/oauth/github/callback from the profile's redirectUris pattern)✓ Iskaria has itsourcedg1
- for buildA public HTTPS webhook endpoint and a webhook secret, if the agent should react to issue/PR events. MISSING from the profile: no webhook URL is defined.sourcedg1
- for launchPrivacy policy and support link (only for a Marketplace listing)✓ Iskaria has itsourcedg9
- for launchApp logo (optional for a GitHub App; useful for the install screen and Marketplace). MISSING: the profile has no exported square PNG.✓ Iskaria has itinferred
No separate test mode. Set 'Where can this GitHub App be installed?' to 'Only on this account' while testing, then switch to 'Any account' to let other users and orgs install it.
Who does what
- Fill every registration field from the profile (name, description, homepage, callback URL, webhook URL, permissions, install target)
- Generate the webhook secret and write the env-var wiring
- Implement JWT signing, installation-token minting, user-token refresh and webhook signature verification
- Run the test flow (issue, branch, PR) on a test repo once the app is installed
- Log in to GitHub and open the New GitHub App form (2FA, owner of the org)
- Click Create GitHub App, then generate and download the private key and client secret
- Install the app on your account/org and pick repositories
- Get org owners to install or approve the app in their organizations
- Accept the Marketplace Developer Agreement if you choose to list
Steps
For an agent that opens issues and PRs on users' repos, register a GitHub App. It gets fine-grained permissions, the installer picks which repositories it can touch, installation tokens expire after 1 hour, and it can act as a bot (e.g. iskaria[bot]) or on behalf of a user via user-to-server tokens. An OAuth App only has broad scopes such as `repo` (all public and private repos of the user) and is blocked by default in new organizations. Pick OAuth App only if you need to act strictly as the user across everything they can access.
Profile picture > Settings (for an org: Your organizations > the org > Settings) > Developer settings > GitHub Apps > New GitHub App. Requires being logged in, so a human starts here; an agent can fill the form once it is open.
https://github.com/settings/apps/newEnter the name (max 34 characters, unique across GitHub), description, homepage and callback URL. Keep 'Expire user authorization tokens' selected (8-hour user tokens with refresh tokens). Select 'Request user authorization (OAuth) during installation' so install and sign-in happen in one flow. Leave Device Flow off unless a CLI needs it.
GitHub App name IskariaMax 34 characters, unique across GitHub; 'Iskaria' may be taken, fall back to e.g. 'Iskaria Agent'. Description Iskaria is a multi-clinic operations console with an AI assistant. Clinic staff connect their business accounts so the assistant can answer patient messages, track leads and report on marketing performance.Shown to users when they install the app; tailor to useCases.github (opens issues/PRs from voice-note tasks). Homepage URL https://iskaria.com/ Callback URL ["https://app.iskaria.com/api/oauth/{provider}/callback","http://localhost:3000/api/oauth/{provider}/callback"]https://app.iskaria.com/api/oauth/github/callback; add the localhost one for development. Multiple callback URLs are allowed. Expire user authorization tokens Leave checked (default). Request user authorization (OAuth) during installation Check it so a user-to-server token is issued at install. Enable Device Flow Leave unchecked for a web console. Setup URL: where GitHub sends the user after installing (it receives installation_id). If 'Request user authorization during installation' is checked, GitHub uses the Callback URL instead and the Setup URL is not available. Optionally check 'Redirect on update'.
Setup URL Not in the profile; e.g. https://app.iskaria.com/settings/integrations/github. Skip if user authorization during installation is on. Redirect on update Webhook Active is on by default. Enter the public HTTPS endpoint and a random secret (generate it, store server-side, verify X-Hub-Signature-256). Deselect Active if the agent only acts on demand and never listens for events. Then pick events under 'Subscribe to events' (e.g. Issues, Issue comment, Pull request).
Webhook Active Uncheck if no events are needed. Webhook URL MISSING from profile; e.g. https://app.iskaria.com/api/webhooks/github. Webhook secret Generate; never commit it. Subscribe to events Repository permissions: Issues Read & write, Pull requests Read & write, Contents Read & write (to push the branch a PR is opened from); Metadata Read-only is added automatically. No organization or account permissions. Request the minimum: adding permissions later forces every installation owner to approve them, and installations that decline keep the old set.
Permissions Each permission: Read-only, Read & write, or No access. See scopes. 'Where can this GitHub App be installed?': 'Only on this account' while testing, 'Any account' to let clinics/users install it. Click Create GitHub App.
Where can this GitHub App be installed? Only on this account / Any account. On the app page note the App ID and Client ID, generate a client secret and a private key (.pem). Store them in server env (Vercel), never in the repo or browser. The server signs a JWT with the private key to mint 1-hour installation tokens.
Install the app on your account or org, choose 'Only select repositories', and run the flow: mint an installation token, create an issue, push a branch and open a PR. Watch rate-limit headers.
Switch to 'Any account'. Share the public install link. In organizations, only owners can install on the whole org; repo admins can install on repos they administer if the app requests no organization permissions and not Repository administration; other members can only request, which emails the owner. Optional: list on GitHub Marketplace (privacy policy, support link; paid plans need a verified-publisher org and 100+ installations).
Scopes an agent typically needs
| Scope | Used for | Review tier | Evidence |
|---|---|---|---|
| Issues: Read & write | Open issues from voice-note tasks and comment on them | basic | sourcedg1 |
| Pull requests: Read & write | Open and update PRs | basic | sourcedg1 |
| Contents: Read & write | Create branches and commits that the PR is opened from The broadest of the three; drop it if the agent only files issues. | basic | inferredg10 |
| Metadata: Read-only | List repositories and basic repo info Added automatically when any repository permission is selected. | basic | inferred |
| repo (OAuth App alternative) | Only if you choose an OAuth App: needed to open issues/PRs on private repos Grants full access to all of the user's public and private repositories; cannot be narrowed per repo. `public_repo` if only public repos. | basic | sourcedg11g2 |
What can slow you down or block approval
Only organization owners can install a GitHub App on an org (repo admins only on their repos, and only if the app requests no organization permissions and not the 'Repository administration' permission; owners can also switch off installs by repo admins). A member's attempt sends a request email to the owner and waits.
Workaround: Request only repository permissions (and not Repository administration) so repo admins can install; tell users up front that an org owner may need to approve.
OAuth app access restrictions are enabled by default for new orgs: members cannot authorize an OAuth App to org resources until an owner approves it. GitHub Apps are not subject to these OAuth app policies.
Workaround: Use a GitHub App.
Installation tokens get 5,000 requests/hour, +50 per repo above 20, capped at 12,500 (15,000 on Enterprise Cloud). Separately, secondary limits allow at most 80 content-generating requests per minute and 500 per hour, and 900 REST points per minute (writes cost 5 points). An agent opening many issues/comments in bursts hits these first.
Workaround: Queue writes, respect Retry-After and x-ratelimit headers, batch comments.
When you add permissions, each installation owner is prompted; installations that do not approve keep the old permissions, so features silently fail for them.
Workaround: Decide the permission set before launch; check granted permissions at runtime.
The app name must be unique across GitHub and at most 34 characters; a short brand name may already be taken.
What we checked
| Claim | How | Result |
|---|---|---|
| GitHub App registration form field names (GitHub App name, Description, Homepage URL, Callback URL, Expire user authorization tokens, Request user authorization (OAuth) during installation, Enable Device Flow, Setup URL, Webhook Active/URL/secret, Permissions, Where can this GitHub App be installed?) Also lists 'Redirect on update' and 'Subscribe to events', added to the steps. | Fetched the live 'Registering a GitHub App' doc | confirmed |
| OAuth Apps allow only one callback URL and issue non-expiring tokens The form now accepts up to 10 callback URLs and has an 'Expire user access tokens' checkbox enabled by default. | Fetched 'Creating an OAuth app' | corrected |
| Installing a GitHub App in an org needs org owner approval Owners install directly; repo admins can install on their own repos when the app requests no org permissions; only other members need to request. OAuth app access restrictions (on by default in new orgs) do not apply to GitHub Apps. | Fetched 'Installing a GitHub App from a third party' and 'Requesting a GitHub App from your organization owner' | corrected |
| Installation token rate limit 5,000/h scaling to 12,500 (15,000 on Enterprise Cloud) | Fetched REST rate-limit doc; the GitHub Apps rate-limit page gives no numbers and links there | confirmed |
| No review is needed to make a GitHub App public No doc says so explicitly; none describes a review outside the optional Marketplace. | Read the registration and Marketplace docs for any approval step | unverified |
| Only org owners install on an org; repo admins only when no organization permissions are requested Repo admins are also blocked if the app requests the 'Repository administration' permission, and owners can disable repo-admin installs. Blocker and launch step updated. | Independent check: fetched docs.github.com 'Installing a GitHub App from a third party' on 2026-10-30 | corrected |
| Installation tokens: 5,000 req/h, +50 per repo above 20, cap 12,500 (15,000 Enterprise Cloud); secondary 80 content-creating/min, 500/h, 900 REST points/min All figures match; GitHub notes secondary limits can change without notice. | Independent check: fetched docs.github.com 'Rate limits for the REST API' on 2026-10-30 | confirmed |
| OAuth endpoint behaviour (discovery metadata, PKCE, dynamic registration, unknown-client handling) github.com publishes no OAuth/OIDC discovery document (both 404), so no advertised PKCE methods and no registration_endpoint. The authorize endpoint with an unknown client_id answers 302 to /login rather than an error page. | Endpoint probe: node scripts/probe.ts on 2026-10-30 | confirmed |
- Exact repository-permission names (Issues, Pull requests, Contents, Metadata) and the auto-added Metadata permission were not re-checked against GitHub's permission reference this session.
- Whether the Setup URL field is disabled when 'Request user authorization (OAuth) during installation' is checked is from prior knowledge of the form.
- GitHub documents no Marketplace review timeline.
- Logo upload location (app settings after creation) was not checked.
Sources
- g1Registering a GitHub App · official-docs · accessed 2026-10-30
“The name cannot be longer than 34 characters.”
- g2Differences between GitHub Apps and OAuth apps · official-docs · accessed 2026-10-30
“In general, GitHub Apps are preferred over OAuth apps.”
- g3
- g4About OAuth app access restrictions · official-docs · accessed 2026-10-30
“When you create a new organization, OAuth app access restrictions are enabled by default.”
- g5Installing a GitHub App from a third party · official-docs · accessed 2026-10-30
“Organization owners can install GitHub Apps on their organization.”
- g6Requesting a GitHub App from your organization owner · official-docs · accessed 2026-10-30
“Organization members can request installation of a GitHub App for their organization.”
- g7Rate limits for the REST API · official-docs · accessed 2026-10-30
“The rate limit cannot increase beyond 12,500 requests per hour.”
- g8About GitHub Marketplace for apps · official-docs · accessed 2026-10-30
“only apps owned by organizations can sell their app”
- g9Requirements for listing an app · provider-policy · accessed 2026-10-30
“GitHub Apps should have a minimum of 100 installations.”
- g10Choosing permissions for a GitHub App · official-docs · accessed 2026-10-30
“You should select the minimum permissions required for the app.”
- g11Scopes for OAuth apps · official-docs · accessed 2026-10-30
“Grants full access to public and private repositories”
- g12Installing a GitHub App from a third party · official-docs · accessed 2026-10-30
“Repository admins can install only if the app doesn't request organization permissions or the "Repository administration" permission.”
- g13Endpoint probe, 2026-10-30 · our-test · accessed 2026-10-30
“No .well-known/oauth-authorization-server or openid-configuration (404); unknown client_id redirects (302) to the github.com login page instead of an error”