GitLab Integration Guide

Overview

The GitLab integration allows your NINA workflows to interact with the GitLab API to search projects and users, manage issues and merge requests, and work with repository files. It supports both GitLab.com and self-hosted GitLab via configurable server URL, and works with either Personal Access Token (PAT) or OAuth2.

Status

Supported resources and operations:

• Project: Get, Get Issues, Search
• Issue: Create, Get, Update
• Merge Request: Get, Get All
• File: Get, Create
• User: Get, Get Projects

Credential Configuration

Authentication Methods

1) Access Token (Personal Access Token)

Field	Description	Example
Server	GitLab base URL (self-hosted use your base URL)	https://gitlab.com
User	Optional user hint
Access Token	Personal Access Token	glpat-xxx...

How to create a Personal Access Token on GitLab.com:

1. Go to GitLab.com → User menu → Edit profile → Access Tokens (or https://gitlab.com/-/profile/personal_access_tokens)
2. Name it (e.g., "GitLab Integration Tests")
3. Set an expiration date (recommended)
4. Select scopes (permissions) based on your needs, e.g.:
   • api (full API access, recommended for automation)
   • read_api (read-only API)
   • read_user, read_repository (granular read scopes)
5. Click "Create personal access token"
6. Copy the token immediately (you won't see it again!)

For self-hosted GitLab, use your instance base URL in Server.

2) OAuth2

Field	Description	Default
Server	GitLab base URL	https://gitlab.com
Client ID	OAuth2 client ID
Client Secret	OAuth2 client secret
Auth URL	Authorization URL	https://gitlab.com/oauth/authorize
Access Token URL	Access Token URL	https://gitlab.com/oauth/token
Scope	OAuth2 scopes	api,read_user,read_repository

Supported Resources and Operations

Project

Operation	Description
Get	Get a project by ID
Get Issues	List issues for a project (filters, sorting, pagination)
Search	Search across projects, issues, merge requests, users, commits, or code

Issue

Operation	Description
Create	Create a new issue
Get	Get a single issue by IID
Update	Update issue fields (state, title, description, labels, assignees)

Merge Request

Operation	Description
Get	Get a single merge request by IID
Get All	Get all merge requests (filters and pagination)

File

Operation	Description
Get	Get file contents by path (optionally by ref)
Create	Create a new file with commit metadata

User

Operation	Description
Get	Get user information
Get Projects	List projects for a user (filters and pagination)

Examples

Get Project Issues

{
  "integration_service": "gitlab",
  "resource": "project",
  "operation": "getIssues",
  "parameters": {
    "projectId": {"mode": "id", "value": "123"},
    "returnAll": false,
    "limit": 20,
    "additionalFields": {
      "state": "opened",
      "sort": "created_at",
      "order_by": "desc"
    }
  }
}

Search Projects

{
  "integration_service": "gitlab",
  "resource": "project",
  "operation": "search",
  "parameters": {
    "scope": "projects",
    "search": "security AND stars:>100",
    "returnAll": false,
    "limit": 10
  }
}

Create Issue

{
  "integration_service": "gitlab",
  "resource": "issue",
  "operation": "create",
  "parameters": {
    "projectId": {"mode": "id", "value": "123"},
    "title": "Bug: unexpected error in workflow",
    "description": "Steps to reproduce...",
    "additionalFields": {"labels": "bug,high-priority"}
  }
}

Best Practices

• Use least-privilege scopes for tokens; prefer read_api where possible.
• Prefer OAuth2 for multi-user or app contexts.
• For self-hosted, ensure Server points to your instance base URL.
• Respect rate limits and implement pagination with returnAll/limit.