Integrate your Git provider (such as GitHub, GitLab, or Bitbucket) to seamlessly manage repositories, sync files, and automate your workflows. This guide walks you through the OAuth authentication flow and the API endpoints available for managing your Git provider installations.
By completing the OAuth flow, you grant your organization secure access to read and manage repository contents without handling user passwords directly.
The OAuth Authentication Flow
Connecting a Git provider requires a standard OAuth 2.0 flow. You will request an installation URL, redirect your user to authorize the application, and then handle the callback to finalize the installation.
sequenceDiagram
participant User
participant App as Your Application
participant API as API
participant Git as Git Provider
App->>API: GET /git-provider/install-url
API-->>App: Returns OAuth Authorization URL
App->>User: Redirect to Authorization URL
User->>Git: Approves access
Git-->>App: Redirects back with auth code
App->>API: POST /git-provider/callback
API-->>App: Installation successful- 1
Get the installation URL
First, retrieve the OAuth authorization URL for your Git provider. Redirect your user to this URL so they can log in and grant access to their repositories.
GET /v1/organizations/{organization_id}/git-provider/install-url - 2
User authorizes the application
The user reviews the requested permissions on the Git provider's website and approves the installation. Once approved, the provider redirects the user back to your application with an authorization code.
- 3
Handle the callback
Send the authorization code received from the Git provider to the callback endpoint. This completes the OAuth flow and creates the installation in your organization.
POST /v1/organizations/{organization_id}/git-provider/callback
Always ensure your application securely handles the state parameter during the OAuth flow to prevent Cross-Site Request Forgery (CSRF) attacks.
Managing Installations
Once a Git provider is connected, it is registered as an "installation" within your organization. You can view, inspect, or remove these installations using the following endpoints:
| Action | Method | Endpoint |
|---|---|---|
| List installations | GET | /v1/organizations/{organization_id}/git-provider/installations |
| Get installation details | GET | /v1/organizations/{organization_id}/git-provider/installations/{installation_id} |
| Delete installation | DELETE | /v1/organizations/{organization_id}/git-provider/installations/{installation_id} |
Deleting an installation immediately revokes access to all associated repositories. Any automated syncs or webhooks relying on this installation will fail until it is reconnected.
Working with Repositories
With an active installation, you can access and manage the repositories the user granted you access to.
Repository Endpoints
Use these endpoints to browse repositories, read file contents, and explore directory trees:
| Action | Method | Endpoint |
|---|---|---|
| List repositories | GET | /v1/organizations/{organization_id}/git-provider/repositories |
| Sync repositories | POST | /v1/organizations/{organization_id}/git-provider/repositories/sync |
| Get repository details | GET | /v1/organizations/{organization_id}/git-provider/repositories/{repository_id} |
| Get file content | GET | /v1/organizations/{organization_id}/git-provider/repositories/{repository_id}/content |
| Get repository file tree | GET | /v1/organizations/{organization_id}/git-provider/repositories/{repository_id}/tree |
If a user recently added a new repository to their Git provider account but it isn't showing up in your application, use the Sync repositories endpoint to fetch the latest data.
Frequently Asked Questions
When should I use the file tree vs. file content endpoints?
Use the file tree endpoint (.../tree) when you need to display a directory structure or find specific files within a repository. Once you have the exact path of the file you need, use the file content endpoint (.../content) to retrieve the actual code or text inside that file.
Can I connect multiple Git providers?
Yes. Your organization can have multiple installations. For example, you can connect both a GitHub account and a GitLab account simultaneously. Use the List installations endpoint to keep track of all active connections.