Custom GitHub App Setup

Create Your Own GitHub App for SpikePrimeGit

📖 Overview

⚠️ Advanced Setup

This guide is for users who want to create their own GitHub App instead of using the official SpikePrimeGit app from the GitHub Marketplace.

Most users should use the official app. Only follow this guide if:

  • The SpikePrimeGit Marketplace app is not yet available
  • You want to use a custom app for organizational/security reasons
  • You're comfortable with GitHub App configuration

What You'll Accomplish

By the end of this guide, you will have:

  • Created your own GitHub App
  • Configured it with the correct permissions
  • Connected SpikePrimeGit extension to use your custom app
  • Successfully synced a project to GitHub

Time Required: 20-30 minutes

🤔 Why Create a Custom GitHub App?

When to Use a Custom App

✅ Good Reasons:

  • Marketplace App Not Available: The official SpikePrimeGit app hasn't been approved yet
  • Organizational Policy: Your organization requires apps to be managed internally
  • Custom Branding: You want the app to appear under your organization's name
  • Testing/Development: You're developing custom features or testing modifications

❌ Not Necessary If:

  • The official SpikePrimeGit app is available on GitHub Marketplace
  • You're a student or individual user just getting started
  • You want the simplest setup possible
💡 Recommendation: If you're new to GitHub Apps, try the official SpikePrimeGit app first. You can always switch to a custom app later if needed.

📋 Prerequisites

Before you begin, make sure you have:

  1. GitHub Account: A GitHub account (personal or organization)
  2. Chrome Extension Installed: SpikePrimeGit extension installed from the Chrome Web Store
  3. Repository Created: At least one GitHub repository where you'll save projects
  4. Basic GitHub Knowledge: Familiarity with GitHub basics (repositories, branches)

⚠️ Important Notes

  • OAuth App vs GitHub App: This guide creates a GitHub App (not an OAuth App). GitHub Apps are the modern, recommended approach.
  • Permissions: You'll need permission to create apps in your account or organization
  • Callback URL: The extension uses a specific callback URL that must be configured correctly

🛠️ Step 1: Create Your GitHub App

1

Navigate to GitHub App Settings

Choose where to create your app:

Option A: Personal Account

  1. Go to GitHub Settings → Developer settings → GitHub Apps
  2. Click "New GitHub App"

Option B: Organization Account

  1. Go to your organization settings
  2. Navigate to Developer settings → GitHub Apps
  3. Click "New GitHub App"
2

Configure Basic Information

Fill in the basic app information:

GitHub App name:

SpikePrimeGit-CustomApp

Or any name you prefer (must be unique across GitHub)

Homepage URL:

https://github.com/varunmehta/spike-prime-git

Or link to your own documentation

Description:

Sync LEGO SPIKE Prime projects to GitHub automatically
3

Configure Callback URL

🔴 CRITICAL: This must be exact or authentication will fail!

Callback URL:

https://<YOUR-EXTENSION-ID>.chromiumapp.org/

Replace <YOUR-EXTENSION-ID> with your actual extension ID

How to Find Your Extension ID:

  1. Open Chrome and go to chrome://extensions/
  2. Enable "Developer mode" (toggle in top-right)
  3. Find SpikePrimeGit in the list
  4. Copy the ID (long string like: abcdefghijklmnopqrstuvwxyz123456)
💡 Example: If your extension ID is ldiklhfinipoikhmfbnamjklkigcppoe, your callback URL would be:
https://ldiklhfinipoikhmfbnamjklkigcppoe.chromiumapp.org/
4

Configure Webhook Settings

Webhook:

☑️ Uncheck "Active" (webhooks not needed for this extension)

5

Configure Permissions

Set the following permissions under "Repository permissions":

Contents: Read and write

Required to read repository files and create commits

Metadata: Read-only

Automatically granted - required to list repositories

⚠️ Important: Do NOT grant more permissions than needed. The extension only requires Contents (Read and write) and Metadata (Read-only).
6

Configure User Permissions

Under "User permissions", no additional permissions are required. Leave all as "No access".

7

Configure Installation Options

Where can this GitHub App be installed?

Choose based on your needs:

  • Only on this account: For personal use only
  • Any account: If you want to share with others (advanced)

Recommendation: Select "Only on this account" for simplicity

8

Create the App

  1. Click "Create GitHub App" at the bottom
  2. You'll be taken to your new app's settings page

🎉 App Created!

