GitHub & GitLab Apps

To read and commit to your repositories and allow users to sign in, a self-hosted Sitepins deployment connects to your Git providers through three separate applications:

1. GitHub App Setup (Repository Access)

Sitepins commits to repositories on behalf of your users using an official GitHub App .

Step 1: Create the App

1. Navigate to GitHub Settings → Developer settings → GitHub Apps → New GitHub App.
2. GitHub App name: Choose a unique name (e.g. acme-cms-sitepins). Note this down; it must match NEXT_PUBLIC_GITHUB_APP_NAME exactly.
3. Homepage URL: Your public web app URL (e.g. https://cms.example.com or http://localhost:3000).
4. Callback URL: <APP_URL>/github-installed (e.g. https://cms.example.com/github-installed).
5. Setup URL (optional): <APP_URL>/github-installed with “Redirect on update” checked.
6. Request user authorization (OAuth) during installation: MUST BE CHECKED.
   [!WARNING]

If “Request user authorization during installation” is unchecked, GitHub will not return the authorization code upon installation, causing the connection flow to fail silently.

7. Webhook: Uncheck Active (Sitepins does not require incoming webhooks).
8. Where can this GitHub App be installed?:
   • Select “Any account” if team members or clients will install it on their personal or external organization repositories.
   • Select “Only on this account” if you are strictly hosting internally for a single organization.

Step 2: Set Repository Permissions

Under the Repository permissions section, grant the following scopes:

Step 3: Generate Keys & Configure app/.env

1. On the app settings page, locate the numeric App ID and the alphanumeric Client ID.
2. Under Client secrets, click Generate a new client secret and copy the resulting string immediately.
3. Under Private keys, click Generate a private key. A .pem file will be downloaded to your computer.
4. Open the downloaded .pem file in a text editor and copy its entire contents (including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----).
5. Populate app/.env:

GITHUB_APP_ID="123456"
GITHUB_APP_CLIENT_ID="Iv1.abc123def456"
GITHUB_APP_CLIENT_SECRET="ghs_secret123456789"
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA...
...
-----END RSA PRIVATE KEY-----"
NEXT_PUBLIC_GITHUB_APP_NAME="acme-cms-sitepins"

Step 4: Install the App

Visit your app’s public installation page at https://github.com/apps/<NEXT_PUBLIC_GITHUB_APP_NAME> and click Install on your user account or target organization.

2. GitHub OAuth App Setup (User Login)

This enables the “Continue with GitHub” button on the sign-in and registration pages.

1. Navigate to GitHub Developer Settings → OAuth Apps  → New OAuth App.
2. Application name: A descriptive name (e.g. Sitepins Login).
3. Homepage URL: Your API or Web URL (e.g. https://cms.example.com).
4. Authorization callback URL: Must point to the Express API’s callback route:

   <BASE_URL>/api/v1/auth/callback/github

   Example: https://api.example.com/api/v1/auth/callback/github (or http://localhost:4000/api/v1/auth/callback/github for local development).
5. Copy the Client ID and generate a Client Secret.
6. Populate api/.env:

GITHUB_CLIENT_ID="Ov23li..."
GITHUB_CLIENT_SECRET="987654..."

3. GitLab OAuth App Setup

GitLab uses a single OAuth application to handle both user sign-in and repository operations.

1. In GitLab, navigate to your user profile Preferences → Applications (or organization Group Settings → Applications to scope to a group).
2. Name: e.g. Sitepins GitLab.
3. Redirect URI: Exactly <APP_URL>/gitlab-installed (e.g. https://cms.example.com/gitlab-installed or http://localhost:3000/gitlab-installed).
4. Confidential: Ensure this is checked.
5. Scopes: Select exactly two scopes:
   • api (Read/write access to repository files and merge requests)
   • read_user (Read user profile and email)
6. Click Save application and copy the Application ID and Secret.
7. Populate app/.env:

NEXT_PUBLIC_GITLAB_APP_NAME="GitLab"
NEXT_PUBLIC_GITLAB_CLIENT_ID="gloas-12345..."
GITLAB_CLIENT_SECRET="gloas-secret-67890..."

Troubleshooting Git Provider Connections