Connecting your external Git provider allows you to seamlessly sync repositories, browse file trees, and access code directly within your organization. This guide walks you through the setup, synchronization, and management process.

How the Integration Works

Before diving into the setup, it helps to understand the connection flow. The integration uses a standard OAuth process to securely grant your organization access to your Git provider.

sequenceDiagram
    participant Admin as Organization Admin
    participant Platform as Our Platform
    participant Git as Git Provider (e.g., GitHub)
    
    Admin->>Platform: Request Installation URL
    Platform-->>Admin: Returns unique OAuth URL
    Admin->>Git: Approves access in browser
    Git-->>Platform: Sends OAuth Callback
    Platform-->>Admin: Installation Complete!

Connecting a Git Provider

To link a new Git provider to your organization, you'll need to complete the OAuth authorization flow.

1. 1

   Get the Installation URL

   First, retrieve the unique installation URL for your organization. This URL redirects you to the Git provider's authorization page.
   Endpoint: GET /v1/organizations/{organization_id}/git-provider/install-url

2. 2

   Authorize the Application

   Navigate to the provided URL in your browser. You will be prompted by your Git provider to grant access to your repositories. Review the permissions and approve the request.

3. 3

   Handle the Callback

   Once approved, the Git provider will redirect you back to the platform with an authorization code. The system processes this automatically via the callback endpoint to finalize the connection.
   Endpoint: POST /v1/organizations/{organization_id}/git-provider/callback

Managing Repositories

After successfully installing the Git provider, you can begin interacting with your repositories.

Syncing Repositories

To ensure the platform has the latest list of your available repositories, you should trigger a synchronization.

• Trigger a Sync: Use POST /v1/organizations/{organization_id}/git-provider/repositories/sync to pull in the latest repository metadata from your provider.

• List Repositories: Use GET /v1/organizations/{organization_id}/git-provider/repositories to view all repositories currently linked to your organization.

• Get Repository Details: Use GET /v1/organizations/{organization_id}/git-provider/repositories/{repository_id} to retrieve specific information about a single repository.

Accessing Repository Content

Once a repository is synced, you can programmatically access its structure and files.

Managing Installations

You can have multiple Git provider installations linked to a single organization. Use the following tools to manage your active connections.