Your GitHub App is now created. Next, we need to generate credentials for the extension.

9

Generate Client Credentials

On your app's settings page:

  1. Scroll down to "Client secrets" section
  2. Click "Generate a new client secret"
  3. IMMEDIATELY COPY the client secret (you won't be able to see it again!)
  4. Also note your Client ID (visible at the top of the page)
🔴 CRITICAL: Save your Client ID and Client Secret in a secure place (password manager, secure note, etc.). You'll need both to configure the extension.

Keep These Safe:

Client ID: Iv1.xxxxxxxxxxxxxxxx

Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

10

Install the App to Your Account

  1. On your app's settings page, click "Install App" in the left sidebar
  2. Click the Install button next to your account/organization
  3. Select repositories to grant access to:
    • All repositories: App can access all your repos
    • Only select repositories: Choose specific repos (recommended)
  4. Click "Install"

✅ Installation Complete!

Your GitHub App is now installed and ready to use. Next, we'll configure the extension.

⚙️ Step 2: Configure the Extension

1

Open Extension Options

  1. Click the SpikePrimeGit extension icon in Chrome
  2. If you're already connected, click "Disconnect" first
  3. Right-click the extension icon
  4. Select "Options" or go to chrome://extensions/ and click "Details" → "Extension options"
2

Enable Custom GitHub App Mode

In the extension options page:

  1. Find the "Use Custom GitHub App" section
  2. Toggle "Enable Custom GitHub App" ON
3

Enter Your App Credentials

Enter the credentials you saved earlier:

Client ID:

Client Secret:

⚠️ Keep Your Secret Safe: Never share your Client Secret publicly or commit it to version control.
4

Save and Connect

  1. Click "Save Settings"
  2. Close the options page
  3. Click the extension icon again
  4. Click "Connect to GitHub"
  5. Authorize the connection when prompted

🎉 Connected!

Your extension is now connected to your custom GitHub App!

✅ Step 3: Test Your Setup

Verify Everything Works

1. Check Connection Status

  1. Click the extension icon
  2. Verify you see "Connected as [your-username]"
  3. Verify you can see your repositories in the dropdown

2. Configure Settings

  1. Select a repository from the dropdown
  2. Select a branch (usually "main")
  3. Set a project path (e.g., "projects/")
  4. Click "Save Settings"

3. Test Sync

  1. Open SPIKE Prime software
  2. Create or open a project
  3. Make a small change and save (Ctrl+S or Cmd+S)
  4. Find the SpikePrimeGit card on the page
  5. Enter a commit message (e.g., "Test sync")
  6. Click "Sync to GitHub"
  7. Wait for the success notification

4. Verify on GitHub

  1. Go to your GitHub repository
  2. Navigate to the project path you configured
  3. Verify your .llsp3 file is there
  4. Check the commit message matches what you entered

🎊 Success!

If you see your project file on GitHub, everything is working correctly! You're now ready to use SpikePrimeGit with your custom GitHub App.

🔧 Troubleshooting

"Invalid callback URL" Error

Problem: Authentication fails with callback URL error.

Solution:

  • Double-check your callback URL in GitHub App settings
  • Make sure it matches: https://<extension-id>.chromiumapp.org/
  • Verify your extension ID at chrome://extensions/
  • Ensure the URL ends with a trailing slash (/)

"Unauthorized" or "403 Forbidden" Errors

Problem: Extension can't access repositories.

Solutions:

  • Verify your app is installed to your account (GitHub Settings → Applications → Installed GitHub Apps)
  • Check that the app has access to the repository you're trying to use
  • Verify your Client ID and Client Secret are correct
  • Make sure you granted Contents: Read and write permission
  • Try disconnecting and reconnecting the extension

Client Secret Lost or Compromised

Problem: You lost your Client Secret or it was exposed.

Solution:

  1. Go to your GitHub App settings
  2. Scroll to "Client secrets"
  3. Click "Revoke" on the compromised secret
  4. Click "Generate a new client secret"
  5. Update the extension options with the new secret
  6. Reconnect the extension

Want to Switch Back to Official App

When the official SpikePrimeGit app becomes available:

  1. Click the extension icon
  2. Click "Disconnect"
  3. Go to extension options
  4. Toggle "Enable Custom GitHub App" OFF
  5. Click "Save Settings"
  6. Click the extension icon and "Connect to GitHub"
  7. You'll now use the official app

Need More Help?

📚 Related Documentation