> ## Documentation Index
> Fetch the complete documentation index at: https://docs.condense.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Private Version Control

### Overview

Condense supports integration with both **public GitLab (gitlab.com)** and **private/self-hosted GitLab instances**. This document describes how to configure Condense to work with a **private GitLab** deployment, using **OAuth 2.0 authentication** for secure repository and branch access.

Private GitLab integration enables:

* Repository access for Condense applications.
* Branch-level validation before pipelines run.
* Cloning source code into Condense build environments.
* Publishing and restoring applications backed by private Git repositories.

### Prerequisites

To integrate a private GitLab instance with Condense:

* **Running GitLab instance**: GitLab CE/EE deployed on-premise or in cloud (e.g., Docker-based EC2 deployment).
* **Domain name**: e.g., `gitlab.company.com`, pointing to the GitLab server.
* **TLS/SSL certificate**: HTTPS endpoint required (Let’s Encrypt, enterprise CA, or self-signed).
* **Admin account** in GitLab.
* **OAuth Application** configured in GitLab, providing:
  * **Client ID**
  * **Client Secret**
  * **Redirect URI** (Condense callback URL)
* **Network access**: Condense backend services must be able to reach your GitLab endpoint over HTTPS.

### Roles and Scopes in Private GitLab

#### Roles

* Guest → Limited visibility; cannot pull or push repository code.
* Reporter → Can pull repository content; cannot push.
* Developer → Can push commits, create branches (subject to branch protections).
* Maintainer → Full project control, including branch and merge request management.
* Owner → Administrative control at the group level.

#### Scopes

* read\_api → Allows Condense to query projects, groups, and metadata.
* read\_repository → Allows Condense to fetch repository contents.
* write\_repository (optional) → Allows Condense to push commits or update commit statuses if the user role permits it.

#### Effective Access

A user’s access = Role ∩ Scope ∩ Branch Protections.

Examples:

* Guest + read\_repository → cannot access repo contents (role blocks it).
* Reporter + read\_repository → can fetch repository code.
* Developer + read\_repository + write\_repository → can fetch and push, if branch rules allow.
* Maintainer + all scopes → full repository access, still subject to branch rules.
* Non-member → cannot link repositories, regardless of scopes.

### GitLab Configuration

#### Create OAuth Application in GitLab

1. Log in to your private GitLab instance as an administrator.
2. Navigate to **Admin Area → Applications**.
   <Frame>
     <img src="https://mintcdn.com/zeliot/V3FrQU0_JGAJgna8/images/image-39.png?fit=max&auto=format&n=V3FrQU0_JGAJgna8&q=85&s=55206045e643df8784e5c09b1fb53418" alt="Image" width="2304" height="1388" data-path="images/image-39.png" />
   </Frame>
