Integrate your Git providers (like GitHub, GitLab, or Bitbucket) directly into your workspace using our API. By connecting a Git provider, you can programmatically manage installations, sync repositories, and read file contents across your organization.

The Installation Flow

Connecting a Git provider requires a standard OAuth flow. You will request an installation URL, direct the user to authorize the application, and then handle the callback to finalize the setup.

sequenceDiagram
    participant Client as Your App
    participant API as Our API
    participant Provider as Git Provider
    
    Client->>API: GET /install-url
    API-->>Client: Returns OAuth Authorization URL
    Client->>Provider: Redirects user to authorize
    Provider-->>API: POST /callback (with auth code)
    API-->>Client: Installation complete

Setting up a new provider

1. 1

   Get the installation URL

   First, retrieve the OAuth authorization URL for the Git provider you want to connect. Direct your user to this URL so they can grant access to their repositories.

   GET /v1/organizations/{organization_id}/git-provider/install-url

2. 2

   Handle the callback

   Once the user authorizes the application, the Git provider will redirect them back with an authorization code. Send this data to the callback endpoint to complete the installation.

   POST /v1/organizations/{organization_id}/git-provider/callback

3. 3

   Verify the installation

   Confirm the setup was successful by listing the active installations for your organization.

   GET /v1/organizations/{organization_id}/git-provider/installations

Managing Installations

You can view or remove Git provider connections at any time using their unique installation IDs.

• Get a specific installation: GET /v1/organizations/{organization_id}/git-provider/installations/{installation_id}

• Delete an installation: DELETE /v1/organizations/{organization_id}/git-provider/installations/{installation_id}

Working with Repositories

Once a Git provider is installed, you can sync and manage the repositories your organization has access to.

Syncing and Listing

To ensure you have the latest list of repositories available from the provider, you should trigger a sync. After syncing, you can retrieve the full list.

1. Sync repositories: POST /v1/organizations/{organization_id}/git-provider/repositories/sync

2. List all repositories: GET /v1/organizations/{organization_id}/git-provider/repositories

3. Get a single repository: GET /v1/organizations/{organization_id}/git-provider/repositories/{repository_id}

Accessing File Content

You can programmatically explore the file system and retrieve the contents of specific files within a repository.

• Get repository file tree: Use GET /v1/organizations/{organization_id}/git-provider/repositories/{repository_id}/tree to retrieve the folder and file structure of the repository.

• Get file content: Use GET /v1/organizations/{organization_id}/git-provider/repositories/{repository_id}/content to read the raw content of a specific file.

API Endpoint Summary

Here is a quick reference of all Git provider endpoints available for your organization:

(Note: All paths above are prefixed with /v1/organizations/{organization_id})