Gitlab Port

Purpose

This is the Harbor reference integration for the GitLab REST API.

Use it when:

• building GitLab actions in Harbor
• extending the Dock / Hub GitLab entry
• teaching Codex or OpenClaw how to map a source-control and issue-tracking API into Harbor Ports and Harbor Actions without turning Harbor into a generic repo proxy

Harbor Port worksheet

Product

• Product: GitLab REST API
• Publisher slug: gitlab
• Publisher name: GitLab
• Category: Developer Tools
• Tags: gitlab, developer, merge-requests, issues, repositories

Safe Harbor Port metadata

• Kind: http_api
• Label: GitLab API
• Description: GitLab REST API connection managed locally through Harbor.
• Base URL: https://gitlab.com/api/v4/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

GitLab fits Harbor well because:

• the base API surface is stable and reviewable
• project discovery and merge-request reads are naturally bounded
• issue creation can stay on a fixed project-scoped path template
• bearer auth works cleanly with Harbor's local secret storage model

Good Harbor GitLab starter actions:

• fixed GET reads for project and merge-request inventory
• a bounded POST write for issue creation in a specific project
• typed query inputs for filters, ordering, and pagination
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for writes
• resultMode: "json_summary" for all starter actions

Avoid for now:

• giant admin or instance-management surfaces
• arbitrary GraphQL or raw search passthroughs
• merge, close, or delete mutation flows before review
• generic route forwarding across the whole GitLab API

Starter GitLab actions

Automatic read actions

• list-projects -> GET /projects
• list-merge-requests -> GET /merge_requests

Approval-friendly write actions

• create-issue -> POST /projects/{projectId}/issues

Why these actions

These routes fit Harbor's current safe model well because they:

• give operators a strong developer-workflow loop right away
• keep project targeting explicit through a bounded path template
• use typed filter inputs for reviewable query construction
• avoid turning Harbor into a generic GitLab client surface

Action Model notes

At execution time, callers should supply values by location:

• input.query for list-projects and list-merge-requests
• input.path.projectId for create-issue
• input.body for the issue payload

Example project listing request:

{
  "query": {
    "membership": true,
    "owned": false,
    "order_by": "last_activity_at",
    "sort": "desc",
    "simple": true
  }
}

Example merge request listing request:

{
  "query": {
    "state": "opened",
    "scope": "assigned_to_me",
    "per_page": 20,
    "page": 1
  }
}

Example issue creation request:

{
  "path": {
    "projectId": "gitlab-org%2Fgitlab"
  },
  "body": {
    "title": "Investigate Harbor import edge case",
    "description": "Opened from Harbor after review."
  }
}

For create-issue, keep the body bounded to fields you actually intend to support, such as:

• title
• description
• labels
• issue_type

Suggested operator workflow

1. Import the GitLab Dock entry from Dock / Hub.
2. Configure the local GitLab bearer token in Harbor Node.
3. Use list-projects to discover accessible projects.
4. Use list-merge-requests to inspect active review state.
5. Keep create-issue on require_approval unless there is a very clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing GitLab Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed GitLab routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored GitLab token
• widen GitLab into a generic repo or admin proxy
• add broad mutation coverage without review
• hide project targeting behind arbitrary route input

Current update strategy

For now, GitLab updates are manual:

• update the Dock / Hub GitLab integration document in apps/hub/catalog/integrations/gitlab/gitlab-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Auth notes

GitLab supports bearer authentication for:

• OAuth 2.0 tokens
• personal access tokens
• project access tokens
• group access tokens

Operators should configure the minimum token access needed for the project and issue flows they want to enable.

Official reference starting points

• GitLab REST API overview: https://docs.gitlab.com/api/rest/
• GitLab REST authentication: https://docs.gitlab.com/api/rest/authentication/
• Projects API: https://docs.gitlab.com/api/projects/
• Merge requests API: https://docs.gitlab.com/api/merge_requests/
• Issues API: https://docs.gitlab.com/api/issues/