GitHub Integration

The One Code connects to GitHub using a GitHub App installation — the most secure and capable integration method GitHub offers. This page explains the GitHub App architecture, how the connection flow works, what data is accessed, and how to manage multiple organizations.

GitHub App vs. OAuth

The One Code uses a GitHub App (App ID: 3034314) rather than personal access tokens or OAuth Apps. Here's why this matters for you and your clients:

	GitHub App	Personal Access Token
Auth method	RS256 JWT signed with private key	Long-lived token tied to a user
Permissions	Granular, per-installation scopes	Broad scopes
Access	Organization-scoped	User-scoped
Rotation	Short-lived installation tokens (1 hour)	Manual rotation required
Audit trail	GitHub shows all app activity	Actions appear as the user
Revocation	Org admin can uninstall instantly	Must revoke at user account level

For MSP clients who are security-conscious, the GitHub App model is the right story to tell. Installation tokens expire after one hour and are generated on-demand — your client's code is never accessible with a static credential.

The Installation Flow

When an MSP technician clicks Connect Organization → GitHub, this is what happens:

1. State token created — The One Code generates a cryptographic state token (HMAC-SHA256) tied to the current tenant and stores it with a 10-minute TTL. This prevents CSRF attacks during the OAuth flow.

2. Redirect to GitHub — The browser navigates to https://github.com/apps/the-one-code/installations/new with the state token and redirect URI embedded.

3. GitHub App installation — The org admin chooses which repositories to grant access to (all repos or selected repos) and clicks Install.

4. GitHub redirects back — GitHub sends the installation_id and the original state token to The One Code's callback endpoint.

5. Repository enumeration — The One Code immediately fetches the list of all repositories in the installation using the GitHub API. For each repo:

   • A repository record is created in The One Code
   • An application profile stub is created (to be populated by analysis)
   • A backup job is queued at normal priority

6. Org record created — The organization is stored with its GitHub login, display name, avatar, installation ID, and default backup settings (daily schedule, 90-day retention).

7. Redirect to success — The technician sees the confirmation screen showing the org name and repo count.

The entire flow from clicking "Install" on GitHub to seeing backed-up repos in The One Code typically takes under 60 seconds for organizations up to ~200 repositories.

What the App Accesses

The GitHub App requests the minimum permissions needed for each feature:

Permission	Level	Used For
Contents	Read	Backup, AI documentation, secret scanning, SBOM
Metadata	Read	Repo enumeration, app type detection
Issues	Read	Backup of issue history
Pull requests	Read	Backup of PR history
Members	Read	Access audit (org members, 2FA status)
Administration	Read	Branch protection rules, org settings
Webhooks	Read + Write	Detect new repos, push events for real-time analysis

The app does not request write access to repository contents, issues, or pull requests. It cannot push code, merge PRs, or modify your client's repositories.

Managing Multiple Orgs

A single MSP tenant can connect any number of organizations across multiple clients. Each org is independent:

• Separate backup schedules and retention settings
• Separate compliance posture
• Separate access audit history
• Reports can be generated per-org or across all orgs

To add another organization:

1. Go to Organizations
2. Click Connect Organization
3. Follow the same flow for GitHub, GitLab, or Azure DevOps

ℹ️If a client has multiple GitHub orgs (for example, separate orgs for production and internal tools), you can connect all of them. They'll appear as separate entries in your org list, but you can filter the portfolio view by client to see them together.

Disconnecting an Organization

When you disconnect an org:

1. All active backup jobs for that org are paused
2. Existing backup snapshots are not deleted — they remain until their retention expiry
3. The organization record is marked as disconnected
4. The GitHub App installation is not automatically uninstalled on GitHub — you'll need to do that separately from your GitHub organization settings if desired

To reconnect a previously disconnected org, connect it again through the normal flow. The One Code will detect that repos already exist and sync only new additions.

Force Sync (New Repositories)

When a new repository is added to a connected GitHub org, The One Code learns about it two ways:

1. Push webhook — If the GitHub App has webhook access, repository creation events trigger an immediate sync
2. Scheduled sync — A background timer runs every few hours and checks each connected org for new repositories

If a new repo isn't appearing in The One Code, trigger a manual sync:

1. Navigate to the org in Organizations
2. Click Sync Repositories
3. The One Code queries the GitHub API and creates records for any new repos found

The sync operation reports how many repos were found and how many were newly added.

Authentication Details

Behind the scenes, The One Code authenticates to GitHub using installation access tokens:

• A short-lived JWT is signed with the GitHub App's RS256 private key (stored in Azure Key Vault)
• This JWT is exchanged for an installation access token scoped to the specific org installation
• Installation tokens expire after 1 hour
• Tokens are never stored — they're generated on demand for each API call or backup job

This means that even if The One Code's database were compromised, there are no long-lived GitHub credentials to steal.

Multi-Provider Support

Beyond GitHub, The One Code supports:

GitLab

• Connection via GitLab OAuth
• Access to groups and repositories
• Same backup capabilities as GitHub

Azure DevOps

• Connection via Microsoft OAuth
• Access to organizations and repositories
• Integrates naturally with clients who use the Microsoft ecosystem

For non-GitHub providers, connection tokens are stored encrypted in Cosmos DB. Token refresh is handled automatically before expiry.

Webhook Events

The GitHub App receives webhook events for:

• repository.created — triggers repo discovery and backup
• push — triggers real-time analysis if a dependency file or code structure file changed
• installation.repositories_added — new repos added to a partial installation

Webhooks are validated using X-Hub-Signature-256 HMAC-SHA256 with the webhook secret stored in Azure Key Vault.

Troubleshooting

The GitHub App install page shows an error

The state token from step 1 has a 10-minute TTL. If you spent more than 10 minutes on the GitHub installation page, the state will have expired. Start the connection flow again.

Repositories aren't appearing after installation

The repository enumeration happens in the callback. If GitHub's API was slow or returned a partial result:

1. Go to the org in Organizations
2. Click Sync Repositories to manually trigger a fresh enumeration

The org shows "Disconnected" status

This usually means the GitHub App was uninstalled from the org's GitHub settings. Reconnect by starting the connect flow again.

New repos added to the GitHub org aren't showing in The One Code

Either wait for the next scheduled sync (runs every few hours), or manually trigger Sync Repositories from the org detail page.