3. Select **New Application** and provide the following:
   * **Name**: Condense Integration
   * **Redirect URI**: [https://central-tower-dev.zeliot.in/redirect](https://central-tower-dev.zeliot.in/redirect)
   * **Scopes**: select `api`
4. Save and note the generated **Client ID** and **Client Secret**.

Reference: GitLab OAuth Applications

<Frame>
  <img src="https://mintcdn.com/zeliot/V3FrQU0_JGAJgna8/images/image-40.png?fit=max&auto=format&n=V3FrQU0_JGAJgna8&q=85&s=c0803e61fdcb02ed24262f007a49887a" alt="Image" width="1200" height="625" data-path="images/image-40.png" />
</Frame>

Defining the scope of the application

<Frame>
  <img src="https://mintcdn.com/zeliot/V3FrQU0_JGAJgna8/images/image-41.png?fit=max&auto=format&n=V3FrQU0_JGAJgna8&q=85&s=6695dd8cd5c31535bb1d8c35ff8e2e8c" alt="Image" width="1200" height="625" data-path="images/image-41.png" />
</Frame>

### Condense Configuration

#### Provider Registration (Admin Only)

Private GitLab instances must be registered in Condense by an organization admin.

| Field                | Description                                 | Example                                        |
| -------------------- | ------------------------------------------- | ---------------------------------------------- |
| **vcProvider**<br /> | Provider identifier                         | `gitlab`                                       |
| url                  | Base URL of the GitLab instance             | `https://gitlab.company.com`                   |
| **redirectUri**      | Callback URI for OAuth exchange             | `https://central-tower-dev.zeliot.in/redirect` |
| **clientId**         | Client ID from GitLab OAuth application     | `abc123...`                                    |
| **clientSecret**     | Client Secret from GitLab OAuth application | `********`                                     |

Configuration is stored in the `vc_provider_config` table and can be added via API:

```text theme={null}
POST /version-control/createVcProviderConfig
```

#### User Authentication Flow

1. User initiates login with GitLab in Condense.
2. Condense redirects the request to the private GitLab OAuth endpoint:
   Copy
   ```text theme={null}
   https://central-tower-dev.zeliot.in/redirect
   ```
   <Frame>
     <img src="https://mintcdn.com/zeliot/V3FrQU0_JGAJgna8/images/image-42.png?fit=max&auto=format&n=V3FrQU0_JGAJgna8&q=85&s=b3e385583c85493797c41fcbbb895fc6" alt="Image" width="1200" height="625" data-path="images/image-42.png" />
   </Frame>
3. GitLab issues an authorization code.
4. Condense exchanges the authorization code for an access token:

Copy

```text theme={null}
POST https://central-tower-dev.zeliot.in/redirect
```

1. Condense stores the access and refresh tokens in `vc_auth_details`.
2. Token refresh is handled automatically using Client ID and Client Secret.

### Application Lifecycle with Private GitLab

Condense integrates private GitLab repositories across the entire application lifecycle:

| Phase                    | Action                                                                   |
| ------------------------ | ------------------------------------------------------------------------ |
| **Application Creation** | Application created in draft state, without version control attached.    |
| **Configure Repository** | User selects GitLab repo + branch; Condense stores mapping.              |
| **Validate Access**      | Condense calls `/checkUserHasRepoAndBranchAccess` to verify permissions. |
| **Clone Repository**     | Condense clones the repo into its build container using OAuth token.     |
| **Publish Application**  | Application validated and published as a connector.                      |
| **Restore Application**  | Condense re-clones the repository from GitLab when restoring.            |

### Configuration Example

A typical provider configuration payload for private GitLab:

Copy

```text theme={null}
{
  "vcProvider": "gitlab",
  "url": "https://gitlab.company.com",
  "redirectUri": "https://central-tower-dev.zeliot.in/redirect",
  "clientId": "1234567890abcdef",
  "clientSecret": "abcdef1234567890"
}
```

### Restrictions

* Only **HTTPS endpoints** supported; plain HTTP is not allowed.
* Authentication supported only via **OAuth 2.0**. SSH keys and basic authentication are not supported.
* Repository and branch visibility is determined entirely by GitLab RBAC. Condense does not override GitLab permissions.
* GitLab API rate limits apply (default: \~600 requests/minute per token).

### Controls

* **Admin Control**: Only admins can register a private GitLab instance in Condense.
* **Org-Scoped Configs**: Configurations are stored at the organization level.
* **Access Enforcement**: Users only see repositories and branches they are authorized for in GitLab.
* **Token Lifecycle**: Tokens are encrypted, refreshed automatically, and revocable by admins.
* **Audit Logging**: All VCS interactions (auth, repo fetch, branch validation, clone) are logged.

### Best Practices

* Minimize scope selection — default to read-only unless write access is justified.
* Use Protected Branches to enforce push/merge policies, regardless of Condense integration.
* Educate users: scopes = APIs allowed; roles = actual repository permissions.
* Audit Condense-linked repositories quarterly for compliance.
* Keep Condense as a consumer of repository data; governance remains in GitLab.

### Troubleshooting

| Issue                      | Resolution                                                               |
| -------------------------- | ------------------------------------------------------------------------ |
| **401 Unauthorized**       | Verify Client ID/Secret; check token refresh.                            |
| **Repository not visible** | Confirm user permissions in GitLab.                                      |
| **Branch access denied**   | Check GitLab branch-level RBAC.                                          |
| **SSL errors**             | Verify certificate validity and Nginx reverse proxy config.              |
| **Rate limit exceeded**    | Reduce API polling frequency; consider higher<br /> API quota in GitLab. |

### References

* [GitLab OAuth Applications](https://docs.gitlab.com/integration/oauth_provider/)
* [GitLab REST API](https://docs.gitlab.com/api/)
* [Private GitLab Setup Guide](https://zeliotinc-my.sharepoint.com/:b:/g/personal/rakesht_zeliot_in/ERabfPdy-VJMrz8uEbdJrqgB9Co80jrNYTvzNslVosDvqQ?e=KSbb8l)
* [Condense Private Version Control – Technical Reference](https://zeliotinc-my.sharepoint.com/:b:/g/personal/rakesht_zeliot_in/EXm7SK7A7SpPjoc-tfT3rHMBvS_sL7TbFJCUSNM4hvPtlQ?e=vz8tHz)