# GitLab

The GitLab integration connects Interlynk to your GitLab groups and projects, enabling automated SBOM processing triggered by repository events.

***

## Purpose

* Automatically ingest SBOMs on push and merge request events.
* Map GitLab branches to Interlynk environments.
* Support both GitLab.com (SaaS) and self-managed GitLab instances.

## Setup Steps

Interlynk connects to GitLab via OAuth.

1. Navigate to **Settings > Organization > Integrations**.
2. Click **GitLab**.
3. You will be redirected to GitLab to authorize the Interlynk application.
4. Complete the authorization.
5. After redirect, select the **Workspace/Group** from the dropdown to scope the integration.
6. Click **Save**.

### Group vs. Project Setup

* **Group-level**: Grants access to all projects within the group. Recommended for organizations that want full coverage.
* **Project-level**: Limit the integration to specific projects by selecting the appropriate group and configuring environment rules per project.

## Supported Events

| Event                     | Trigger                  |
| ------------------------- | ------------------------ |
| `push`                    | Code pushed to a branch  |
| `merge_request` (created) | New merge request opened |
| `merge_request` (merged)  | Merge request merged     |
| `merge_request` (updated) | Merge request updated    |

## Required Permissions

The OAuth application requests:

| Scope              | Purpose                                  |
| ------------------ | ---------------------------------------- |
| `read_repository`  | Access repository contents               |
| `read_api`         | Query project and group metadata         |
| `write_repository` | Post merge request comments (if enabled) |

## Security Notes

* OAuth tokens are encrypted at rest and automatically refreshed on expiry.
* For self-managed GitLab instances, verify your instance URL is accessible from the Interlynk platform.
* Revoke access from GitLab's **User Settings > Applications** if needed.

## Troubleshooting

| Issue                             | Cause                               | Resolution                                                           |
| --------------------------------- | ----------------------------------- | -------------------------------------------------------------------- |
| No groups visible after auth      | Token scope too narrow              | Re-authorize with broader group access                               |
| Events not triggering             | Webhook not registered on project   | Verify the workspace/group selection matches your target projects    |
| Self-managed instance unreachable | Network/firewall restriction        | Ensure your GitLab instance is accessible from Interlynk's IP ranges |
| Token refresh failures            | OAuth application revoked on GitLab | Disconnect and reconnect the integration                             |