A self-hosted install needs its own provider credentials. There are three separate things to create, and mixing them up is the most common setup mistake.

What	Where it’s configured	What it does
GitHub OAuth app	api/.env	Sign in with GitHub
GitHub App	app/.env	Read and write repositories
GitLab OAuth app	app/.env	Both sign-in and repository access for GitLab

Google sign-in is optional and configured on the API alongside the GitHub OAuth app.

GitHub App — Repository Access

Sitepins commits on your behalf, so repository access uses a GitHub App, not a plain OAuth app.

Create one at Settings → Developer settings → GitHub Apps → New GitHub App.

Settings

1. GitHub App name — anything unique, for example acme-sitepins. This exact name goes into NEXT_PUBLIC_GITHUB_APP_NAME; the install button links to github.com/apps/<name>/installations/select_target, so a typo here breaks the install flow with no error message.
2. Homepage URL — your app’s base URL, http://localhost:3000 for local development.
3. Callback URL — <APP_URL>/github-installed, and check “Request user authorization (OAuth) during installation”.
4. Setup URL — the same <APP_URL>/github-installed, with “Redirect on update” checked so re-installs and permission changes land on the same page.
5. Webhook — uncheck Active. Sitepins doesn’t listen for webhooks, so leaving it on just means GitHub retries deliveries against nothing.
6. Where can this GitHub App be installed? — “Any account” if your users will install it on their own organizations, “Only on this account” if you’re hosting for a single organization.

Repository permissions

Permission	Access
Administration	Read and write
Code	Read and write
Commit statuses	Read-only
Deployments	Read-only
Metadata	Read-only (mandatory)
Pull requests	Read and write

Anything narrower and API calls start failing with 403s.

Credentials

After creating the app:

• Note the App ID and Client ID from the settings page
• Generate a new client secret and copy it immediately — it’s shown once
• Under Private keys, Generate a private key, which downloads a .pem file

Fill app/.env:

GITHUB_APP_ID="<App ID>"
GITHUB_APP_CLIENT_ID="<Client ID>"
GITHUB_APP_CLIENT_SECRET="<Client secret>"
GITHUB_APP_PRIVATE_KEY="<the full .pem contents, including the BEGIN/END lines>"
NEXT_PUBLIC_GITHUB_APP_NAME="<GitHub App name>"

Finally, install the app on your own account or organization from github.com/apps/<name>, so there’s at least one installation to authenticate against.

GitHub OAuth App — Sign-In

Separate from the App above, and configured on the API rather than the app.

Create one at github.com/settings/developers → OAuth Apps → New OAuth App.

• Authorization callback URL — <BASE_URL>/api/v1/auth/callback/github, where BASE_URL is your API’s URL

Fill api/.env:

GITHUB_CLIENT_ID="<Client ID>"
GITHUB_CLIENT_SECRET="<Client secret>"

Google sign-in (optional)

Create OAuth credentials in the Google Cloud Console with callback <BASE_URL>/api/v1/auth/callback/google, then:

GOOGLE_CLIENT_ID="<Client ID>"
GOOGLE_CLIENT_SECRET="<Client secret>"

GitLab OAuth App

GitLab uses a plain OAuth application for both sign-in and repository access.

Create one at gitlab.com → your avatar → Edit profile → Applications, or under Group → Settings → Applications to scope it to an organization.

1. Name — cosmetic, used for NEXT_PUBLIC_GITLAB_APP_NAME
2. Redirect URI — exactly <APP_URL>/gitlab-installed, for example http://localhost:3000/gitlab-installed
3. Confidential — check this. The secret is used server-side only.
4. Scopes — check exactly api and read_user, nothing else

GitLab shows the Application ID and Secret once. Fill app/.env:

NEXT_PUBLIC_GITLAB_APP_NAME="<name>"
NEXT_PUBLIC_GITLAB_CLIENT_ID="<Application ID>"
GITLAB_CLIENT_SECRET="<Secret>"

Troubleshooting

Sign-in with GitHub does nothing. “Request user authorization (OAuth) during installation” is unchecked on the GitHub App, or the OAuth app’s callback URL points at the app instead of the API.

No repositories appear after installing. The App was installed with “Only select repositories” and none were selected, or it was installed on a different account than the one you signed in with.

403 errors on commit. Repository permissions are narrower than the table above. Update them on GitHub and approve the permission change on each installation.

GitLab callback rejected. The redirect URI doesn’t match <APP_URL>/gitlab-installed exactly.