# 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**.

<div data-with-frame="true"><figure><img src="https://content.gitbook.com/content/rwKRGO3QthZ6EMqqYblg/blobs/0MJUg4fCnPJxAkDZ9Ukx/image.png" alt=""><figcaption></figcaption></figure></div>

1. Select **New Application** and provide the following:
   * **Name**: Condense Integration
   * **Redirect URI**: <https://central-tower-dev.zeliot.in/redirect>
   * **Scopes**: select `api`
2. Save and note the generated **Client ID** and **Client Secret**.

Reference: GitLab OAuth Applications

<div data-with-frame="true"><figure><img src="https://content.gitbook.com/content/rwKRGO3QthZ6EMqqYblg/blobs/DVsBKxI2sxHMXyShNI9V/image.png" alt=""><figcaption></figcaption></figure></div>

Defining the scope of the application

<div data-with-frame="true"><figure><img src="https://content.gitbook.com/content/rwKRGO3QthZ6EMqqYblg/blobs/tIdTMm0yRscBxEfABbNK/image.png" alt=""><figcaption></figcaption></figure></div>

### Condense Configuration

#### Provider Registration (Admin Only)

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

| Field            | Description                                 | Example                                                                                        |
| ---------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **vcProvider**   | 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`](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:

```http
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:

   ```
   https://central-tower-dev.zeliot.in/redirect
   ```

<div data-with-frame="true"><figure><img src="https://content.gitbook.com/content/rwKRGO3QthZ6EMqqYblg/blobs/FrDmQ06YcAgD5y3lAMes/image.png" alt=""><figcaption></figcaption></figure></div>

3. GitLab issues an authorization code.
4. Condense exchanges the authorization code for an access token:

```
POST https://central-tower-dev.zeliot.in/redirect
```

5. Condense stores the access and refresh tokens in `vc_auth_details`.
6. 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:

```json
{
  "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&#x20;

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

### 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 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)