GitHub apps

The portal uses two GitHub registrations:

Registration	Purpose	Token
OAuth App	Sign in with GitHub. The portal reads the user’s public profile only.	Used once at login, never stored.
GitHub App	Read, list and create repositories for projects.	Installation tokens that last one hour, made from the app private key.

In the steps below, APP_BASE_URL is the public URL of the portal without a trailing slash, for example https://factory.example.com or http://localhost:5173 for local development.

1. Register the OAuth App

1. Open GitHub → Settings → Developer settings → OAuth Apps → New OAuth App. To make the organization own it, use Organization settings → Developer settings → OAuth Apps instead.
2. Set these fields:
   • Application name: Software Factory
   • Homepage URL: APP_BASE_URL
   • Authorization callback URL: APP_BASE_URL/api/auth/callback
3. Click Register application, then Generate a new client secret.
4. Record the Client ID and the client secret.

An OAuth App has only one callback URL. Register a separate OAuth App for each environment, for example one for localhost and one for the deployed portal.

2. Register the GitHub App

1. Open Organization settings → Developer settings → GitHub Apps → New GitHub App.

2. Set these fields:

   • GitHub App name: Software Factory (or a name with your environment).
   • Homepage URL: APP_BASE_URL
   • Callback URL: leave empty. Clear Request user authorization (OAuth) during installation.
   • Setup URL: APP_BASE_URL/api/github/setup. Select Redirect on update.
   • Webhook: clear Active. The portal does not use webhooks yet.

3. Set Repository permissions:

   Permission	Access	Why
   Metadata	Read-only	Mandatory. List and read repositories.
   Contents	Read and write	Agents read and change code.
   Pull requests	Read and write	Agents open pull requests.
   Administration	Read and write	Create new repositories in an organization.

4. Set Organization permissions → Members: Read-only. The portal uses it to check that the person who connects an organization is a member of it.

5. Under Where can this GitHub App be installed?, select Any account when people connect more than one organization or personal account. Otherwise select Only on this account.

6. Click Create GitHub App.

7. Record the App ID from the app page and the slug from its public URL, https://github.com/apps/<slug>.

8. Under Private keys, click Generate a private key. GitHub downloads a .pem file.

The GitHub App can create repositories only in organizations. For a personal account, create the repository on GitHub, give the app access to it, then choose it in the portal.

3. Configure the portal

Put the values you recorded into the GitHub variables in Configuration:

Variable	Value
GITHUB_OAUTH_CLIENT_ID	OAuth App client ID
GITHUB_OAUTH_CLIENT_SECRET	OAuth App client secret
GITHUB_APP_ID	GitHub App ID
GITHUB_APP_SLUG	GitHub App slug
GITHUB_APP_PRIVATE_KEY	Contents of the .pem file

• Local development: put them in backend/.env, using the template.
• Amp orb: add them as project environment variables and secrets. .amp/services.yaml sets APP_BASE_URL to the orb’s portal URL, so register the OAuth App and GitHub App with that URL. The portal URL changes for each thread.

The backend stops at start when a required value is missing.

4. Check the setup

1. Open the portal and click Sign in with GitHub. GitHub asks you to authorize the OAuth App, then sends you back to the portal.
2. Click Connect GitHub. Install the GitHub App on an account and choose repositories. GitHub sends you back to the portal with GitHub is connected.
3. Click New project and choose a default repository.