Connecting your Git provider (like GitHub, GitLab, or Bitbucket) allows the platform to securely access your repositories, sync files, and read project structures. This page explains how the OAuth authentication flow works and how to manage your connected Git installations and repositories.
By understanding this flow, you can seamlessly integrate Git providers into your organization's workspace and troubleshoot connection issues.
The OAuth Authentication Flow
We use a standard OAuth 2.0 flow to securely connect to Git providers without ever seeing or storing your users' passwords.
Here is a high-level overview of how the authentication process works:
sequenceDiagram
participant U as User
participant App as Your Application
participant API as Platform API
participant Git as Git Provider (e.g., GitHub)
U->>App: Clicks "Connect Git"
App->>API: Request Install URL
API-->>App: Returns Secure OAuth URL
App->>U: Redirects to Git Provider
U->>Git: Approves Application Access
Git->>API: Redirects via Callback URL
API-->>App: Installation CompleteConnecting a Git Provider
To establish a new Git connection for your organization, you'll need to guide the user through the following steps.
- 1
Generate the Installation URL
First, request the installation URL for your specific organization. This URL contains the necessary OAuth scopes and redirect parameters.
GET /v1/organizations/{organization_id}/git-provider/install-url - 2
Authorize Access
Redirect the user to the generated URL. They will be taken to their Git provider's website to review the requested permissions and authorize the application.
- 3
Handle the Callback
Once authorized, the Git provider redirects the user back to the platform. The system automatically processes the OAuth callback and establishes the connection.
POST /v1/organizations/{organization_id}/git-provider/callback
Ensure your organization's callback URLs are correctly configured in your Git provider's developer settings to prevent routing errors during step 3.
Managing Installations
Once a Git provider is connected, it is tracked as an Installation. You can have multiple installations if you connect different providers or distinct accounts.
If you need to check the status of a specific connection, you can fetch it directly by its ID (GET .../installations/{installation_id}).
Removing an Installation
If a user no longer wants their repositories synced, you can delete the installation.
Deleting an installation (DELETE .../installations/{installation_id}) immediately revokes our access to the Git provider. All synced repositories tied to this installation will stop receiving updates.
Working with Repositories
After a successful OAuth connection, you gain access to the repositories authorized by the user.
| Action | Endpoint | Description |
|---|---|---|
| List Repositories | GET /.../repositories | View all repositories available under the current installations. |
| Get Repository | GET /.../repositories/{id} | Retrieve details for a specific repository by its ID. |
| Sync Repositories | POST /.../repositories/sync | Manually trigger a synchronization to fetch the latest commits and branches. |
| Get File Tree | GET /.../repositories/{id}/tree | Retrieve the folder and file structure of a specific repository. |
| Read File Content | GET /.../repositories/{id}/content | Fetch the raw content of a specific file within the repository. |
If a user adds a new repository to their Git account after the initial installation, you may need to invoke the Sync Repositories endpoint to make it visible in your organization.
Frequently Asked Questions
What happens if a user revokes access directly from GitHub?
If a user goes into their GitHub (or other provider) settings and revokes the OAuth application, the platform's API calls will begin failing with 401 Unauthorized errors. You will need to prompt the user to go through the OAuth connection flow again to generate a fresh token.
Why aren't my newly created repositories showing up?
Repository lists are cached for performance. If you just created a new repository on your Git provider, use the POST /v1/organizations/{organization_id}/git-provider/repositories/sync endpoint to force an immediate refresh of your repository list.
Can I connect multiple Git providers to one organization?
Yes. You can complete the OAuth flow multiple times to connect different providers (like GitHub and GitLab) or multiple accounts from the same provider to a single organization.