GitHub Setup

BeatConnect uses a GitHub App for secure repository access. This gives you fine-grained control over which repositories we can access, without sharing your personal access tokens.

Installing the GitHub App

Step 1: Start the Connection

1. Go to Creator Portal → Settings → Developer
2. Click Connect GitHub

You’ll be redirected to GitHub to authorize the app.

Step 2: Choose Installation Scope

GitHub will ask where to install the BeatConnect app:

Option	Best For
Personal Account	Solo developers
Organization	Teams, companies, or multiple collaborators

Select your preferred account.

Step 3: Select Repositories

Choose which repositories the app can access:

Option	Description
All repositories	Access to all current and future repos
Only select repositories	Choose specific repos (recommended)

Recommendation: Start with “Only select repositories” and add more as needed. You can change this later.

Step 4: Authorize

Click Install & Authorize. You’ll be redirected back to BeatConnect.

Verification

After successful connection, you’ll see:

• ✅ GitHub Connected
• Account: your-username or your-org
• Connected: [timestamp]

Managing Repository Access

Adding More Repositories

1. Go to GitHub Settings → Applications → Installed GitHub Apps
2. Find BeatConnect Build System
3. Click Configure
4. Add or remove repository access

Checking Access

In the Creator Portal:

1. Go to Projects → Link External Repository
2. You’ll see a list of accessible repositories
3. Missing a repo? Click Manage GitHub Access

Multiple Accounts

You can connect repositories from:

• Your personal GitHub account
• Multiple GitHub organizations
• Any account where you have admin access

Each connection creates a separate installation with its own repository scope.

Permissions Explained

The BeatConnect GitHub App requests these permissions:

Permission	Level	Purpose
Repository contents	Read	Clone code for building
Metadata	Read	List repositories, check topics
Actions	Read & Write	Trigger and monitor builds
Webhooks	Read & Write	Receive push notifications

What We CAN Do

• ✅ Read your source code (only during builds)
• ✅ Trigger GitHub Actions workflows
• ✅ Receive webhook events (pushes, releases)
• ✅ Read repository metadata

What We CANNOT Do

• ❌ Push code to your repository
• ❌ Delete branches or repositories
• ❌ Access your GitHub profile data
• ❌ Modify repository settings
• ❌ Access other users’ private repos

Repository Discovery

BeatConnect automatically discovers repositories tagged with the beatconnect-plugin topic.

Adding the Topic

Via GitHub CLI:

gh repo edit --add-topic beatconnect-plugin

Via GitHub Website:

1. Go to your repository
2. Click the gear icon next to “About”
3. Add beatconnect-plugin to Topics
4. Click Save changes

Why Use Topics?

• Automatic project discovery in Creator Portal
• Easy filtering of plugin repositories
• Optional but recommended

Webhook Configuration

When you link a repository, BeatConnect automatically:

1. Creates a webhook for push events
2. Configures secure signature verification
3. Enables automatic build triggers (optional)

Webhook Events

Event	Action
push	Optionally trigger build
release	Optionally trigger release build
repository	Sync repository metadata

Automatic Builds

You can configure automatic builds on push:

1. Go to Project Settings
2. Enable Auto-build on push
3. Configure filters:
   • Branch: main, release/*, etc.
   • Files: Only when source files change

Troubleshooting

”Repository not found”

Cause: GitHub App doesn’t have access to the repository.

Fix:

1. Go to GitHub → Settings → Applications
2. Configure BeatConnect app
3. Add the missing repository

”Installation not found”

Cause: GitHub App was uninstalled or you’re using a different account.

Fix:

1. Disconnect GitHub in Creator Portal
2. Reconnect with the correct account

”Access denied to organization”

Cause: Organization requires approval for new apps.

Fix:

1. Ask an organization admin to approve the app
2. Or use a personal fork of the repository

”Rate limit exceeded”

Cause: Too many API requests (rare).

Fix:

• Wait 1 hour for rate limit reset
• Reduce build frequency if hitting limits regularly

Disconnecting

To remove BeatConnect access:

From Creator Portal

1. Go to Settings → Developer
2. Click Disconnect GitHub
3. Confirm disconnection

From GitHub

1. Go to GitHub Settings → Applications
2. Find BeatConnect Build System
3. Click Uninstall

Note: Disconnecting removes access to all repositories. Linked projects will show “Repository disconnected” and cannot build until reconnected.

Security Best Practices

1. Use minimal scope — Only grant access to plugin repositories
2. Review access regularly — Remove repos you no longer need
3. Audit builds — Check build logs for unexpected activity
4. Use branch protection — Prevent unauthorized pushes to main branches

Next Steps

• Build your first plugin
• Set up your repository structure
• Configure build options