Build an app

An app can work in two ways, and one app can do both:

• Sign people in. Someone approves your app and it acts as them, with the access they agreed to.
• Install as a bot. An owner installs your app on their account or organization and picks repositories. The app acts as its own bot, named {slug}-bot, on just those repositories.

Create an app in Your apps. Choose the most access it will ever need; people and owners can only grant up to that.

Sign people in

Send people to:

https://upstream.codes/login/oauth/authorize
  ?client_id=CLIENT_ID
  &redirect_uri=https://example.com/callback
  &scope=repo:read issues:write
  &state=RANDOM
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

After they approve, they come back to your callback with code and state. Exchange the code:

curl -X POST https://upstream.codes/login/oauth/access_token \
  -H "Accept: application/json" \
  -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET \
  -d code=CODE -d redirect_uri=https://example.com/callback \
  -d code_verifier=VERIFIER

You get an access token that lasts eight hours and a refresh token that rotates each time you use it. Using an old refresh token again revokes the whole chain. Apps without a server, such as CLIs and mobile apps, register as public clients, skip the secret and must use PKCE. Callback URLs must match exactly.

Access tokens work like personal access tokens: the same scopes, the REST API and Git over HTTPS. People can revoke an app at any time in Connected apps.

Install as a bot

Share your app's install link, https://upstream.codes/apps/{slug}/installations/new. Owners pick a namespace and repositories, then approve.

To act as the bot:

1. Generate a private key on your app's Keys and secrets tab. It downloads once.
2. Sign a JWT with it using RS256, with iss set to your app ID and exp at most ten minutes out.
3. Create an installation token:

curl -X POST -H "Authorization: Bearer $APP_JWT" \
  https://api.upstream.codes/api/v3/app/installations/$INSTALLATION_ID/access_tokens

Installation tokens last an hour and can only reach the installation's repositories with the permissions the owner approved. List installations with GET /app/installations. GitHub App libraries that let you set the API base URL work against https://api.upstream.codes/api/v3.

A bot can open and comment on Issues and Change Requests, review, report checks, publish releases, run Actions and push. It can't change repository settings, delete or transfer repositories, manage webhooks or assign people.

Changing permissions

Removing a permission takes effect right away. Adding one asks every installation's owner to approve it again; until they do, the installation keeps its current access.

Events for your app

Set a webhook URL and events on your app. It receives events from every repository it's installed on, signed with your webhook secret. Payloads include installation.id.