# GitLabService

**Kind:** Service

**Source:** [`atloria-monorepo/apps/api/src/gitlab/gitlab.service.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/gitlab/gitlab.service.ts#L5)

`GitLabService` manages the backend integration between the API and GitLab. It handles the OAuth connection flow, reports connection state, retrieves repositories and branches for the authenticated user, and disconnects the current GitLab account.

## Methods

| Method | Signature | Returns | Description |
|---|---|---|---|
| `getAuthUrl` | `getAuthUrl(userId: string)` | `string` | Generate the GitLab OAuth authorization URL |
| `handleCallback` | `handleCallback(code: string, userId: string)` | `Promise<void>` | Exchange authorization code for access token and store it |
| `getConnectionStatus` | `getConnectionStatus(userId: string)` | `Promise<{ connected: boolean; username: string | null }>` | Check if user has GitLab connected |
| `listRepos` | `listRepos(userId: string)` | `Promise<any[]>` | List projects for the connected GitLab account. |
| `listBranches` | `listBranches(userId: string, owner: string, repo: string)` | `Promise<any[]>` | List branches for a specific project |
| `disconnect` | `disconnect(userId: string)` | `Promise<void>` | Disconnect GitLab from user account |

## Dependencies

- `PrismaService`
- `ConfigService`

## Where it refuses work

- `GitLabService` stops the work with `Error` when `!retryResponse.ok`.
- `GitLabService` stops the work with `Error` when `!projectResponse.ok`.
- `GitLabService` stops the work with `Error` when `!response.ok`.
- `GitLabService` stops the work with `UnauthorizedException` when `!user?.gitlabAccessToken` — “GitLab not connected. Please authorize first.”.

## Diagram

```mermaid
sequenceDiagram
  participant Client
  participant API as GitLab Controller/API
  participant Service as GitLabService
  participant GitLab as GitLab OAuth/API

  Client->>API: Request GitLab authorization URL
  API->>Service: getAuthUrl()
  Service-->>API: OAuth authorization URL
  API-->>Client: Redirect URL

  Client->>GitLab: Authorize application
  GitLab->>API: OAuth callback
  API->>Service: handleCallback()
  Service->>GitLab: Exchange callback code for token
  GitLab-->>Service: Access token and user details
  Service-->>API: Persist connection

  Client->>API: List repositories or branches
  API->>Service: listRepos() / listBranches()
  Service->>GitLab: Fetch authenticated resources
  GitLab-->>Service: Repository/branch data
  Service-->>API: Resource list
  API-->>Client: JSON response
```

## Usage

```ts
import { Controller, Get, Redirect } from '@nestjs/common';
import { GitLabService } from './gitlab.service';

@Controller('gitlab')
export class GitLabController {
  constructor(private readonly gitLabService: GitLabService) {}

  @Get('connect')
  @Redirect()
  connect() {
    return {
      url: this.gitLabService.getAuthUrl(),
    };
  }

  @Get('status')
  getStatus() {
    return this.gitLabService.getConnectionStatus();
  }

  @Get('repos')
  listRepositories() {
    return this.gitLabService.listRepos();
  }

  @Get('branches')
  listBranches() {
    return this.gitLabService.listBranches();
  }

  @Get('disconnect')
  async disconnect() {
    await this.gitLabService.disconnect();

    return { connected: false };
  }
}
```

## AI Coding Instructions

- Keep GitLab OAuth logic inside `GitLabService`; controllers should only map HTTP requests and responses.
- Call `getConnectionStatus()` before invoking repository or branch operations when the caller may not have an active GitLab connection.
- Ensure `handleCallback()` is invoked only from the validated OAuth callback route and preserves any required authorization state.
- Treat repository and branch responses as external API data; add explicit DTOs or typed interfaces before relying on fields returned as `any[]`.
- Use `disconnect()` to clear stored GitLab credentials rather than deleting connection data directly from controllers or other services.

## Relationships

- DEPENDS_ON → `PrismaService`
- DEPENDS_ON → `configservice`

## Referenced By

- `GitLabController` (DEPENDS_ON)
- `GitLabModule` (MODULE_PROVIDES)
- `GitLabModule` (MODULE_EXPORTS)