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

# GitLab

> Client-mode REST API connector for a curated GitLab REST API v4 slice: pipeline trigger, releases, issues, generic package download, user smoke, and project webhook create

Technical Preview

## Overview

A client-mode connector for a **curated DevOps** slice of the [GitLab REST API v4](https://docs.gitlab.com/ee/api/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST trigger/pipeline | `POST /projects/{id}/trigger/pipeline` | Pipeline **trigger token** + `ref` (not a PAT) |
| GET releases | `GET /projects/{id}/releases` | List project releases |
| POST issues | `POST /projects/{id}/issues` | Create issue from alarm / MQTT |
| GET generic package file | `GET /projects/{id}/packages/generic/{name}/{version}/{file}` | Firmware / artifact download |
| GET /user (smoke) | `GET /user` | Credential check → `id` / `username` |
| POST hooks | `POST /projects/{id}/hooks` | Register GitLab → HTTPS target |

Default `BASE_ADDRESS` is `https://gitlab.com/api/v4` (no trailing slash). Self-hosted: `https://YOUR_HOST/api/v4`. Topics use `devops/gitlab/<object>/<verb>`.

> [!NOTE]
>
> Auth prefers **`PRIVATE-TOKEN`** (personal / project / group access token). OAuth 2.0 may use `Authorization: Bearer …` instead. Prefer Hub secret `GITLAB_TOKEN` (aliases `GITLAB_PRIVATE_TOKEN`, `GITLAB_ACCESS_TOKEN`). Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — GitLab REST API v4
# Auth: PRIVATE-TOKEN {value.json.private_token} (PAT); trigger uses query token
# BASE_ADDRESS: https://gitlab.com/api/v4

DEFINE ROUTE GitlabRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://gitlab.com/api/v4"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuser
        WITH SOURCE_TOPIC "devops/gitlab/user/get"
        WITH DESTINATION_TOPIC "devops/gitlab/user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/user"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
    ADD EVENT Triggerpipeline
        WITH SOURCE_TOPIC "devops/gitlab/pipeline/trigger"
        WITH DESTINATION_TOPIC "devops/gitlab/pipeline/trigger/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/projects/{value.json.project_id}/trigger/pipeline?token={value.json.trigger_token}&ref={value.json.ref}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Listreleases
        WITH SOURCE_TOPIC "devops/gitlab/release/list"
        WITH DESTINATION_TOPIC "devops/gitlab/release/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/projects/{value.json.project_id}/releases"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
    ADD EVENT Createissue
        WITH SOURCE_TOPIC "devops/gitlab/issue/create"
        WITH DESTINATION_TOPIC "devops/gitlab/issue/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/projects/{value.json.project_id}/issues"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
        WITH BODY "{payload}"
    ADD EVENT Downloadgenericpackage
        WITH SOURCE_TOPIC "devops/gitlab/package/generic/get"
        WITH DESTINATION_TOPIC "devops/gitlab/package/generic/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/projects/{value.json.project_id}/packages/generic/{value.json.package_name}/{value.json.package_version}/{value.json.file_name}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
    ADD EVENT Createprojecthook
        WITH SOURCE_TOPIC "devops/gitlab/hook/create"
        WITH DESTINATION_TOPIC "devops/gitlab/hook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/projects/{value.json.project_id}/hooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuser | GET | `/user` | `devops/gitlab/user/get` | `devops/gitlab/user/get/response` |
| Triggerpipeline | POST | `/projects/{id}/trigger/pipeline` | `devops/gitlab/pipeline/trigger` | `devops/gitlab/pipeline/trigger/response` |
| Listreleases | GET | `/projects/{id}/releases` | `devops/gitlab/release/list` | `devops/gitlab/release/list/response` |
| Createissue | POST | `/projects/{id}/issues` | `devops/gitlab/issue/create` | `devops/gitlab/issue/create/response` |
| Downloadgenericpackage | GET | `/projects/{id}/packages/generic/...` | `devops/gitlab/package/generic/get` | `devops/gitlab/package/generic/get/response` |
| Createprojecthook | POST | `/projects/{id}/hooks` | `devops/gitlab/hook/create` | `devops/gitlab/hook/create/response` |

## Auth

1. Create a [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) (or project/group token) with appropriate scopes (`api` / `read_api` as needed), **or** obtain an OAuth 2.0 access token.
2. For pipeline triggers, create a [pipeline trigger token](https://docs.gitlab.com/ci/triggers/) on the project (separate from the PAT).
3. Set connector `BASE_ADDRESS` to `https://gitlab.com/api/v4` or your self-hosted `https://HOST/api/v4`.
4. Pass `private_token` on MQTT JSON payloads so the `PRIVATE-TOKEN` header resolves. For path params, also pass `project_id` / package path fields. For triggers, pass `trigger_token` and `ref`.
5. Store secrets in Hub / `GET SECRET "GITLAB_TOKEN"` (aliases `GITLAB_PRIVATE_TOKEN`, `GITLAB_ACCESS_TOKEN`). Never commit real credentials.
6. Successful smoke: `GET /user` → **HTTP 200** with `id`. Invalid tokens → **HTTP 401**.

## Example payloads

**getUser (smoke):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "private_token": "YOUR_GITLAB_PRIVATE_TOKEN"
}
```

**triggerPipeline:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "123",
  "trigger_token": "YOUR_PIPELINE_TRIGGER_TOKEN",
  "ref": "main"
}
```

**createIssue:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "title": "Coreflux alarm — Zone A",
  "description": "RMS exceeded limit"
}
```

**createProjectHook:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "url": "https://YOUR_PUBLIC_HTTPS_CALLBACK/gitlab-webhook",
  "push_events": true,
  "pipeline_events": true
}
```

## Server / inbound companion

`POST /projects/{id}/hooks` is **client-mode** registration (MQTT → GitLab). GitLab then POSTs events to your `url`. Receiving those callbacks into MQTT requires a separate companion `ENABLE_SERVER` connector — not included in `GitlabRestApi.lot`.

## Deploy notes

* Deploy `GitlabRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/gitlab](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/gitlab)

## Sources

* [GitLab REST API](https://docs.gitlab.com/ee/api/)
* [Authentication](https://docs.gitlab.com/api/rest/authentication/)
* [Pipeline triggers](https://docs.gitlab.com/api/pipeline_triggers/)
* [Releases](https://docs.gitlab.com/api/releases/)
* [Issues](https://docs.gitlab.com/api/issues/)
* [Generic packages](https://docs.gitlab.com/user/packages/generic_packages/)
* [Project webhooks](https://docs.gitlab.com/api/project_webhooks/)
* [OpenAPI v2](https://docs.gitlab.com/ee/api/openapi/openapi_v2.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.